Gateway Implementations

Request Parameters

Gateway implementations expose functionality through the below parameters. See each implementation linked above for the exact parameters (including gateway-specifics) that are supported and the 3rd-party gateway API parameters to which they are mapped. It is okay to send requests containing parameters that are not mapped for a gateway - these extra parameters are ignored and not forwarded to the 3rd-party gateway API.

BillingAddress

The Billing Address object is used to send information about the entity being billed for the transaction.

Check

The Check object is used to send information about an account holder's bank account. AccountNumber can be the TokenEx token associated with the PAN.

CreditCard

The CreditCard object is used to send information about a cardholder's card. It can be used for credit and debit cards. Number can be the TokenEx token associated with the PAN.

OrderInfo

The OrderInfo object is used to send additional information about the order.

ShippingAddress

The Shipping Address object is used to send information about the entity to which a product is being sent.

SoftDescriptors

Use Soft Descriptors (also called Dynamic Descriptors) to add more detail to a customer's bank statement.

StoredCredentials

Use Stored Credentials to support CIT (cardholder initiated transactions) and MIT (merchant initiated transactions) flows.

Credential Stored Inference

ThreeDSecure

Payment Services supports the pass through of EMVCo 3-D Secure authentication values obtained from authentication providers, such as TokenEx's 3-D Secure Authentication or Cardinal Commerce.

Wallet

The wallet object can be used to pass through payment instrument data from providers such as Google Pay to the payment gateway.

Response Parameters

Requests to Payment Services return the following parameters. GatewayResponse may not be present if the transaction fails prior to or during the request to the 3rd-Party Gateway API.

GatewayResponse

The GatewayResponse object contains the response sent by the 3rd-Party Gateway's API and parsings of that response. Not all gateway implementations will return values for all the parameters. The RawResponse is the source of truth for how a transaction was processed and it is strongly recommended that your application parse it when obtaining details about and determining the success or failure of a transaction. Response models can be obtained from the 3rd-Party Gateway's API documentation.

Additional gateway response parameters below can be used when supported by a gateway implementation and their values align with your application's logic. Reach out to us with parameter mapping suggestions for specific gateways as Payment Services continues to grow.

VerificationResult

Returns results about any CVC and AVS checks that were performed downstream from TokenEx.

GatewayErrors

The GatewayErrors object is intended to isolate codes and messages from the rawResponse when an issue arises preventing a transaction from being approved. Use this parameter to determine transaction failure only when the mappings are a value-add to your application - the rawResponse should always be parsed to diagnose the exact status of a transaction.

🚧

Gateway Errors formatting

This product is migrating to an Error Codes and Messages format (detailed above) to enable more merchant-friendly parsing. This migration is a work in progress. See table below for migrated gateways. The List of Strings format will be maintained for active customers until a sunset date is identified, after which the format will be switched.

Response Examples

Any request that includes either the creditCard.Number or check.AccountNumber parameter can create TokenEx tokens. If a token was generated, it will be returned in the response under tokens.PAN.

{
    "tokens": {
        "PAN": "TokenEx Token Here"
    },
    "gatewayResponse": {
        "rawResponse": "{varies by gateway}",
        "gatewayErrors": [],
        "tokenExTransactionCode": "UUxNTkpTQzVDVEdMTks4Mg==",
        "providerTransactionCode": "QLMNJSC5CTGLNK82",
        "approved": true
    },
    "referenceNumber": "23111113453145218703",
    "success": true,
    "error": "",
    "message": "",
    "thirdPartyStatusCode": "200"
}

{
    "gatewayResponse": {
        "rawResponse": "{varies by gateway}",
        "gatewayErrors": [],
        "tokenExTransactionCode": "UUxNTkpTQzVDVEdMTks4Mg==",
        "providerTransactionCode": "QLMNJSC5CTGLNK82",
        "approved": true
    },
    "referenceNumber": "23111113453145218703",
    "success": true,
    "error": "",
    "message": "",
    "thirdPartyStatusCode": "200"
}

{
    "gatewayResponse": {
        "rawResponse": "{varies by gateway}",
        "gatewayErrors": [
            {
                "code": "2022",
                "message": "Declined - Updated Cardholder Available"
            }
        ],
        "providerTransactionCode": "QLMNJSC5CTGLNK82",
        "approved": false
    },
    "referenceNumber": "22112316405851364004",
    "success": true,
    "error": "",
    "message": "",
    "thirdPartyStatusCode": "200"
}

{
    "gatewayResponse": {
        "rawResponse": "{varies by gateway}",
        "gatewayErrors": [
            "Declined - Updated Cardholder Available",
            "2022 - Declined - Updated Cardholder Available"
        ],
        "tokenExTransactionCode": "",
        "providerTransactionCode": "QLMNJSC5CTGLNK82",
        "approved": false
    },
    "referenceNumber": "22112316405851364004",
    "success": true,
    "error": "",
    "message": "",
    "thirdPartyStatusCode": "200"
}