Advanced 25 min read

Design the Payment Flow

By the end of this lesson, you'll be able to:

Design a payment flow that respects the trigger-callout constraint from Modules 36 and 38
Define what "success," "decline," and "error" mean for this specific integration
Sketch the classes needed before writing any code

Prerequisites: Module 38: "Asynchronous Apex"

What we're building

"When an Order__c's Status__c is set to 'Ready for Payment', charge
the customer's payment method through an external payment gateway
and update the Order with the result — without ever running the
callout synchronously inside the trigger itself."

This is a direct, deliberate application of Modules 36 and 38's central lesson: a trigger can never make a synchronous callout, so this entire feature is designed around Queueable Apex from the first sketch, not bolted on afterward.

Defining the three outcomes precisely

Success — the gateway confirms the charge; Order__c.Status__c becomes 'Paid', Payment_Reference__c stores the gateway's transaction Id.
Decline — the gateway explicitly rejects the charge (insufficient funds, expired card); Status__c becomes 'Payment Declined', with the decline reason stored for the customer service team.
Error — the callout itself fails (network issue, gateway downtime); Status__c becomes 'Payment Error', distinct from a decline, since this is a technical failure worth automatically retrying, not a definitive "no."

This is Module 37's "Handle Errors and Timeouts" distinction (a response vs no response), now built into the actual business status model from the very start.

Sketching the classes

PaymentGatewayService — makes the actual callout, returns a result
ProcessPaymentJob — Queueable wrapper, called from the trigger
OrderTriggerHandler — thin, enqueues ProcessPaymentJob

This is the exact three-layer shape from Module 26's CRM Extension and Module 35's dashboard — trigger/handler, a service doing the real work, and (here) a Queueable layer in between specifically because of the async requirement.

Exercise

As a comment, explain why "Payment Error" is a distinct status from "Payment Declined" rather than being merged into one "Failed" status.

Show hint

Think about whether each one should be automatically retried.

APEX

Design the Payment Flow Quiz

1. Why is this entire feature designed around Queueable Apex from the very first sketch?

A trigger can never make a synchronous callout directly, so the async requirement shapes the whole design from the start Queueable Apex is required for every trigger, regardless of what it does Synchronous callouts are always slower than asynchronous ones This is an arbitrary stylistic choice

My Notes

Questions about this lesson

No questions yet — be the first to ask.

Summary

This module builds a payment-processing feature triggered when an Order is marked ready for payment — and because the callout can't run synchronously from a trigger, the whole flow is designed around Module 38's Queueable Apex from the start.

← Choosing the Right Async Tool Build the Callout Service →