Handle Declines and Retries

Retrying a definitively declined charge — the same card, the same amount, immediately again — accomplishes nothing except annoying the customer and potentially triggering fraud detection on the gateway's side. This is exactly why Lesson 1 defined declined as a distinct, non-retryable outcome from error in the first place.

public class ProcessPaymentJob implements Queueable {
    private Id orderId;
    private Decimal amount;
    private String paymentToken;
    private Integer attemptNumber;

    public ProcessPaymentJob(Id orderId, Decimal amount, String paymentToken, Integer attemptNumber) {
        this.orderId = orderId;
        this.amount = amount;
        this.paymentToken = paymentToken;
        this.attemptNumber = attemptNumber;
    }

    public void execute(QueueableContext context) {
        PaymentResult result = new PaymentGatewayService().charge(amount, paymentToken);

        Order__c order = new Order__c(Id = orderId);
        if (result.success) {
            order.Status__c = 'Paid';
            order.Payment_Reference__c = result.gatewayTransactionId;
            update order;
        } else if (result.declined) {
            order.Status__c = 'Payment Declined';
            order.Decline_Reason__c = result.message;
            update order;
        } else if (attemptNumber < 3) {
            System.enqueueJob(new ProcessPaymentJob(orderId, amount, paymentToken, attemptNumber + 1));
        } else {
            order.Status__c = 'Payment Error';
            update order;
        }
    }
}

1. public class ProcessPaymentJob implements Queueable { — the same class as Lesson 3.
2. private Id orderId; — unchanged.
3. private Decimal amount; — unchanged.
4. private String paymentToken; — unchanged.
5. private Integer attemptNumber; — a new field, tracking how many times this charge has been attempted.
6. (blank line)
7. public ProcessPaymentJob(Id orderId, Decimal amount, String paymentToken, Integer attemptNumber) { — the constructor, extended with the new parameter.
8. this.orderId = orderId; — unchanged.
9. this.amount = amount; — unchanged.
10. this.paymentToken = paymentToken; — unchanged.
11. this.attemptNumber = attemptNumber; — stores the new field.
12. } — closes the constructor.
13. (blank line)
14. public void execute(QueueableContext context) { — runs when the job fires.
15. PaymentResult result = new PaymentGatewayService().charge(amount, paymentToken); — the callout, unchanged.
16. (blank line)
17. Order__c order = new Order__c(Id = orderId); — unchanged.
18. if (result.success) { — the success branch.
19. order.Status__c = 'Paid'; — unchanged.
20. order.Payment_Reference__c = result.gatewayTransactionId; — unchanged.
21. update order; — a final outcome — saved immediately.
22. } else if (result.declined) { — the decline branch.
23. order.Status__c = 'Payment Declined'; — unchanged.
24. order.Decline_Reason__c = result.message; — unchanged.
25. update order; — also final — never retried.
26. } else if (attemptNumber < 3) { — the new branch — an error, but under the retry limit.
27. System.enqueueJob(new ProcessPaymentJob(orderId, amount, paymentToken, attemptNumber + 1)); — Module 38's job-chaining, incrementing the attempt count.
28. } else { — an error, and the limit has been reached.
29. order.Status__c = 'Payment Error'; — gives up and records the final status.
30. update order; — saves it.
31. } — closes the four-way branch.
32. } — closes execute.
33. } — closes the class.

attemptNumber (Module 9's parameter passing, extended with one more field) tracks how many times this specific charge has been attempted — an error triggers Module 38's job-chaining pattern to retry, but only up to 3 attempts, after which it gives up and records the final error status.

if (justReadyForPayment) {
    System.enqueueJob(new ProcessPaymentJob(order.Id, order.Total__c, order.Payment_Token__c, 1));
}

1. if (justReadyForPayment) { — unchanged from Lesson 3.
2. System.enqueueJob(new ProcessPaymentJob(order.Id, order.Total__c, order.Payment_Token__c, 1)); — now passes 1 as the starting attemptNumber — the first attempt.
3. } — closes the if.

The trigger's original enqueue call now passes 1 as the starting attemptNumber — the first attempt — with ProcessPaymentJob itself handling every retry afterward via chaining, never requiring the original trigger to know or care about retries at all.