Network Tokenisation
Network Token Generation
If you want to store the credit card information under network token, you need to send a request with referencedOrderIdof the transaction which captured consumer's consent to store their sensitive credit card information under a token.
The following JSON document represents an example of a request including your own token value:
{
"requestType": "ReferencedOrderPaymentTokenizationRequest",
"referencedOrderId": "C-8a820c97-03e5-4045-83ff-a9b5976ab0c9",
"storeId": "330995118",
"createToken": {
"value": "TEST125"
}
}
A network token is provisioned by the Gateway for the card data used in submitted referencedOrderIdand linked to the Token value you have provided in the previous request. The call to retrieve a token from the schemes is made by our system automatically.
{
"clientRequestId": "2838649",
"apiTraceId": "YbsATprutgkfwMXM9131BQAAA4E",
"requestStatus": "SUCCESS",
"requestTime": 1639645262162,
"paymentToken": {
"value": "TEST125",
"reusable": true,
"declineDuplicates": false,
"last4": "3006",
"brand": "MASTERCARD",
"accountVerification": false,
"type": "PAYMENT_CARD"
}
}
If you do not wish to define your own ‘paymentToken’ value in your token provisioning request, the Gateway will generate this value for you and you will obtain it in the API response.
The following json document represents an example of a request without submitted ‘paymentToken’:
{
"requestType": "ReferencedOrderPaymentTokenizationRequest",
"referencedOrderId": "C-8a820c97-03e5-4045-83ff-a9b5976ab0c9",
"storeId": "330995118",
"createToken": {
}
}
The following json document represents an example of the response including generated ‘paymentToken’:
{
"clientRequestId": "2838649",
"apiTraceId": "YbsAhUr75THtfN2sdqvVhQAAA8E",
"requestStatus": "SUCCESS",
"requestTime": 1639645317009,
"paymentToken": {
"value": "FF2E6982-BA39-477D-A486-D6970846DE80",
"reusable": true,
"declineDuplicates": false,
"last4": "3006",
"brand": "MASTERCARD",
"accountVerification": false,
"type": "PAYMENT_CARD"
}
}
Initiate payment transactions using Network Token and Cryptogram
Network token and a cryptogram will be provided in the response after you submitted the following request to the Gateway:
POST /v2/services/payment-tokens/{paymentTokenValue}/cryptogram
{
"storeId": "330995118"
}
Below is the example of the response including associated credit card details, network token value and token cryptogram.
{
"clientRequestId": "2838649",
"apiTraceId": "YbsBzwSL38Qqaq8aJ53@hwAAAhM",
"requestStatus": "SUCCESS",
"requestTime": 1639645647039,
"networkToken": {
"value": "5204736200204958",
"expiryMonth": "01",
"expiryYear": "25",
"cardLast4": "3006",
"brand": "MASTERCARD",
"cryptogram": "AGX1lvbYlypcAAFHV22IGgADFA=="
}
}
Received data can be used to trigger a sale or preauth request.
Please note, that in case you are located in European Union or India, you are mandated to perform 3-D Secure authentication for every eCommerce transaction. In case you are using network tokens with such transaction, you need to include "tokenCryptogram" element in all sale/preauth requests for all 3DS protocols (2.1 and 2.2).
The following json document represents an example of a Sale transaction using network token and token cryptogram with included 3DS v2 call:
{
"requestType": "PaymentCardSaleTransaction",
"storeId": "330995118",
"transactionAmount": {
"total": "178.00",
"currency": "INR"
},
"transactionOrigin": "ECOM",
"paymentMethod": {
"paymentCard": {
"number": "5204736200113910",
"securityCode": "006",
"cardFunction": "DEBIT",
"expiryDate": {
"month": "12",
"year": "24"
}
}
},
"authenticationRequest": {
"authenticationType": "Secure3DAuthenticationRequest",
"termURL": "https://test.ipg-online.com/webshop/simulator/secure3d/return",
"methodNotificationURL": "https://test.test/notify",
"messageCategory": "01"
},
"order": {
"tokenCryptogram": "AGX1lvbYlypcAAFHV22IGgADFA=="
}
}
In the response you will obtain authentication parameters, what should be used in the next call to the Gateway.
The complete process how to perform 3-D Secure is described here: 3-D Secure
It is important to include the element tokenCryptogram in your PATCH request to the original transaction, once you received the response from the ACS about the successful authentication:
The following JSON document represents an example of the response you will receive after successfully authenticated and authorized transaction using token cryptogram:
{
"clientRequestId": "2838649",
"apiTraceId": "YbsG@MItojOb3pFHVNWOygAAA7w",
"ipgTransactionId": "84385055093",
"orderId": "R-f98d11be-9bea-419b-9645-1c4404971c10",
"transactionType": "SALE",
"paymentToken": {
"reusable": true,
"declineDuplicates": false,
"brand": "MASTERCARD",
"type": "PAYMENT_CARD"
},
"transactionOrigin": "ECOM",
"paymentMethodDetails": {
"paymentCard": {
"expiryDate": {
"month": "12",
"year": "2028"
},
"cardFunction": "DEBIT",
"bin": "520473",
"last4": "3910",
"brand": "MASTERCARD"
},
"paymentMethodType": "PAYMENT_CARD"
},
"terminalId": "00001115",
"merchantId": "470000032001125",
"transactionTime": 1639646716,
"approvedAmount": {
"total": 178,
"currency": "INR",
"components": {
"subtotal": 178
}
},
"transactionStatus": "APPROVED",
"approvalCode": "Y:006973:4385055093:PPX :121609639289",
"secure3dResponse": {
"responseCode3dSecure": "1"
},
"processor": {
"referenceNumber": "121609639289",
"authorizationCode": "006973",
"responseCode": "00",
"responseMessage": "Function performed error-free",
"avsResponse": {
"streetMatch": "NO_INPUT_DATA",
"postalCodeMatch": "NO_INPUT_DATA"
}
}
}
Display Stored Network Token Details
For cases when you would like to get information about the network token associated with your store and token value, you can submit a GET request with referenced paymentTokenValue:
GET /v2/services/payment-tokens/{paymentTokenValue}
The following json document represents an example of API response:
{
"clientRequestId": "2838649",
"apiTraceId": "YbsJPn4TVn0bWRZH6wmlegAAAuc",
"requestStatus": "SUCCESS",
"requestTime": 1639647550653,
"paymentToken": {
"value": "FF2E6982-BA39-477D-A486-D6970846DE80",
"reusable": false,
"brand": "MASTERCARD",
"type": "PAYMENT_CARD"
},
"networkToken": {
"value": "520473******4958",
"expiryMonth": "01",
"expiryYear": "25"
}
}
Store payment information without performing a transaction at the same time
For cases where you would prefer to store credit card details without performing a transaction at the same time, you can submit a request type: PaymentCardPaymentTokenizationRequestincluding credit card details as on example below, and accountVerification element set to false:
Please note, that you have to obtain customer’s consent and perform additional strong customer authentication via 3-D Secure before submitting the request to store card credentials.
POST /v2/services/payment-tokens
{
"requestType": "PaymentCardPaymentTokenizationRequest",
"storeId": "330995118",
"paymentCard": {
"number": "520473******3006",
"expiryDate": {
"month": "12",
"year": "24"
},
"securityCode": "XXX"
},
"createToken": {
},
"accountVerification": false
}
Updated 19 days ago
