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.

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}