Gateway Parameters

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

Gateway Implementations

Parameter Pages	gateway parameter value	Request Objects	Built on SDK	3rd Party API Documentation
Adyen Classic	Adyen	- BillingAddress - ShippingAddress - CreditCard - Check - OrderInfo - SoftDescriptors - StoredCredentials - ThreeDSecure	Yes	Adyen Classic Payments v51
Adyen Checkout	AdyenDirect	- BillingAddress - ShippingAddress - CreditCard - OrderInfo - SoftDescriptors - StoredCredentials - ThreeDSecure	No	Adyen Checkout
Authorize.Net	AuthorizeNetDirect	- BillingAddress - ShippingAddress - CreditCard - Check - OrderInfo - Wallet	No	Authorize.Net Payment Transactions
BluePay	BluePay	- BillingAddress - CreditCard - Check - OrderInfo	No	BluePay bp10emu
Braintree	Braintree	- BillingAddress - ShippingAddress - CreditCard - OrderInfo - SoftDescriptors - StoredCredentials - ThreeDSecure	Yes	PayPal Braintree
ChaseNetConnect	ChaseNetConnect	- BillingAddress - CreditCard - OrderInfo	No	Chase Paymentech Developer Center
CyberSource	CyberSource	- BillingAddress - ShippingAddress - CreditCard - Check - OrderInfo - ThreeDSecure	Yes	Cybersource Payments
dLocal	dLocal	- BillingAddress - CreditCard - OrderInfo - SoftDescriptors - StoredCredentials - ThreeDSecure	No	dLocal Payins
EBANX	EBANX	- BillingAddress - CreditCard - OrderInfo - ThreeDSecure	No	EBANX Direct Payments
Elavon	Elavon	- BillingAddress - ShippingAddress - CreditCard - Check - OrderInfo - ThreeDSecure	No	Elavon's Converge - XML
EMerchantPay	EMerchantPay	-BillingAddress -CreditCard -ThreeDSecure -SoftDescriptors -StoredCredentials	No	EMerchantPay Card Transactions
First Data IPG	FirstDataIPG	- BillingAddress - ShippingAddress - CreditCard - OrderInfo - SoftDescriptors - StoredCredentials - ThreeDSecure	No	Fiserv's Internet Payment Gateway
Nuvei	Nuvei	- BillingAddress - ShippingAddress - CreditCard - OrderInfo - SoftDescriptors - StoredCredentials - ThreeDSecure	No	Nuvei Payment API
Orbital	Orbital	- BillingAddress - ShippingAddress - CreditCard - Check - OrderInfo - SoftDescriptors - StoredCredentials - ThreeDSecure	No	Chase Paymentech Orbital - Stratus
Stripe	Stripe	- BillingAddress - ShippingAddress - CreditCard - OrderInfo - SoftDescriptors	Yes	Stripe Payment Intents
Worldpay eComm cnpAPI	VantivCNP	- BillingAddress - ShippingAddress - CreditCard - Check - OrderInfo - SoftDescriptors - ThreeDSecure	No	Worldpay CNP API
Worldpay Native RAFT	WorldpayNativeRaft	- BillingAddress - CreditCard - OrderInfo - StoredCredentials - ThreeDSecure	No	FIS Native Raft Credit API
Worldpay WPG	WorldpayWPG	- BillingAddress - CreditCard - Check - OrderInfo - ThreeDSecure	No	FIS 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.

Parameter	Type	Description
Gateway	string	Name of the gateway implementation (see Gateway Implementations)
Amount	number	The amount in minor units. For example, 2000 means USD 20.00. Max length: 12 characters.
CurrencyCode	string	Use the ISO 4217 three-letter alphabetic code for the currency.
CustomerIpAddress	string	The IP Address of the customer or client performing the transaction. Used for fraud checks.
TokenExTransactionCode	string	Each successful transaction generates a TokenExTransactionCode that should be used when processing modifications on that transaction through Payment Services.
BillingAddress	object	See BillingAddress
Check	object	See Check
CreditCard	object	See CreditCard
OrderInfo	object	See OrderInfo
ShippingAddress	object	See ShippingAddress
SoftDescriptors	object	See SoftDescriptors
StoredCredentials	object	See StoredCredentials
ThreeDSecure	object	See ThreeDSecure

BillingAddress

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

BillingAddress	Type
Address1	string
Address2	string
City	string
Company	string
Country	string
FirstName	string
FullName	string
LastName	string
State	string
Zip	string
Email	string
Fax	string
Phone	string

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.

Check	Type
AccountNumber	string
AccountType	string
BankName	string
CheckNumber	string
FirstName	string
FullName	string
LastName	string
RoutingNumber	string

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.

CreditCard	Type
Brand	string
CVV	string
ExpMonth	number
ExpYear	number
FirstName	string
FullName	string
LastName	string
Number	string

OrderInfo

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

OrderInfo	Type
CustomerId	string
DiscountAmount	number
DutyAmount	number
InvoiceNumber	string
PurchaseOrderNumber	string
OrderId	string
ShippingAmount	number

ShippingAddress

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

ShippingAddress	Type
Address1	string
Address2	string
City	string
Company	string
Country	string
FirstName	string
FullName	string
LastName	string
State	string
Zip	string
Email	string
Fax	string

SoftDescriptors

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

SoftDescriptors	Type
MerchantCategoryCode	string
MerchantCity	string
MerchantEmail	string
MerchantName	string
MerchantPhone	string
MerchantUrl	string

StoredCredentials

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

StoredCredentials	Type	Description
CredentialStored	boolean	Has 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
Initiator	string	Is the transaction a cardholder-initiated or merchant-initiated transaction? Valid values: "cardholder" or "merchant"
PreviousNetworkTransactionId	string	The transaction id of the transaction which established the credential as stored.
TransactionType	string	Valid values: "recurring", "installment", or "unscheduled". Some gateways allow gateway-specific transaction types as a passthrough.

Credential Stored Inference

StoredCredentials.CredentialStored	tx-tokenize header	Inference
null	true	StoredCredentials.CredentialStored:false The credential has not been previously stored.
null	false	StoredCredentials.CredentialStored:true The credential has been previously stored.
null	absent	StoredCredentials.CredentialStored:true The credential has been previously stored.
true	ignored	StoredCredentials.CredentialStored:true The credential has been previously stored.
false	ignored	StoredCredentials.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.

ThreeDSecure	Type	EMVCo Mapping
CAVV	string	authenticationValue
DSTransId	string	dsTransID
ECI	string	eci
ThreeDSecureVersion	string	messageVersion

Wallet

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

Wallet	Type	Description
provider	string	Name of wallet provider to be used for the payment. Current values accepted: - "GooglePay"
providerToken	string	The 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.

Parameter	Type	Description
Tokens	array of key-value-pairs	If a request generated a token, that token is returned under the key "PAN". See Response Examples below.
GatewayResponse	object	Contains information about what was sent to and received from the 3rd-Party Gateway API. See GatewayResponse below.
ReferenceNumber	string	A value that can be used when communicating about a specific transaction. Provide this number to Support or Client Success when needed.
Success	boolean	True 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.
Error	string	When Success is false, contains information about what occurred or next steps to take.
Message	string	May contain additional information about actions that occured within Payment Services.
ThirdPartyStatusCode	string	The 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.

GatewayResponse	Type	Description
ForwardedRequest	object	Information about the request sent to the 3rd-party Gateway API. See Payment Services Testing. Only returned in the TokenEx Test environment.
RawResponse	escaped string	The response returned by the 3rd-party Gateway API. May be JSON, XML, or URL-encoded form parameters
Approved	boolean	True 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.
TokenExTransactionCode	string	A 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.
ProviderTransactionCode	string	A 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.
MerchantReferenceId	string	Usually the value sent in request's 'OrderInfo.OrderId' parameter.
NetworkTransactionId	string	A transaction identifier returned by the network. Usually used to reference a CIT transaction in a MIT flow.
CustomerProfileId	string	A merchant or gateway assigned value to reference the customer.
PaymentProfileId	string	A merchant or gateway assigned value to reference a payment profile.
GatewayToken	string	A gateway assigned value to reference a specific PAN. This value is not a TokenEx token.
VerificationResult	string	CVC and AVS results. See VerificationResult below.
GatewayErrors	object array	An 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.

VerificationResult	Type	Description
CvvRaw	string	CVV verification as returned by the issuer. Some gateways performing AVS and CVC checks do not return the raw values.
AvsRaw	string	AVS 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.
ProviderParsed	object	Contains any parsing of the issuer-returned CVV and AVS verification values occurred. Some gateways do not return any specific parsing of the raw values.
-CvvMatch	string	Provider-parsed value of CVV verification
-Avs	string	Provider-parsed value of AVS verification. Single value, not split by postal code or street
-StreetMatch	string	Provider-parsed value of AVS verification - street only.
-PostalCodeMatch	string	Provider-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[?]	Type	Description
Code	string	The issue code returned by the gateway. See the source parameter for the entity to which that code belongs to.
Message	string	The message returned by the gateway. See the source parameter for the entity to which the message belongs to.
Source*	string	Possible 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.

Gateway	Sandbox Migration Date	Production Migration Date
Adyen Classic	5/9/2023	5/16/2023
Authorize.Net	2/14/2023	2/21/2023
BluePay	2/14/2023	2/21/2023
Braintree	11/29/2022	12/6/2022
ChaseNetConnect	12/20/2022	12/27/2022
Cybersource	5/7/2024	5/14/2024
EBANX	1/4/2023	1/10/2023
Elavon	5/9/2023	5/16/2023
Nuvei	1/4/2023	1/10/2023
Stripe	3/28/2023	4/4/2023
Payeezy	5/9/2023	5/16/2023
Worldpay Native Raft	12/20/2022	12/27/2022
Orbital	11/29/2022	12/6/2022
First Data IPG	12/20/2022	12/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.

Tokenize

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

Detokenize and Passthrough

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

Gateway Error - Error Codes and Messages

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

Gateway Error - List of Strings

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