Skip to main content

Payment Services v2 - The Basics

Use TokenEx tokens with a variety of Payment Gateways

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​

TransactionPayment TypeDescription
Card AuthorizeCreationValidates customer payment card and places a hold on funds.
Card PurchaseCreationValidates customer payment card and moves funds to the merchant.
Card CaptureModificationMoves funds from a previous authorization to the merchant.
Card RefundModificationMoves funds from the merchant to a customer's card.
Card VoidModificationCancels an in-process action.
Check Purchase*CreationMoves funds from customer's bank account to the merchant.
Check Refund*ModificationMoves funds from the merchant to the customer's bank account.
Check Void*ModificationCancels an in-process action.
*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

TransactionPath
Card Authorize/card/authorize
Card Purchase/card/purchase
Card Capture/card/capture
Card Refund/card/refund
Card Void/card/void
Check Purchase/check/purchase
Check Refund/check/refund
Check Void/check/void
Wallet Authorize/wallet/authorize
Wallet Purchase/wallet/purchase
Wallet Capture/wallet/capture
Wallet Refund/wallet/refund
Wallet Void/wallet/void

Headers​

HTTP Request HeaderDescription
Tx-TokenEx-IdID from configuration menu in client portal
Tx-ApiKeyAPI key from configuration menu in client portal
Tx-Token-SchemeEither the name (case sensitive) or the numerical value of the Token Scheme to be used
Tx-TokenizeTrue/False. Tokenizes PAN within request for Card numbers and ACH account numbers.
Tx-PassthroughTrue/False. Bypasses detokenization of PAN within request for Card numbers and ACH account numbers
Tx-CacheCvvTrue/False. Caches CVV for 5 minutes so that it can be used with subsequent transactions. See CVV Retention and Retrieval
Tx-Cvv-Not-RequiredTrue/False. Specifies that the request will continue if a CVV is not able to be retrieved.
Tx-Network-TokenizationBreakOnFailure (1) or UsePANFallback (2). Indicates the behavior of the flow for using Network Tokenization gateway integrations if we are unable to provision a network token (if tokenizing) or retrieve a payment cryptogram for your transaction.
Tx-RetrySee Retries and 3rd Party APIs
Tx-Http-TimeoutValue in seconds to wait for a response from the 3rd-party before timing out.
Default: 60
Max: 120

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.

OperationTx-TokenizeTx-Passthrough
TokenizeTrueTrue
TokenizeTrueFalse
PassthroughFalseTrue
DetokenizeFalseFalse
DetokenizeHeader OmittedHeader Omitted
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**

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"
}
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.

Last updated on