Synchronous versus asynchronous payment gateway adapters
Key Takeaway
A synchronous adapter gets the final status in one round trip. An asynchronous adapter gets an acknowledgment first and the final status later, so it also needs processNotification and a webhook.
A payment gateway adapter is an Apex class that sits between the Salesforce payments platform and an external payment gateway. The adapter translates Salesforce payment requests into calls the gateway understands and turns gateway replies back into results Salesforce can use. The timing of the final status decides which interfaces, methods and setup the adapter needs.
How the two flows differ
Both adapter types start the same way. When the payments platform receives a payments API request, it passes the request to the adapter. The processRequest method is the first step in both synchronous and asynchronous flows.
In a synchronous flow, the platform sends the transaction to the gateway and waits for a response that contains the final status. The adapter gets that status in one round trip. Salesforce creates a transaction only if the transaction succeeds in the gateway, so there is never a pending transaction.
In an asynchronous flow, the gateway first replies with only a quick acknowledgment, so the platform creates a pending transaction. When the gateway later sends a notification with the final status, the platform updates the transaction's status.
Ana pays $60 for a pair of shoes. With a synchronous gateway, the platform waits, and the gateway's response says the payment succeeded. Salesforce then creates the transaction. If the response had said the payment failed, Salesforce would not have created one. With an asynchronous gateway, the first reply is only an acknowledgment. Salesforce now holds a pending transaction, and the gateway hasn't said yet whether the payment succeeded. When the gateway's notification arrives with the final status, the platform updates that transaction's status.