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 |
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 |
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
.
{
"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"
}
Updated 4 months ago