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

Modify the Request Body

📘

FYI

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

{{{TOKEN}}}

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
Example:
name=John%20Smith&data=5454545454545454&total=23.12
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.

Accept-Encoding
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.

Content-Encoding
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.