Tokenization Service API

The credit card tokenization process replaces sensitive customer information with a one-time algorithmically generated number, called a token, to use during the payment transaction. Salesforce stores the token and then uses that token as a representation of the credit card used for transactions. The token stores information about the credit card without storing sensitive customer data such as credit card numbers. To add tokenization capabilities to your payment services, implement our Tokenization API.

In a typical tokenization process, the payments platform accepts customer payment method data and passes it to a remote token service server on the payment gateway, outside of Salesforce. The server provides the tokenized value for storage on the platform. For example, a customer provides a credit card number of 4111 1111 1111 1234. The token server stores this value, associates it with a token of 2537446225198291, and sends that token for storage on the platform.

During communication with the merchant, the merchant sends the 2537446225198291 token to the token server. The token server confirms that it matches the customer’s token, and authorizes the merchant to perform the transaction against the customer’s card.

The Commerce Payments Tokenization API accepts credit card information and uses the external payment gateway configured through the customer's Salesforce org to tokenize the card information. It then returns the tokenization representation. The API then saves the token in CardPaymentMethod.

Call the tokenization service by making a POST request to this endpoint.

1/commerce/payments/payment-methods

The Tokenization Service accepts these request parameters from payment and related entities.

Parameter	Required or Optional	Details
cardPaymentMethod	Some of the related fields for this parameter, shown in the sample request of this topic, are required. See `CardPaymentMethod`	Details of the credit card to be tokenized. For Type, see `CardPaymentMethod`
accountId	Optional	Salesforce Account ID of the card owner.
address	Optional	Address information of the customer who owns the credit card payment method being tokenized.
paymentGatewayId	Required	The external payment gateway related to the tokenization server.
email	Optional	Fraud parameter.
ipAddress	Optional	Fraud parameter.
macAddress	Optional	Fraud parameter.
phone	Optional	Fraud parameter.
additionalData	Optional	Any additional data required by the gateway to tokenize a credit card payment method.

Sample Request and Response

This sample request provides a customer's credit card information for tokenization. Some optional parameters are left blank.

1{
2    "cardPaymentMethod": {
3        "cardHolderName":"Carol Smith",
4        "expiryMonth": "05",
5        "expiryYear": "2025", 
6        "startMonth": "",
7        "startYear": "",
8        "cvv": "000",
9        "cardNumber": "4111111111111111",
10        "cardCategory": "Credit",
11        "cardType": "Visa",
12        "nickName": "",
13        "cardHolderFirstName": "Carol",
14        "cardHolderLastName": "Smith",
15        "email" : "csmith@example.com",
16        "comments" : "",
17        "accountId": "000XXXXXXXX"
18    },
19    "address":{
20        "street": "128 1st Street",
21        "city": "San Francisco",
22        "state": "CA",
23        "country": "USA",
24        "postalCode": "94015",
25        "companyName": "Salesforce"
26    },
27    "paymentGatewayId" : "000XXXXXXXX",
28    "email": ""
29    "ipAddress": "",
30    "macAddress": "",
31    "phone": "",
32   
33    "additionalData":{
34         //add additional information if needed
35        "key1":"value1",
36        "key2":"value2",
37        "key3":"value3",
38        "key4":"value4",
39        "key5":"value5"
40    }
41}

A successful tokenization response updates the payment method and provides information about the gateway response and any payment gateway logs.

1{
2  "paymentMethod": {
3    "id": "03OR0000000xxxxxxx",
4    "accountId" : "001xx000000xxxxxxx",
5    "status" : "Active"
6  },
7  "gatewayResponse" : {
8    "gatewayResultCode": "00",
9    "gatewayResultCodeDescription": "Transaction Normal",
10    "gatewayDate": "2020-12-08T04:03:20.000Z",
11    "gatewayAvsCode" : "7638788018713617",
12    "gatewayMessage" : "8313990738208498",
13    "salesforceResultCode": "Success",
14    "gatewayTokenEncrypted" : "SF701252"
15  }
16  "paymentGatewayLogs" : [ {
17    "createdDate" : "2020-12-08T04:03:20.000Z",
18    "gatewayResultCode" : "00",
19    "id" : "0XtR0000000xxxxxxx",
20    "interactionStatus" : "NoOp"
21  } ],
22}

Apex Developer Guide

Tokenization Service API

Sample Request and Response