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 is 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 functions in the API |
Request Body Parameters:
A denotes an applicable field, A* denotes required under certain conditions, N/A is not applicable, 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. Defaults to Cryptogram if omitted. | A | A | A |
| amount | The transaction amount. | N/A | N/A | * |
| merchantId | Merchant identifier assigned by the acquirer. | A* | N/A | A* |
| token | An existing TokenEx token that represents a PAN. | * | * | * |
| transactionType | Possible values: ECOM, AFT. | * | N/A | N/A |
| tokenReferenceId | If there is more than one network token, indicate which network token to use for this operation. | A* | A* | A* |
| billTo.firstName, billTo.lastName, billTo.address1, billTo.locality, billTo.administrativeArea, billTo.postalCode, billTo.country, billTo.email, billTo.phoneNumber | Coming soon Cardholder name, billing address, email, and phone number. Supports Visa's Digital Commerce Authentication Program (DCAP). | A* | N/A | N/A |
| deviceInfo.id, deviceInfo.ipAddress | Device identifier and IP address. Supports Visa's Digital Commerce Authentication Program (DCAP). | A* | 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. |
| provider | string | Identifies which provider serviced the request: CybersourceTMS or VisaTGS. |
| thirdPartyStatusCode | string | Reserved field; not currently populated. |
| networkResponse.tokenRequestorId | string | Opaque identifier associated with the domain to which the token belongs. Treat as opaque — do not persist or use in downstream logic. Identify tokens by token + tokenReferenceId. |
| networkResponse.tokenReferenceId | string | Unique reference identifier for the token generated. |
| networkResponse.messageId | string | Unique message identifier (GUID format), generated per response. |
| networkResponse.conversationId | string | Message identifier assigned for the entire conversation (GUID format). Useful when contacting support. |
| networkResponse.statusCode | string | The four-digit status code. |
| networkResponse.statusMessage | string | Human readable comments about the status. Null on success — read statusCode for the outcome. |
| networkResponse.decodedEncData.paymentBundle.bundleElements[].type | string enum | The type of the bundle element. Possible values: TOKEN, TOKEN_EXP, ECOM_CRYPTOGRAM, ECI. |
| networkResponse.decodedEncData.paymentBundle.bundleElements[].value | string or object | The value of the bundle element. |
Cryptogram generation is supported for Visa only. Token bundles (bundleMetaData: Token) are supported for all three brands.
- Visa Example Request
- Response
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, AFT]
"billTo": {
"firstName": "Alex",
"lastName": "Smith",
"address1": "123 Main St",
"locality": "Austin",
"administrativeArea": "TX",
"postalCode": "78701",
"country": "US",
"phoneNumber": "5125551234"
},
"deviceInfo": {
"id": "a1b2c3d4-device-id",
"ipAddress": "198.51.100.123"
}
}
{
"token": "476120FDallZ7718",
"success": true,
"referenceNumber": "21082510332941084676",
"error": "",
"message": "",
"provider": "CybersourceTMS",
"thirdPartyStatusCode": null,
"networkResponse": {
"tokenRequestorId": "a1b2c3d4e5f6",
"tokenReferenceId": "749f4d0d-4005-443e-9a66-0ea2d317b8f6",
"messageId": "3ffb2966-dc98-43da-80ab-f27874cf2208",
"conversationId": "f3c9430e-4e5f-4c8a-9526-ec8973470eea",
"statusCode": "0000",
"statusMessage": null,
"decodedEncData": {
"paymentBundle": {
"bundleElements": [
{ "type": "TOKEN", "value": "4761209400161814" },
{ "type": "TOKEN_EXP", "value": "2812" },
{ "type": "ECOM_CRYPTOGRAM", "value": "AgAAAAAAD5olyYoZAqIKQOwAAAA=" },
{ "type": "ECI", "value": "05" }
]
}
}
}
}