Building a Synchronous Gateway Adapter

In synchronous payment configurations, the Salesforce payment platform sends transaction information to the gateway, and then waits for a gateway response that contains the final transaction status. Salesforce will create a transaction only if the transaction is successful in the gateway.

A synchronous gateway adapter implements the PaymentGatewayAdapter Interface. In this topic, we’ll break down a sample asynchronous adapter by looking at PaymentGatewayAdapter, and then the processRequest class, which drives most of the communication between the payment platform and the payment gateway.

Payment gateway adapters can’t make future calls, external callouts using System.Http, asynchronous calls, queueable calls, or execute DMLs using SOQL.

Note

PaymentGatewayAdapter

All synchronous gateway must implement the PaymentGatewayAdapter interface. All PaymentGatewayAdapters are required to implement the processRequest method.

1global with sharing class SampleAdapter implements commercepayments.PaymentGatewayAdapter {
2    global SampleAdapter() {}
3    
4    global commercepayments.GatewayResponse processRequest(commercepayments.paymentGatewayContext gatewayContext) {
5    }
6}

Processing an Initial Payment Request

When the payments platform receives a payments API request, it passes the request to your gateway adapter for further evaluation. The adapter begins the request evaluation process by calling the processRequest method, which represents the first step in a synchronous payment flow. We can break the processRequest implementation into three parts.

First, it builds a payment request object that the gateway can understand.

1commercepayments.RequestType requestType = gatewayContext.getPaymentRequestType();
2if (requestType == commercepayments.RequestType.Capture) {
3   req.setEndpoint('/pal/servlet/Payment/v52/capture');
4    body = buildCaptureRequest((commercepayments.CaptureRequest)gatewayContext.getPaymentRequest());
5} else if (requestType == commercepayments.RequestType.ReferencedRefund) {
6    req.setEndpoint('/pal/servlet/Payment/v52/refund');
7    body = buildRefundRequest((commercepayments.ReferencedRefundRequest)gatewayContext.getPaymentRequest());
8}

Then, the adapter sends the request to the payment gateway.

1req.setBody(body);
2req.setMethod('POST');
3commercepayments.PaymentsHttp http = new commercepayments.PaymentsHttp();
4HttpResponse res = null;
5try {
6    res = http.send(req);
7} catch(CalloutException ce) {
8    commercepayments.GatewayErrorResponse error = new commercepayments.GatewayErrorResponse('500', ce.getMessage());
9    return error;
10}

Finally, the adapter creates a response object to store data from the gateway’s response. The type of response object will vary based on whether you originally made a payment capture request or a refund request.

1if ( requestType == commercepayments.RequestType.Capture) {
2   // Refer to the end of this doc for sample createCaptureResponse implementation
3    response =  createCaptureResponse(res);
4} else if ( requestType == commercepayments.RequestType.ReferencedRefund) {
5    response =  createRefundResponse(res);
6}
7return response;

Apex Developer Guide

Building a Synchronous Gateway Adapter

PaymentGatewayAdapter

Processing an Initial Payment Request