Gateway Parameters

Supported gateways within Payment Services v2 and high-level information about each

Gateway Implementations

Parameter Pagesgateway parameter valueRequest ObjectsBuilt on SDK3rd Party API Documentation
Adyen ClassicAdyen- BillingAddress
- ShippingAddress
- CreditCard
- Check
- OrderInfo
- SoftDescriptors
- StoredCredentials
- ThreeDSecure
YesAdyen Classic Payments v51
Adyen CheckoutAdyenDirect- BillingAddress
- ShippingAddress
- CreditCard
- OrderInfo
- SoftDescriptors
- StoredCredentials
- ThreeDSecure
NoAdyen Checkout
Authorize.NetAuthorizeNetDirect- BillingAddress
- ShippingAddress
- CreditCard
- Check
- OrderInfo
- Wallet
NoAuthorize.Net Payment Transactions
BluePayBluePay- BillingAddress
- CreditCard
- Check
- OrderInfo
NoBluePay bp10emu
BraintreeBraintree- BillingAddress
- ShippingAddress
- CreditCard
- OrderInfo
- SoftDescriptors
- StoredCredentials
- ThreeDSecure
YesPayPal Braintree
ChaseNetConnectChaseNetConnect- BillingAddress
- CreditCard
- OrderInfo
NoChase Paymentech Developer Center
CyberSourceCyberSource- BillingAddress
- ShippingAddress
- CreditCard
- Check
- OrderInfo
- ThreeDSecure
YesCybersource Payments
dLocaldLocal- BillingAddress
- CreditCard
- OrderInfo
- SoftDescriptors
- StoredCredentials
- ThreeDSecure
NodLocal Payins
EBANXEBANX- BillingAddress
- CreditCard
- OrderInfo
- ThreeDSecure
NoEBANX Direct Payments
ElavonElavon- BillingAddress
- ShippingAddress
- CreditCard
- Check
- OrderInfo
- ThreeDSecure
NoElavon's Converge - XML
EMerchantPayEMerchantPay-BillingAddress
-CreditCard
-ThreeDSecure
-SoftDescriptors
-StoredCredentials
NoEMerchantPay Card Transactions
First Data IPGFirstDataIPG- BillingAddress
- ShippingAddress
- CreditCard
- OrderInfo
- SoftDescriptors
- StoredCredentials
- ThreeDSecure
NoFiserv's Internet Payment Gateway
NuveiNuvei- BillingAddress
- ShippingAddress
- CreditCard
- OrderInfo
- SoftDescriptors
- StoredCredentials
- ThreeDSecure
NoNuvei Payment API
OrbitalOrbital- BillingAddress
- ShippingAddress
- CreditCard
- Check
- OrderInfo
- SoftDescriptors
- StoredCredentials
- ThreeDSecure
NoChase Paymentech Orbital - Stratus
StripeStripe- BillingAddress
- ShippingAddress
- CreditCard
- OrderInfo
- SoftDescriptors
YesStripe Payment Intents
Worldpay eComm cnpAPIVantivCNP- BillingAddress
- ShippingAddress
- CreditCard
- Check
- OrderInfo
- SoftDescriptors
- ThreeDSecure
NoWorldpay CNP API
Worldpay Native RAFTWorldpayNativeRaft- BillingAddress
- CreditCard
- OrderInfo
- StoredCredentials
- ThreeDSecure
NoFIS Native Raft Credit API
Worldpay WPGWorldpayWPG- BillingAddress
- CreditCard
- Check
- OrderInfo
- ThreeDSecure
NoFIS WPG Direct Integration

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.

ParameterTypeDescription
GatewaystringName of the gateway implementation (see Gateway Implementations)
AmountnumberThe amount in minor units. For example, 2000 means USD 20.00. Max length: 12 characters.
CurrencyCodestringUse the ISO 4217 three-letter alphabetic code for the currency.
CustomerIpAddressstringThe IP Address of the customer or client performing the transaction. Used for fraud checks.
TokenExTransactionCodestringEach successful transaction generates a TokenExTransactionCode that should be used when processing modifications on that transaction through Payment Services.
BillingAddressobjectSee BillingAddress
CheckobjectSee Check
CreditCardobjectSee CreditCard
OrderInfoobjectSee OrderInfo
ShippingAddressobjectSee ShippingAddress
SoftDescriptorsobjectSee SoftDescriptors
StoredCredentialsobjectSee StoredCredentials
ThreeDSecureobjectSee ThreeDSecure

BillingAddress

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

BillingAddressType
Address1string
Address2string
Citystring
Companystring
Countrystring
FirstNamestring
FullNamestring
LastNamestring
Statestring
Zipstring
Emailstring
Faxstring
Phonestring

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.

CheckType
AccountNumberstring
AccountTypestring
BankNamestring
CheckNumberstring
FirstNamestring
FullNamestring
LastNamestring
RoutingNumberstring

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.

CreditCardType
Brandstring
CVVstring
ExpMonthnumber
ExpYearnumber
FirstNamestring
FullNamestring
LastNamestring
Numberstring

OrderInfo

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

OrderInfoType
CustomerIdstring
DiscountAmountnumber
DutyAmountnumber
InvoiceNumberstring
PurchaseOrderNumberstring
OrderIdstring
ShippingAmountnumber

ShippingAddress

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

ShippingAddressType
Address1string
Address2string
Citystring
Companystring
Countrystring
FirstNamestring
FullNamestring
LastNamestring
Statestring
Zipstring
Emailstring
Faxstring

SoftDescriptors

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

SoftDescriptorsType
MerchantCategoryCodestring
MerchantCitystring
MerchantEmailstring
MerchantNamestring
MerchantPhonestring
MerchantUrlstring

StoredCredentials

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

StoredCredentialsTypeDescription
CredentialStoredbooleanHas the credential been previously stored for use with subsequent transactions?
False: establish credential as stored.
True: subsequent usage of previously stored credential.
If this parameter is omitted, the value of the tx-tokenize header is used to infer the value. See Credential Stored Inference
InitiatorstringIs the transaction a cardholder-initiated or merchant-initiated transaction?
Valid values: "cardholder" or "merchant"
PreviousNetworkTransactionIdstringThe transaction id of the transaction which established the credential as stored.
TransactionTypestringValid values: "recurring", "installment", or "unscheduled". Some gateways allow gateway-specific transaction types as a passthrough.

Credential Stored Inference

StoredCredentials.CredentialStoredtx-tokenize headerInference
nulltrueStoredCredentials.CredentialStored:false
The credential has not been previously stored.
nullfalseStoredCredentials.CredentialStored:true
The credential has been previously stored.
nullabsentStoredCredentials.CredentialStored:true
The credential has been previously stored.
trueignoredStoredCredentials.CredentialStored:true
The credential has been previously stored.
falseignoredStoredCredentials.CredentialStored:false
The credential has not been previously stored.

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.

ThreeDSecureTypeEMVCo Mapping
CAVVstringauthenticationValue
DSTransIdstringdsTransID
ECIstringeci
ThreeDSecureVersionstringmessageVersion

Wallet

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

WalletTypeDescription
providerstringName of wallet provider to be used for the payment. Current values accepted:

- "GooglePay"
providerTokenstringThe provider token that the payment gateway requires for processing the transaction.

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.

ParameterTypeDescription
Tokensarray of key-value-pairsIf a request generated a token, that token is returned under the key "PAN". See Response Examples below.
GatewayResponseobjectContains information about what was sent to and received from the 3rd-Party Gateway API. See GatewayResponse below.
ReferenceNumberstringA value that can be used when communicating about a specific transaction. Provide this number to Support or Client Success when needed.
SuccessbooleanTrue when the transaction was sent through TokenEx servers as expected. False when an issue occurred as a result of a TokenEx validation or server issue.
ErrorstringWhen Success is false, contains information about what occurred or next steps to take.
MessagestringMay contain additional information about actions that occured within Payment Services.
ThirdPartyStatusCodestringThe HTTP status code returned by the 3rd-party gateway's 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.

GatewayResponseTypeDescription
ForwardedRequestobjectInformation about the request sent to the 3rd-party Gateway API. See Payment Services Testing. Only returned in the TokenEx Test environment.
RawResponseescaped stringThe response returned by the 3rd-party Gateway API. May be JSON, XML, or URL-encoded form parameters
ApprovedbooleanTrue when the requested action was processed successfully. False when an issue occurred preventing the action from being successful. The logic for determining this value is detailed within each gateway implementation.
TokenExTransactionCodestringA base64-encoded string that should be sent in secondary/modification requests such as Capture, Refund, and Void. This value assists the respective gateway in processing the request.
ProviderTransactionCodestringA unique identifier returned by the 3rd-party Gateway API in reference to the transaction. This is usually the value required by the gateway to process a modification request on the original transaction.
MerchantReferenceIdstringUsually the value sent in request's 'OrderInfo.OrderId' parameter.
NetworkTransactionIdstringA transaction identifier returned by the network. Usually used to reference a CIT transaction in a MIT flow.
CustomerProfileIdstringA merchant or gateway assigned value to reference the customer.
PaymentProfileIdstringA merchant or gateway assigned value to reference a payment profile.
GatewayTokenstringA gateway assigned value to reference a specific PAN. This value is not a TokenEx token.
VerificationResultstringCVC and AVS results. See VerificationResult below.
GatewayErrorsobject arrayAn array of objects containing information about any issues that occurred during processing of the transaction. See GatewayErrors below.

VerificationResult

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

VerificationResultTypeDescription
CvvRawstringCVV verification as returned by the issuer. Some gateways performing AVS and CVC checks do not return the raw values.
AvsRawstringAVS verification as returned by the issuer. Single value, not split by postal code or street. Some gateways performing AVS and CVC checks do not return the raw values.
ProviderParsedobjectContains any parsing of the issuer-returned CVV and AVS verification values occurred. Some gateways do not return any specific parsing of the raw values.
-CvvMatchstringProvider-parsed value of CVV verification
-AvsstringProvider-parsed value of AVS verification. Single value, not split by postal code or street
-StreetMatchstringProvider-parsed value of AVS verification - street only.
-PostalCodeMatchstringProvider-parsed value of AVS verification - postal code only.

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.

GatewayErrors[?]TypeDescription
CodestringThe issue code returned by the gateway. See the source parameter for the entity to which that code belongs to.
MessagestringThe message returned by the gateway. See the source parameter for the entity to which the message belongs to.
Source*stringPossible values: Unspecified, Gateway, Processor, TokenEx. This source should be used to filter the array.
Unspecified - the entity responsible for the issue could not be immediately determined.
Gateway - issue reported by the 3rd-Party Gateway API.
Processor - issues occurring downstream from the 3rd-Party Gateway API. Issuer codes and messages will fall under this source.
TokenEx - When TokenEx is unable to parse out the response from the 3rd-Party Gateway API or another issue occurs during processing of the response.
*The source parameter is not supported on all gateways at this time.

🚧

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.

GatewaySandbox Migration DateProduction Migration Date
Adyen Classic5/9/20235/16/2023
Authorize.Net2/14/20232/21/2023
BluePay2/14/20232/21/2023
Braintree11/29/202212/6/2022
ChaseNetConnect12/20/202212/27/2022
Cybersource5/7/20245/14/2024
EBANX1/4/20231/10/2023
Elavon5/9/20235/16/2023
Nuvei1/4/20231/10/2023
Stripe3/28/20234/4/2023
Payeezy5/9/20235/16/2023
Worldpay Native Raft12/20/202212/27/2022
Orbital11/29/202212/6/2022
First Data IPG12/20/202212/27/2022

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