Get Payment Bundle
This method is used to retrieve a cryptogram for an existing TokenEx token that has a network token associated with it. The cryptogram will be required by your payment gateway or processor to process customer-initiated transactions (CIT) using a network token. A cryptogram is not typically required for subsequent subscription/recurring merchant-initiated transactions (MIT).
- Test URI: https://test-api.tokenex.com/v2/NetworkToken/GetPaymentBundle
- Prod US URI: https://api.tokenex.com/v2/NetworkToken/GetPaymentBundle
- Prod EU URI: https://eu1-api.tokenex.com/v2/NetworkToken/GetPaymentBundle
Required API Key Permissions: NetworkTokenizationGeneralAccess
Request Headers: Authentication and Authorization
* denotes a required field
HTTP Request Header | Description |
---|---|
tx-tokenex-id* | Like a username, this ID logically segments your tokenized data. |
tx-apikey* | Controls your access to individual function in the API |
Request Body Parameters:
A denotes an applicable field, A* denotes required under certain conditions, N/A is not applcable, and * denotes a required field under all conditions
Parameter | Description | Visa | Mastercard | AMEX |
---|---|---|---|---|
bundleMetaData | The type of bundle to be generated. Possible values: Cryptogram, Token, TokenCryptogram. Defaults to "Cryptogram". | A | A | A |
amount | The transaction amount. Up to 10 digits in ‘xxx.xx’ format. | N/A | N/A | * |
unpredictableNumber | A value to provide variability and uniqueness to the generation of a cryptogram (8-byte hex encoded string). *Required if the GenerateUnpredictableNumber flag is not set during on-boarding of MDES. | N/A | A* | N/A |
applicationTransactionCounter | *Only required for INAPP PresentationMode type (see Network Tokenize method). | A* | N/A | N/A |
cryptogramValue | Value of the CAVV cryptogram. *Required for CTAVV type cryptogram. N/A for TAVV and DTVV types. | A* | N/A | N/A |
merchantId | Merchant identifier assigned by the acquirer. *Required if available. | A* | N/A | A* |
ECI | EC indicator for liability shift. *Required when CTAVV type is cryptogram AND BundleMetaData is Cryptogram. | A* | N/A | N/A |
token | An existing TokenEx token that represents a PAN. | * | * | * |
transactionInitiationType | Possible values: CONSUMER, MERCHANT. | A | N/A | N/A |
transactionType | Possible values: ECOM, RECURRING, POS, AFT. | * | N/A | N/A |
Response Body Parameters:
Parameter | Type | Description |
---|---|---|
token | string | The token generated by TokenEx that references the sensitive data. |
success | bool | Indicator if the request was successfully processed by TokenEx. |
referenceNumber | string | TokenEx reference number for the transaction. |
error | string | TokenEx Error Code and human readable description. |
message | string | Human readable message about response from TokenEx. |
networkResponse.tokenRequestorId | string | TRID associated to the domain to which the token belongs (card brand specific). The format matches with the EMVCo Tokenization specifications. |
networkResponse.tokenReferenceId | string | Unique reference identifier for the token generated. |
networkResponse.encData | string | Base64 encoded and encrypted sensitive data. |
networkResponse.messageId | string | Unique message identifier (GUID format) of this command. |
networkResponse.conversationId | string | Message identifier assigned for the entire conversation (GUID format). Typically, it is generated by the initiator of the flow. |
networkResponse.statusCode | string | The four-digit status code. |
networkResponse.statusMessage | string | Human readable comments about the status. |
networkResponse.decodedEncData.paymentBundle.bundleMetaData | string enum | It indicates the type of the bundle returned. The valid values depend on the product use cases. Possible values are ECOM_TOKEN, ECOM_CRYPTOGRAM and ECOM_PAN. |
networkResponse.decodedEncData.paymentBundle.bundleElements[].type | string enum | It indicates the type of the bundle element. It has pre-defined values. Possible values are TOKEN, TOKEN_EXP (the format is 'YYMM'), ECOM_CRYPTOGRAM, ECI, PSN, TRACK2, PAN, PAN_EXP. |
networkResponse.decodedEncData.paymentBundle.bundleElements[].value | string or object | It contains the value of the bundle element. |
networkResponse.decodedEncData.cardData.panReferenceId | string | The unique reference ID (GUID format) of the real PAN. It is required except when PAN is provided. |
networkResponse.decodedEncData.cardData.paymentAccountReference | string | Globally unique reference of a cardholder’s PAN. It is commonly abbreviated as PAR. |
networkResponse.decodedEncData.cardData.cardSuffix | string | The last four digits of the real PAN. |
networkResponse.decodedEncData.cardData.panExpDate | string | The expiry date of the real PAN. The format is 'YYMM'. |
networkResponse.decodedEncData.cardData.cardHolderEmbossedName | string | The embossed name on the physical card. |
networkResponse.decodedEncData.cardData.cardCountryCode | string | A 2-character country code. The format is based on ISO 3166-1 alpha-2. |
networkResponse.decodedEncData.cardData.cardName | string | The name of the card. |
networkResponse.decodedEncData.cardData.cardType | string | The type of the card product (e.g., Credit, Debit). |
networkResponse.decodedEncData.cardData.cardLongDescription | string (64 max) | Description of card. |
networkResponse.decodedEncData.cardData.cardShortDescription | string (32 max) | Description of card. |
networkResponse.decodedEncData.cardData.coBranded | bool | It indicates if the card is a co-branded card. |
networkResponse.decodedEncData.cardData.coBrandName | string | The card co-brand name. It is required if isCoBranded is set to true. |
networkResponse.decodedEncData.cardData.cardTypeIndicator | string [] | These are indicators (Boolean values) associated with the card. The expected values are PRIVATE_LABEL. |
networkResponse.decodedEncData.cardData.expDataPrinted | bool | It indicates if the expiration date is printed on the card or not. |
networkResponse.decodedEncData.cardData.cvv2Printed | bool | It indicates if the cvv2 is printed on the card or not. |
POST /v2/NetworkToken/GetPaymentBundle HTTP/1.1
Host: test-api.tokenex.com
tx-apikey: YourAPIKey
tx-tokenex-id: YourTokenExId
Content-Type: application/json
{
"token": "476120FDallZ7718", // Required
"transactionType": "ECOM" // Required for Visa [ECOM, RECURRING, POS, AFT]
}
{
"token": "476120FDallZ7718",
"networkResponse": {
"tokenRequestorId": "12345678901",
"tokenReferenceId": "749f4d0d-4005-443e-9a66-0ea2d317b8f6",
"encData": "eyJraWQiOiJURVhcLzAxIiwiZW5jIjoiQTEyOENCQy1IUzI1NiIsImFsZyI6IlJTQTFfNSJ9.Nghq0VUoMqS1S53K30J6cmdjbP59XQMy_csilNMe_SQGhrL5H4ojR6U3z3dSAQRFYc9jT3hwtN5qkADBuqSMpgkOCFO4WfV8-2MzKyn8kdupT2C8wzPVAHxJdfzDTXfPn2MU4JCCYy9tFUSI4-8JHL6R--jlKvcbfoSYg1XS23ZhY-z7VmuxH5-ectCGc56wBRW_gYgbRZ26pYWtPkYLX8AMl86WhZIk5ZXnxldidwVZlim1WnDcmfEENHpiKUhRyuFtKkEZO7tiQcTHJuFgVS_jo0SkdQIVEdp-CIB9D7jWteZLDWBe8kI_WNqR5KSW_hO54mpZ8Gvmqeae6-HZ6w.58JQ_C00MrQVSWrqd8xcGA.FaDcRHedDXLKszPp31zA3O3_9JCvrEuYNsM4BcWDbE_UnqvrhHFOoStNaSA9Ht066fXzrmPfGRfdSuv6Au5oa_gJrlgy0K3NITSpg9EOBEPJWx0KcPRymIcd5nT_5Gt47rYcLjZDqW0UjiOdU793VOXnqisFSWsBXL_eHhpx_8YW__Zw-w-SCdq4Ux9f0iyM5DFvsHHqFlTYIOkHI6YvNX2dgBsww6a7zmJqWjR4g_Z5Z8Ac8mwVRgoyPjiSpCgAKbywpBgu4lB8Fe18oTVARY2wX8hT1ZMR94qa4XHpSDmejNbNd10yLRZYM-5WMUtx1vr_7kGiSA8ecP_JwRDrRhXLyjlmxh_D-HK3PdfeHEIS5NIr1I3HqW0NERXN7Jch.msSkliU8bbBaohAtAkEzjA",
"decodedEncData": {
"paymentBundle": {
"bundleMetadata": "ECOM_CRYPTOGRAM",
"bundleElements": [
{
"type": "TOKEN",
"value": "4761209400161814"
},
{
"type": "TOKEN_EXP",
"value": "2212"
},
{
"type": "ECOM_CRYPTOGRAM",
"value": "AgAAAAAAD5olyYoZAqIKQOwAAAA="
},
{
"type": "ECI",
"value": "07"
}
]
},
"cardData": {
"panReferenceId": null,
"paymentAccountReference": null,
"cardSuffix": null,
"panExpDate": null,
"cardHolderEmbossedName": null,
"cardCountryCode": null,
"cardName": null,
"cardType": null,
"cardLongDescription": null,
"cardShortDescription": null,
"coBranded": false,
"coBrandName": null,
"cardTypeIndicator": null,
"expDataPrinted": false,
"cvv2Printed": false
}
},
"paymentBundle": null,
"messageId": "3ffb2966-dc98-43da-80ab-f27874cf2208",
"conversationId": "f3c9430e-4e5f-4c8a-9526-ec8973470eea",
"statusCode": "0000",
"statusMessage": null
},
"referenceNumber": "",
"success": true,
"error": "",
"message": ""
}
Updated 10 months ago