GuidesAPI ReferenceRelease Notes

Transparent Detokenization Integration

Suggest Edits

To begin using this service, you simply need to make a few modifications to the code that is constructing your HTTPS payload to the 3rd-party endpoint.

  1. Update the URL to POST to TokenEx
  2. Add a HTTP Header for the intended URL
    • TX-URL
  3. Add your Authentication Headers
    • TX-TokenEx-ID
    • TX-APIKey
  4. Replace the sensitive data point in the HTTP Body with the TokenEx token, wrapped in three curly braces
    • example: {{{545454XXXXXX5454}}}
  5. (Optional) To inject a CVV that was previously collected by TokenEx, insert the CVV placeholder as shown below. The placeholder is established by calling the CVV function.
    • example: {{{{FUNCTION:CVV, TOKEN:545454XXXXXX5454}}}}

📘

Don't want to wrap your token in curly braces?

You can optionally use the "tx-request-regex" header which allows you to bypass the {{{ }}} requirement and instead identify the location of your token using a regular expression.

HTTP Request Headers

HeaderRequiredDescription
TX-TokenEx-IDRequiredYour TokenEx ID.
TX-APIKeyRequiredYour API Key.
TX-URLRequiredThe endpoint URL to which TokenEx should POST the detokenized request.
TX-CacheCvvOptionalSending 'true' will cache the CVV for 5 minutes allowing additional attempts with the CVV after a failed transaction.

Click here to view more information about required and additional optional headers for this endpoint.

HTTP Response Headers

HeaderDescription
tx-thirdpartystatuscodeThe statuscode TokenEx received from our connection with the 3rd party host.
tx-tokenexstatuscodeThe status code related to your connection with TokenEx.
tx-destinationtimeThe amount of time the request spent with the 3rd party host.
tx-tokenex-timeThe total amount of time the request spent with TokenEx.
tx-total-timeThe total amount of time (TokenEx + 3rd party host) it took to process the request.

Detokenization Examples - JSON

POST https://test-tgapi.tokenex.com/detokenize HTTP/1.1
Content-Type: application/json
TX-URL: https://www.example.com
TX-TokenEx-ID: YourTokenExID
TX-APIKey: YourAPIKey

{
	"card": {
		"type": "MC ",
		"number": "{{{545454XXXXXX5454}}}",
		"expDate": "1126",
		"cardValidationNum":"123
	}
}

POST https://test-tgapi.tokenex.com/detokenize HTTP/1.1
Content-Type: application/json
TX-URL: https://www.example.com
TX-TokenEx-ID: YourTokenExID
TX-APIKey: YourAPIKey

{
	"card": {
		"type": "MC ",
		"number": "{{{545454XXXXXX5454}}}",
		"expDate": "1112",
		"cardValidationNum": "{{{{FUNCTION:CVV, TOKEN:545454XXXXXX5454}}}}"
	}
}

POST https://test-tgapi.tokenex.com/detokenize HTTP/1.1
Content-Type: application/json
TX-URL: https://www.example.com
TX-TokenEx-ID: XXXXXXXXXX
TX-APIKey: XXXXXXXXXX
TX-CacheCvv: true

{
	"card": {
		"type": "MC ",
		"number": "{{{545454XXXXXX5454}}}",
		"expDate": "1126",
		"cardValidationNum": "{{{{FUNCTION:CVV, TOKEN:545454XXXXXX5454}}}}"
	}
}

POST https://test-tgapi.tokenex.com/detokenize HTTP/1.1
Content-Type: application/json
TX-URL: https://www.example.com
TX-TokenEx-ID: YourTokenExID
TX-APIKey: YourAPIKey
TX-Request-Regex: (?<="CreditCardNumber": ")(.*?)(?=")

{
	"FirstName": "John",
	"LastName": "Smith",
	"CreditCardNumber": "545454XXXXXX5454",
	"ExpirationDate": "06/24",
	"CVV": "123"
}

Detokenization Examples - XML

POST https://test-tgapi.tokenex.com/detokenize HTTP/1.1
Content-Type: text/xml
TX-URL: https://www.example.com
TX-TokenEx-ID: YourTokenExID
TX-API-Key: YourAPIKey

<card>
	<type>MC</type>
	<number>{{{545454XXXXXX5454}}}</number>
	<expDate>1126</expDate>
	<cardValidationNum>123</cardValidationNum>
</card>

POST https://test-tgapi.tokenex.com/detokenize HTTP/1.1
Content-Type: text/xml
TX-URL: https://www.example.com
TX-TokenEx-ID: YourTokenExID
TX-API-Key: YourAPIKey

<card>
	<type>MC</type>
	<number>{{{545454XXXXXX5454}}}</number>
	<expDate>1126</expDate>
	<cardValidationNum>{{{{FUNCTION:CVV, TOKEN:545454XXXXXX5454}}}}</cardValidationNum>
</card>

Detokenization Examples - Form URL encoded

POST https://test-api.tokenex.com/TransparentGatewayAPI HTTP/1.1
Content-Type: application/x-www-form-URLencoded
TX-URL: https://www.example.com
TX-TokenEx-ID: YourTokenExID
TX-APIKey: YourAPIKey

type=MC&number={{{545454XXXXXX5454}}}&expDate=1112&cardValidationNum=123

POST https://test-tgapi.tokenex.com/detokenize HTTP/1.1
Content-Type: application/x-www-form-URLencoded
TX-URL: https://www.example.com
TX-TokenEx-ID: YourTokenExID
TX-APIKey: YourAPIKey

type=MC&number={{{545454XXXXXX5454}}}&expDate=1112&cardValidationNum={{{{FUNCTION:CVV, TOKEN:545454XXXXXX5454}}}}

Updated 11 days ago