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 lets you store information about the credit card without actually storing sensitive customer data such as credit card numbers in Salesforce. Implement our Tokenization API to add tokenization capabilities to your payment services.

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 CardPayementMethod.

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

Endpoint

1/commerce/payments/payment-method/tokens/

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

Table 1. Tokenization Service Input Parameters
Parameter	Required or Opitonal	Details
`1cardPaymentMethod: { 2 "cardHolderName":"", 3 "expiryMonth":"", 4 "expiryYear":"", 5 "startMonth":"", 6 "startYear":"", 7 "cvv":"", 8 "cardNumber":"", 9 "cardCategory":"", 10 "cardType":"", 11 "nickName":"", 12 "cardHolderFirstName":"", 13 "cardHolderLastName":"", 14 "email":"", 15 "comments":"" 16}`	Some Required. See `CardPayementMethod`	Details of the credit card to be tokenized. For Type, see `CardPayementMethod`
accountId	Optional	Salesforce Account ID of the card owner.
`1"address":{ 2 "street":"", 3 "city":"", 4 "state":"", 5 "country":"", 6 "postalCode":"", 7 "companyName":"", 8}`	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. Note that 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}

Sample Success Response

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