Skip to main content

Tokenize

This method is used to request that a network token be provisioned for a given primary account number (PAN). You will need to provide your TokenEx ID and authorized API key, the PAN or an existing TokenEx token, and the desired TokenEx token scheme if the PAN is used.

Required API Key Permissions: NetworkTokenizationGeneralAccess

Request Headers: Authentication and Authorization

* denotes a required field
HTTP Request HeaderDescription
tx-tokenex-id*Like a username, this ID logically segments your tokenized data.
tx-apikey*Controls your access to individual function in the API
tx-tokenize[Boolean]. True indicates that a TokenEx token should be generated for the PAN. True by default. Can be set to false if existing TokenEx token is provided.
tx-token-scheme*Either the name or the numerical value of the Token Scheme to be used
tx-data-encryptedtrue/false
This header is used to indicate whether the Data and CVV fields have been encrypted using browser-based encryption

Request Body Parameters:

* Denotes a Required Field. Some optional fields may be required for certain card brands. Please read descriptions for full details.

ParameterTypeDescription
data*stringEither the PAN or an existing TokenEx token that represents a PAN.
expirationDate*stringExpiration date for the PAN.
cvvstringThe security code on the back of the physical card.
cardholderBillingAddress.line1String (140)Address line 1.
cardholderBillingAddress.line2String (140)Address line 2.
cardholderBillingAddress.countryString (2)Country code in ISO 3166-1 alpha-2 format.
cardholderBillingAddress.stateString (3)State code in ISO 3166-2 format.
cardholderBillingAddress.cityString (100)Name of the cardholder's city.
cardholderBillingAddress.zipString (16)Cardholder's postal code.

Response Body Parameters:

ParameterTypeDescription
tokenstringThe token generated that references the sensitive data.
successboolIndicator if the request was successfully processed.
referenceNumberstringReference number for the transaction.
errorstringError code and human readable description.
messagestringHuman readable message about the response.
networkResponse.tokenRequestorIdstringOpaque 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.tokenReferenceIdstringUnique reference identifier for the token generated.
networkResponse.tokenizationDecisionstring enumThe tokenization decision: APPROVED, AUTH_REQ, PCI_APPROVED, DECLINED.
networkResponse.messageIdstringUnique message identifier (GUID), generated per response.
networkResponse.conversationIdstringMessage identifier (GUID) assigned for the entire conversation — useful when contacting support.
networkResponse.statusCodestringThe four-digit status code.
networkResponse.statusMessagestringHuman readable comments about the status; null on success — read statusCode for the outcome.
networkResponse.tokenStatestring enumThe current state of the token, as returned by the token provider.
networkResponse.cvv2VerificationCodestring enumIndicates whether the security code (CVV/CVC) was verified by the issuer during the provisioning request. Supported only for Visa network tokens. Values: MATCH, NO_MATCH, NOT_SUPPORTED, SKIPPED.
networkResponse.addressVerificationCodestring enumIndicates whether the billing address was verified by the issuer during the provisioning request. Supported only for Visa network tokens. Values: MATCH, PARTIAL_MATCH, PARTIAL_MATCH_FORMAT_UNSUPPORTED, NO_MATCH, NOT_SUPPORTED, SKIPPED.
networkResponse.encData.paymentBundle.bundleElements\[]arrayThe elements of the payment bundle: TOKEN, TOKEN_EXP. The cryptogram itself is retrieved via Get Payment Bundle.
networkResponse.encData.cardData.paymentAccountReferencestringGlobally unique reference of a cardholder’s PAN (PAR).
networkResponse.encData.cardData.cardSuffixstringThe last four digits of the real PAN.
networkResponse.encData.cardData.panExpDatestringThe expiry date of the real PAN. The format is YYMM.
networkResponse.encData.cardData.coBrandedboolIndicates if the card is a co-branded card.
networkResponse.encData.cardData.coBrandNamestringThe card co-brand name.
networkResponse.encData.cardData.expDataPrintedboolIndicates if the expiration date is printed on the card.
networkResponse.encData.cardData.cvv2PrintedboolIndicates if the CVV2 is printed on the card.
networkResponse.cardMetaData.termsAndConditionsUrlstringThe website URL which is used to describe the terms and conditions.
networkResponse.cardMetaData.cardArtUrlstringThe website URL which is used to present the card’s art image.
networkResponse.cardMetaData.cardForegroundColorstringThe foreground color of the card specified as a CSS style RGB value.
networkResponse.cardMetaData.issuerData.issuerNamestringThe name of the card issuer.
networkResponse.cardMetaData.issuerData.issuerEmailstringThe customer service email address of the issuing bank.
networkResponse.cardMetaData.issuerData.issuerWebsitestringThe customer service website of the issuing bank.
networkResponse.cardMetaData.issuerData.customerServiceTelephonestringThe customer service phone number of the issuing bank.
networkResponse.cardMetaData.cardAssets\[].guidstringUnique identifier (GUID format) of the asset.
networkResponse.cardMetaData.cardAssets\[].assetTypestring enumThe type of asset: COMBINED_BACKGROUND, ICON_ISSUER, ICON_BRAND, ICON.
POST /v2/NetworkToken/Tokenize HTTP/1.1
Host: test-api.tokenex.com
tx-apikey: YourAPIKey
tx-tokenex-id: YourTokenExID
tx-tokenize: true
tx-token-scheme: PCI
Content-Type: application/json

{
"data": "4761209980007718",
"expirationDate": "2812",
"cvv": "123",
"cardholderBillingAddress": {
"line1": "123 Main St",
"line2": "Apt 4B",
"country": "US",
"state": "TX",
"city": "Austin",
"zip": "78701"
}
}