Construct Request

The HTTP request should first be constructed to meet the specifications of the receiving endpoint. Then, modifications need to be made in order to pass this request through the TGAPI. These modifications may include the addition of TokenEx specific headers, and/or changes to the request body. These modifications enable the TGAPI to perform the necessary processing (i.e. detokenization, tokenization, encryption, decryption, hashing, or encoding) on the request before forwarding the request on to the receiving endpoint.

Supply TokenEx Request Headers

HTTP Request HeaderDescription/Detokenize/Tokenize/Proxy/Hash
tx-tokenex-idID from configuration menu in client portalRequiredRequiredN/ARequired
tx-apikeyAPI key from configuration menu in client portalRequiredRequiredN/ARequired
tx-urlThe destination to which TokenEx will forward the request.
Must be prefixed with https://
tx-proxy-keyAPI key assigned to proxy profile from proxy profile menu in client portalN/AN/ARequiredN/A
tx-proxy-encryption-ivInitialization vector (applicable when encryption is enabled in proxy profile)N/AN/AOptionalN/A
tx-request-regexRegular expression to locate token in request (used in place of curly brackets).
Token must be in group 0 or the match of the regex. (Note: see Payload Encodings / Formats)
tx-response-regexRegular expression or MultiRegex expression to locate data to be tokenized in the response. Data to be tokenized must be in group 0 or the match of the regex. OptionalRequiredN/AN/A
tx-token-schemeToken scheme to be applied to data to be tokenized in responseOptionalRequiredN/AN/A
tx-cachecvvExtends life of security code for 5min after initial useOptionalN/AN/AN/A
tx-headersComma-separated list of headers expected to be received from destination endpoint in responseOptionalOptionalN/AN/A
tx-HMACkeyThe HMAC key for HMAC payload hashingN/AN/AN/AOptional (Required for HMAC Types)
tx-response-metaregex-cvvRegular expression to locate CVV data to be associated with a token in the response.



will match bolded: "CVV": "1234"
tx-http-timeoutValue in seconds to wait for a response from the 3rd-party before timing out.
Default: 60
Max: 120
tx-retrySee Retries and 3rd PartiesoptionaloptionaloptionalN/A
tx-client-keyUtilized to pass in the private key for mutual authentication.

The key should be in PKCS#8 format, starting with “-----BEGIN PRIVATE KEY-----” and ending with "-----END PRIVATE KEY-----", and should either be base64 encoded as a whole, or converted to a single line string, replacing line breaks with \r\n.

If using base64 encoding, you must include a value of true for the tx-client-key-encoded header.

Indicates whether the value of tx-client-key has been base64 encoded.
tx-client-certUtilized to pass in the certificate for mutual authentication.

The certificate should be in PEM format, starting with “-----BEGIN CERTIFICATE-----” and ending with "-----END CERTIFICATE-----", and should either be base64 encoded as a whole, or converted to a single line string, replacing line breaks with \r\n.

If using base64 encoding, you must include a value of true for the tx-client-cert-encoded header.

Indicates whether the value of tx-client-cert has been base64 encoded.
tx-passthroughSpecific to a request to the Detokenize endpoint, this allows the request to bypass the requirement that a token be present in the body of the request.optionalN/AN/AN/A
tx-ignore-default-encodingSpecifies that the default UTF8 encoding should be ignored and that the encoding in the original request will be used.optionaloptionalN/AN/A
tx-cvv-not-requiredSpecifies that the request will continue if a CVV is not able to be retrieved.optionaloptionalN/AN/A
tx-retain-cvvEnables the persistence of the CVV when used for a non-payment authorization flow such as a 3D-Secure authentication. The CVV will remain usable for 7 days after its initial association.optionalN/AN/AN/A
tx-acceptXML serialization for TokenEx errors instead of JSON

Requires content type to be provided as the header value (e.g. application/xml)

Indicates that your payload is minified/compressed i.e. When payload drops all tabs and whitespace and makes JSON take up the least space.

We recommend using this header only when your JSON payload is compressed and also contains TokenEx Function.
{"PaymentCard":{"type":"credit","cardNumber":"{{{TOKEN}}}","expDate":"1234", "securityCode": {{{{FUNCTION:CVV, TOKEN:TOKEN}}}},"test": {"test2": {"test3": "data"}}}}

Modify the Request Body



Modifications to the body are not always required, such as with proxy tokenization, or when using the tx-request-regex instead of token notation for transparent detokenization.

Token Notation – The token is located between three sets of curly brackets


Tokens can be located in the body of a request using token notation. Functions can also be invoked within the request body using function notation. A combination of up to ten tokens or functions may be located within a request body.

Payload Encodings / Formats

The TGAPI will support any data format (JSON, XML, form-URL-encoded, etc.) if the token can be located in the request body (by token notation, a proxy profile regular expression, or via the tx-request-regex header) and read. If the token is not readable (i.e. the tokens characters have changed due to encoding/compression) or the regular expression has no match, the TGAPI will not be able to locate the token. In this case, the TGAPI detokenize endpoint and the TGAPI payload hashing endpoint will return a 3000 error, “token does not exist”. TGAPI tokenize and proxy endpoints will not return an error but will report that there are no matches for the regular expression in the tx-message response header.

By default, a charset of UTF-8 is appended to the outgoing request when TGAPI is forwarding it on to the third party. To bypass this default encoding, please set the tx-ignore-default-encoding header to true.

Note: In the case of a "application/x-www-form-urlencoded" request, the tx-request-regex header behaves slightly differently. The regex can only operate on each key and value separately, not on the body as a whole like other requests
A tx-request-regex header of (?<=data=)([^\"]+) would not work, because the context of the regex would just be the key data or the value 5454545454545454, but not data=5454545454545454. Your regex must target the PAN value directly

Response MultiRegex

MultiRegex allows more than one regex pattern to be sent for locating data elements to Tokenize, with support for different token schemes assigned to each pattern. This is useful when you have different types of data to tokenize in your 3rd-party's response.

To build a MultiRegex, create a JSON object where the keys are the regex patterns to match against and the values are the token schemes to use when tokenizing those matches.

  "(?<=data\": \")([0-9]{13})(?=\")": "nTOKEN",
  "(?<=number\": \")([0-9]{14,16})(?=\")": "ANTOKEN"


MultiRegex Validation

For a MultiRegex to be accepted, the JSON object must only contain root-level keys/values as described in this section. If there is a parsing error, the value is assumed to be a single regex pattern and the tx-token-scheme header controls how matches are tokenized, if any.

Once you have built the object, stringify it, then take the MultiRegex string value and set it to the tx-response-regex header of your request. The tx-message response header will indicate how many matches in the response were found and tokenized. The MultiRegex limit is the same as the per-request Tokenize limit.


Vaultless token schemes

For clients who use vaultless token schemes, matched data will be tokenized using your chose vaultless token scheme. If any MultiRegex pattern specifies a different token scheme, it will be ignored.

GZIP Compression

The TGAPI does support GZIP compressed content encodings. If the content-encoding header is set to gzip, the TGAPI will decompress the request, process, and re-compress before forwarding on to the specified endpoint. GZIP compression can be controlled in the TGAPI using a couple of headers.

When the initial request is sent to the TGAPI, setting the accept-encoding header to GZIP informs the TGAPI that a gzip compressed response can be returned to the system that initiated the request.

When this header is set to gzip and is received (in a request or a response), the TGAPI understands that the request needs to be decompressed, processed, and then recompressed before forwarding the request and/or response to the recipient endpoint.

tx-proxy-key via Basic Auth

The tx-proxy-key value may also be sent via the http basic authorization header. If the tx-proxy-key is sent in this manner then the tx-proxy-key header is no longer required for proxy requests.

To leverage, simply pass tx-proxy-key as the username, and the proxy key as the password.
For example: Basic tx-proxy-key:Your-Proxy-Key-Here
The username:password segment is expected to be base64 encoded before being sent in the request.