Tokenization Service Apex Class Implementation

Encryption for Tokenized Payment Methods

CommercePayments uses Salesforce field encryption to securely store gateway token values on customer payment method entities such as DigitalWallet, CardPaymentMethod, and AlternativePaymentMethod.

CardPaymentMethod and DigitalWallet contain the GatewayTokenEncrypted field, available in API v52.0 and later, and the GatewayToken field, available in API v48.0 and later. Both fields store gateway token values. However, GatewayTokenEncrypted uses Salesforce Classic Encryption for Custom Fields to securely encrypt the token. GatewayToken doesn't use encryption. To ensure secure tokenization, we recommend using GatewayTokenEncrypted on your DigitalWallets and CardPaymentMethods. The AlternativePaymentMethod object uses a GatewayToken field for token storage, however, this field is encrypted on AlternativePaymentMethods.

In API version 52.0 and later, CardPaymentMethods and DigitalWallets can’t store values for GatewayTokenEncryption and GatewayToken at the same time on the same record. If you try to assign one while the other exists, Salesforce throws an error.

Your payment gateway adapter uses the PaymentMethodTokenizationRequest and PaymentMethodTokenizationResponse classes to retrieve a gateway token from the payment gateway, encrypt it in Salesforce, and store the value on a payment method entity. Let's see how we can configure these classes in our payment gateway adapter.

Implementing Tokenization Classes in Your Gateway Adapter

The following code is used within your PaymentGatewayAdapter Apex class.

Gateway tokens are created and encrypted when the GatewayResponse class's processRequest method receives a tokenization request. If the request type is Tokenize, GatewayResponse calls the createTokenizeResponse method and passes an instance of the PaymentMethodTokenizationRequest class. The passed PaymentMethodTokenizationRequest object contains the address and cardPaymentMethod information that the payment gateway needs to manage the tokenization process. For example:

1global commercepayments.GatewayResponse processRequest(commercepayments.paymentGatewayContext gatewayContext) {
2         commercepayments.RequestType requestType = gatewayContext.getPaymentRequestType();
3         commercepayments.GatewayResponse response;
4         try
5         {
6             if (requestType == commercepayments.RequestType.Tokenize) {
7                     response = createTokenizeResponse((commercepayments.PaymentMethodTokenizationRequest)gatewayContext.getPaymentRequest());
8             }
9             //Add other else if statements for different request types as needed.
10             return response;
11         }
12         catch(SalesforceValidationException e)
13         {
14              commercepayments.GatewayErrorResponse error = new commercepayments.GatewayErrorResponse('400', e.getMessage());
15              return error;
16         }
17     }

Configure the createTokenizeResponse method to accept an instance of PaymentMethodTokenizationRequest and then build an instance of PaymentMethodTokenizationResponse based on the values that it receives from the payment gateway. The tokenizeResponse contains the results of the gateway's tokenization process, and if successful, the tokenized value. In this example, we call the setGatewayTokenEncrypted method to set the tokenized value in our tokenization response.

1public commercepayments.GatewayResponse createTokenizeResponse(commercepayments.PaymentMethodTokenizationRequest tokenizeRequest) {
2         commercepayments.PaymentMethodTokenizationResponse tokenizeResponse = new commercepayments.PaymentMethodTokenizationResponse();
3         tokenizeResponse.setGatewayTokenEncrypted(encryptedValue);
4         tokenizeResponse.setGatewayTokenDetails(tokenDetails);
5         tokenizeResponse.setGatewayAvsCode(avsCode);
6         tokenizeResponse.setGatewayMessage(gatewayMessage);
7         tokenizeResponse.setGatewayResultCode(resultcode);
8         tokenizeResponse.setGatewayResultCodeDescription(resultCodeDescription);
9         tokenizeResponse.setSalesforceResultCodeInfo(resultCodeInfo);
10         tokenizeResponse.setGatewayDate(system.now());
11         return tokenizeResponse;
12     }

The setGatewayTokenEncrypted method is available in Salesforce API v52.0 and later. It uses Salesforce classic encryption to set the encrypted token value that you can store in GatewayTokenEncrypted on a CardPaymentMethod or DigitalWallet, or in GatewayToken on an AlternativePaymentMethod. We recommend using setGatewayTokenEncrypted to ensure your tokenized payment method values are encrypted and secure.

1/** @description Method to set Gateway token to persist in Encrypted Text */
2     global void setGatewayTokenEncrypted(String gatewayTokenEncrypted) {
3         if (gatewayTokenSet)  {
4             throwTokenError();
5         }
6         this.delegate.setGatewayTokenEncrypted(gatewayTokenEncrypted);
7         gatewayTokenEncryptedSet = true;
8     }

If the instantiated class already has a gateway token, setGatewayTokenEncrypted throws an error.