Overview

Payment Services supports the use of TokenEx tokens with many 3rd-Party Payment Gateways through a single, standardized REST API format using JSON. This format reduces the time-to-market when integrating multiple gateways into your payments flow while keeping the customers' payment method PANs out of PCI scope.

Transaction Flows

^{*Not all gateways support ACH/Check transactions}

Construct a Request

Please contact TokenEx Support or Customer Success to request a current Postman collection which will contain working examples of requests and responses for each gateway.

Transaction Endpoints

Send HTTP POST requests to the below endpoints.

Production: https://paymentservices.tokenex.com

Sandbox: https://test-paymentservices.tokenex.com

Headers

Tokenization, Detokenization and CVV Retrieval

Currently supported fields for tokenization and detokenization are CreditCard.Number and Check.AccountNumber. By default, detokenization is performed on these values. To bypass detokenization, pass the Tx-Passthrough:true header. To tokenize instead of detokenizing, pass the Tx-Tokenize:true header. If Tx-Tokenize:true, the Tx-Token-Scheme header must be present and the Tx-Passthrough header will be ignored. A token or relevant tokenization error message will always be returned if Tx-Tokenize:true.

The detokenize operation supports CVV retrieval for verification values previously associated with a token. To trigger CVV retrieval during a detokenize operation, pass "cvv" in the CreditCard.CVV field. Transactions approved by the gateway will trigger the deletion of that CVV from TokenEx systems. Numeric values will not trigger a CVV retrieval and instead will be passed along to the gateway unmodified.

A tokenize operation does not support CVV association with a card number. Instead, the value of CreditCard.CVV will be passed along to the gateway unmodified.

Tx-Passthrough bypasses tokenization, detokenization, and CVV retrieval operations. Account numbers and CVVs passed in the request are forwarded to the gateway.

Example header configurations

tx-tokenex-id:<Your TokenExId>
tx-apikey:<Your API Key>
tx-token-scheme:sixTOKENfour
tx-tokenize:true

**tx-passthrough is ignored in a tokenize flow**

tx-tokenex-id:<Your TokenExId>
tx-apikey:<Your API Key>

tx-tokenex-id:<Your TokenExId>
tx-apikey:<Your API Key>

**Request body snippet*
"CreditCard": {
        "Number": "123456789012345",
        "ExpMonth": 3,
        "ExpYear": 2024,
        "CVV": "cvv"
    }

tx-tokenex-id:<Your TokenExId>
tx-apikey:<Your API Key>
tx-passthrough:true

Body

Payment Services has minimal validations in place around the values sent to the third-party gateway APIs. For each gateway you're integrating, consult the gateway's parameter page for example requests and breakdowns of request and response parameters as well as any gateway-specific functionality.

Utilizing the 3rd-party API's documentation is critical for a successful integration, though there is significant standardization between gateway implementations on request parameters such as Amount,CurrencyCode, BillingAddress, ShippingAddress, CreditCard, Check, SoftDescriptors, StoredCredentials, and ThreeDSecure. The specific request parameters to be included with each request are dependent upon the payment gateway your application is integrating with. If a field is not required for your gateway, it does not have to be populated.

Several of our gateway implementations support parameter forwarding, allowing your application to forward parameters that are specific to a 3rd-Party Gateway's API. It is recommended to utilize this feature when a supported gateway implementation does not have a suitable parameter mapping for your application's need.

Every successful transaction will generate the response parameter tokenExTransactionCode in the gatewayResponse (see GatewayResponse). The tokenExTransactionCode is required for modification transactions such as Captures, Voids, and Refunds so that Payment Services can properly process the modification. The generated tokenExTransactionCode is a base64-encoded string containing information needed by the respective gateway implementation to process the subsequent transaction. This field should remain unmodified between primary responses and secondary transactions. An example usage of a tokenExTransactionCode is below.

{
    "gatewayResponse": {
        "rawResponse": "{varies by gateway}",
        "gatewayErrors": [],
        "tokenExTransactionCode": "QlMyM0RQWEtUR1hYR044Mg==",
        "approvalCode": "082011",
        "providerTransactionCode": "BS23DPXKTGXXGN82",
        "approved": true
    },
    "referenceNumber": "22111515501772095335",
    "success": true,
    "error": "",
    "message": "",
    "thirdPartyStatusCode": "200"
}

{
    "Gateway": "<Gateway name>",
    "TokenExTransactionCode": "QlMyM0RQWEtUR1hYR044Mg==",
    "<Gateway-specific credential field>":"<Gateway-specific credential>",
    "<Gateway-specific credential field>":"<Gateway-specific credential>"
}

🚧

Careful with that TokenEx transaction code!

Attempting to create or modify a tokenexTransactionCode may yield unpredictable results. If deconstructing and generating these codes is required for your payments flow, please reach out for more details on these code constructions. A use case for generating your own TokenEx transaction codes is performing modifications on payments that were created outside of Payment Services.