Mastercard Payment Gateway API Reference: Operations -
Version 76,
Protocol: NVP

Initiate Authentication

Request returning which payer authentication mechanism (e.g. 3-D Secure authentication version 2, 3-D Secure authentication version 1, RuPay PaySecure) the gateway recommends you to use for this order.

Where both 3-D Secure Authentication version 1 and version 2 are available the gateway returns 3-D Secure authentication version 2.

You must provide details about the card, the purpose of the authentication (e.g payment or card registration only), and how the payer will interact with the authentication process (e.g. via the browser or mobile app).

You can provide the actual card details, or a gateway token, scheme token or device payment details.

The response will indicate, if payer authentication is available. You can either

  • only proceed with the Authenticate Payer operation where the response indicates that payer authentication is available (transaction.authenticationStatus=AUTHENTICATION_AVAILABLE ) or
  • (to simplify your integration) always proceed with the Authenticate Payer operation. Where no payer authentication is available, the payer will simply be redirected back to your website.
When performing payer authentication we recommend you use a payment session. This will allow you to share the request data across the multiple operations required to carry out both the payer authentication and transaction processing.

When using a payment session build your integration as follows:
  • When you create the payment session, populate it with all the transaction data required for the Authenticate Payer operation.
  • As soon as you have the card number, invoke the Initiate Authentication operation with the payment session identifier. It is recommended that you perform this asynchronously, so that the payer can continue filling out payment details.
  • When the payers clicks PAY, update the payment session with the additional data entered by the payer and invoke the Authenticate Payer operation with the payment session identifier.
  • On your website, receive the POST callback from the gateway following the Authenticate Payer operation and submit the payment for processing by the gateway with the payment session identifier.
Usage Note

Using the Initiate Authenticate and Authenticate Payer operations for 3-D Secure authentication requires you to manage a variety of authentication flows and understand the 3-D Secure version 2 data flows as published by EMVCo.

A more simple alternatively is to use the gateway's threeDS.js library.

URL https://na.gateway.mastercard.com/api/nvp/version/76
HTTP Method POST
Authentication This operation requires authentication via one of the following methods:
  • Certificate authentication.
  • To authenticate to the API two additional NVP parameters must be supplied in the request. Provide 'merchant.<your gateway merchant ID>' in the apiUsername field and your API password in the apiPassword field.

Request Parameters

apiOperation  String =INITIATE_AUTHENTICATION FIXED

Existence
FIXED
Fixed value
INITIATE_AUTHENTICATION
Validation Rules
Any sequence of zero or more unicode characters.
XSD type
string

merchant  Alphanumeric + additional characters = COMPULSORY

The unique identifier issued to you by your payment provider.
Existence
COMPULSORY
Fixed value
Validation Rules
Data may consist of the characters 0-9, a-z, A-Z, '-', '_'
XSD type
string
minimum length
1
maximum length
40

order.currency  Upper case alphabetic text = COMPULSORY

The currency of the transaction expressed as an ISO 4217 alpha code, e.g. USD.
Existence
COMPULSORY
Fixed value
Validation Rules
Data must consist of the characters A-Z
XSD type
string
minimum length
3
maximum length
3

order.id  String = COMPULSORY

A unique identifier for this order to distinguish it from any other order you create.
Use this identifier when referring to this order in subsequent transactions and in retrieval operations. This value must be unique for every order you create using your merchant profile.
Existence
COMPULSORY
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
40

session.id  ASCII Text = OPTIONAL

Identifier of the payment session containing values for any of the request fields to be used in this operation.
Values provided in the request will override values contained in the session.
Existence
OPTIONAL
Fixed value
Validation Rules
Data consists of ASCII characters
XSD type
string
minimum length
31
maximum length
35

transaction.id  String = COMPULSORY

Unique identifier for this transaction to distinguish it from any other transaction on the order.
An order can have transactions representing:
  • Movement of money. For example, payments and refunds.
  • Validations. For example, account verification or 3-D Secure authentication of the payer.
  • Undoing other transactions. For example, voiding a payment transaction.
  • Chargebacks.
  • Fees from your payment service provider.
Each transaction on the order must have a unique id that identifies that transaction. Some transactions also hold the transaction identifier of other transactions on the order. For example a void payment transaction references the original payment transaction that is being voided.

If you attempt an operation and it fails (eg you try to PAY on a card with no funds), then you need a new id for each retry.
Existence
COMPULSORY
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
40

apiOperation  String =INITIATE_AUTHENTICATION FIXED

Existence
FIXED
Fixed value
INITIATE_AUTHENTICATION
Validation Rules
Any sequence of zero or more unicode characters.
XSD type
string

authentication   = OPTIONAL

Information about how the payer's identity is verified.
For example, using 3-D Secure authentication.

This parameter group include payer authentication options available to you, parameters you need to perform payer authentication for an available method, and the results of payer authentication.
Fixed value

correlationId  String = OPTIONAL

A transient identifier for the request, that can be used to match the response to the request.
The value provided is not validated, does not persist in the gateway, and is returned as provided in the response to the request.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
100

merchant  Alphanumeric + additional characters = COMPULSORY

The unique identifier issued to you by your payment provider.
Existence
COMPULSORY
Fixed value
Validation Rules
Data may consist of the characters 0-9, a-z, A-Z, '-', '_'
XSD type
string
minimum length
1
maximum length
40

order   = OPTIONAL

Information about the order associated with this transaction.
Fixed value

order.reference  String = OPTIONAL

The identifier of the order.
For example, a shopping cart number, an order number, or an invoice number.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
40

order.subMerchant   = OPTIONAL

Provide these parameters if you are a payment aggregator or facilitator and process payments on behalf of other merchants.
These merchants are referred to as your sub-merchants.

The sub-merchant's details you provide may be displayed on the payer's cardholder statement.

Note that your acquirer may require you to register with the card scheme(s) before allowing you to submit sub-merchant details with a transaction.

This data must be on the initial transaction of an order, subsequent transactions with sub-merchant will be rejected.

Note: If you are requesting payer authentication using 3-D Secure Version 2 then you must provide values for order.subMerchant.address.country and order.subMerchant.bankIndustryCode.
Fixed value

order.subMerchant.address   = OPTIONAL

The sub-merchant's address.
Fixed value

order.subMerchant.address.city  String = OPTIONAL

The city portion of the address.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
100

order.subMerchant.address.company  String = OPTIONAL

The name of the company associated with this address.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
100

order.subMerchant.address.country  Upper case alphabetic text = OPTIONAL

The 3 letter ISO standard alpha country code of the address.
Existence
OPTIONAL
Fixed value
Validation Rules
Data must consist of the characters A-Z
XSD type
string
minimum length
3
maximum length
3

order.subMerchant.address.postcodeZip  Alphanumeric + additional characters = OPTIONAL

The post code or zip code of the address.
Existence
OPTIONAL
Fixed value
Validation Rules
Data may consist of the characters 0-9, a-z, A-Z, ' ', '-'
XSD type
string
minimum length
1
maximum length
10

order.subMerchant.address.stateProvince  String = OPTIONAL

The state or province of the address.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
20

order.subMerchant.address.street  String = OPTIONAL

The first line of the address.
For example, this may be the street name and number, or the Post Office Box details.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
100

order.subMerchant.address.street2  String = OPTIONAL

The second line of the address (if provided).
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
100

order.subMerchant.authentication[n]   = OPTIONAL

Information about the sub-merchant's registration to use a payer authentication protocol.
For example, using 3-D Secure authentication.
Fixed value

order.subMerchant.authentication[n].3DS2   = OPTIONAL

Information about the sub-merchant's registration to use 3-D Secure authentication version 2.
These details are used to identify the sub-merchant to the card scheme's directory server.
Fixed value

order.subMerchant.authentication[n].3DS2.requestorId  String = OPTIONAL

The unique identifier assigned to the merchant by the card scheme directory server when the merchant registered to use 3-D Secure authentication version 2 with their acquirer.
Do not provide this value for Mastercard SecureCode or Verified by Visa. For these authentication schemes, it will be generated by the gateway. For American Express if it is provided it will be used otherwise it will be generated by the gateway.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
35

order.subMerchant.authentication[n].3DS2.requestorName  String = OPTIONAL

The unique name assigned to the merchant by the card scheme directory server when the merchant registered to use 3-D Secure authentication version 2 with their acquirer.
Do not provide this value for Mastercard SecureCode or Verified by Visa. For these authentication schemes, it will be generated by the gateway. For American Express if it is provided it will be used otherwise it will be generated by the gateway.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
40

order.subMerchant.authentication[n].protocol  Enumeration = COMPULSORY

The protocol used for payer authentication.
Existence
COMPULSORY
Fixed value
Validation Rules
XSD type
string
Value must be a member of the following list. The values are case sensitive.
AMEX_SAFEKEY
American Express SafeKey EMV 3DS authentication
DINERS_PROTECTBUY
Diners ProtectBuy EMV 3DS authentication
FASTR_BY_CB
Carte Bancaire FAST'R by CB using EMV 3DS authentication
JCB_JSECURE
JCB J/Secure using EMV 3DS authentication
VERIFIED_BY_VISA
Visa Verified by Visa EMV 3DS authentication

order.subMerchant.bankIndustryCode  Digits = OPTIONAL

Code used by acquirer to describe the business or industry the sub-merchant operates in.
You must provide a value if you want the gateway to perform 3-D Secure Version 2 authentication of the payer.
Existence
OPTIONAL
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9.
XSD type
string
minimum length
4
maximum length
4

order.subMerchant.disputeContactPhone  Telephone Number = OPTIONAL

Only provide this field if you have received a notification from the scheme that either you or the sub-merchant has a high number of disputes.
In this case, provide a phone number that payers can use to contact the sub-merchant in case of a dispute. Where applicable, the issuer may display this phone number on the cardholder statement. The phone number must be provided in ITU-T E123 format.
Existence
OPTIONAL
Fixed value
Validation Rules
Data consists of '+', country code (1, 2 or 3 digits), 'space', and national number (which may embed single space characters for readability)
XSD type
string
mandatory country code
true
maximum total digits
15

order.subMerchant.email  Email = OPTIONAL

The sub-merchant's email address.
Existence
OPTIONAL
Fixed value
Validation Rules
Ensures that the email address is longer than 3 characters and adheres to a generous subset of valid RFC 2822 email addresses
XSD type
string

order.subMerchant.identifier  Alphanumeric + additional characters = COMPULSORY

Your identifier for the sub-merchant.
You can use this identifier in searches and reports in the gateway.
Existence
COMPULSORY
Fixed value
Validation Rules
Data may consist of the characters 0-9, a-z, A-Z, '-', '_', ' ', '&', '+', '!', '$', '.'
XSD type
string
minimum length
1
maximum length
100

order.subMerchant.phone  String = OPTIONAL

The sub-merchant's phone number
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
20

order.subMerchant.registeredName  String = OPTIONAL

The legal name of the sub-merchant.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
100

order.subMerchant.tradingName  String = COMPULSORY

The trading name of the sub-merchant, also known as doing business as (DBA), operating as or trading as.
For MasterCard transactions the name must not exceed 21 characters. For American Express transactions the name must not exceed 27 characters (or 36 characters including the aggregator name). The trading name may be displayed on the payer's cardholder statement. Therefore if you need to shorten it, use an abbreviation that will be meaningful to the payer when displayed on their statement.
Existence
COMPULSORY
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
100

order.subMerchant.websiteUrl  Url = OPTIONAL

The URL of the sub-merchant's website.
Existence
OPTIONAL
Fixed value
Validation Rules
Ensure that this is a valid URL according to RFC 1738.
XSD type
string

order.walletProvider  Enumeration = OPTIONAL

The wallet provider used to collect the customer's payment details used for this transaction.
Existence
OPTIONAL
Fixed value
Validation Rules
XSD type
string
Value must be a member of the following list. The values are case sensitive.
AMEX_EXPRESS_CHECKOUT
Amex Express Checkout wallet provider.
APPLE_PAY
Apple Pay mobile wallet provider.
CHASE_PAY
Chase Pay wallet provider.
GOOGLE_PAY
Google Pay mobile wallet provider.
MASTERPASS_ONLINE
MasterPass Online wallet provider.
SAMSUNG_PAY
Samsung Pay mobile wallet provider.
VISA_CHECKOUT
Visa Checkout wallet provider.

order.currency  Upper case alphabetic text = COMPULSORY

The currency of the transaction expressed as an ISO 4217 alpha code, e.g. USD.
Existence
COMPULSORY
Fixed value
Validation Rules
Data must consist of the characters A-Z
XSD type
string
minimum length
3
maximum length
3

order.id  String = COMPULSORY

A unique identifier for this order to distinguish it from any other order you create.
Use this identifier when referring to this order in subsequent transactions and in retrieval operations. This value must be unique for every order you create using your merchant profile.
Existence
COMPULSORY
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
40

order.merchantCategoryCode  Digits = OPTIONAL

A 4-digit code used to classify your business by the type of goods or services it offers.
This is also known as the Merchant Category Code (MCC).
You only need to provide the MCC if you want to override the default value configured for your acquirer link.The value you provide must match one of those configured by your payment service provider.
Existence
OPTIONAL
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9.
XSD type
string
minimum length
4
maximum length
4

order.notificationUrl  Url = OPTIONAL

The URL to which the gateway will send Webhook notifications when an order is created or updated.
To receive notifications at this URL, you must enable Webhook notifications in Merchant Administration. Ensure the URL is HTTPS
Existence
OPTIONAL
Fixed value
Validation Rules
Ensure that this is a valid URL according to RFC 1738.
XSD type
string

partnerSolutionId  String = OPTIONAL

If, when integrating with the gateway, you are using a solution (e.g. a shopping cart or e-commerce solution) provided, supported or certified by your payment service provider, enter the solution ID issued by your payment service provider here.
If your payment service provider has not provided you with a solution ID, you should ignore this field.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
40

session.id  ASCII Text = OPTIONAL

Identifier of the payment session containing values for any of the request fields to be used in this operation.
Values provided in the request will override values contained in the session.
Existence
OPTIONAL
Fixed value
Validation Rules
Data consists of ASCII characters
XSD type
string
minimum length
31
maximum length
35

session.version  ASCII Text = OPTIONAL

Use this field to implement optimistic locking of the session content.
Do this if you make business decisions based on data from the session and wish to ensure that the same data is being used for the request operation.

To use optimistic locking, record session.version when you make your decisions, and then pass that value in session.version when you submit your request operation to the gateway.

If session.version provided by you does not match that stored against the session, the gateway will reject the operation with error.cause=INVALID_REQUEST.

See Making Business Decisions Based on Session Content.
Existence
OPTIONAL
Fixed value
Validation Rules
Data consists of ASCII characters
XSD type
string
minimum length
10
maximum length
10

sourceOfFunds   = OPTIONAL

The details describing the source of the funds to be used.
For card payments these may be represented by combining one or more of the following: explicitly provided card details, a session identifier which the gateway will use to look up the card details and/or a card token. Precedence rules will be applied in that explicitly provided card details will override session card details which will override card token details. Each of these may represent partial card details, however the combination must result in a full and complete set of card details. See Using Multiple Sources of Card Details for examples.
Fixed value

sourceOfFunds.provided   = OPTIONAL

Information about the source of funds when it is directly provided (as opposed to via a token or session).
For browser payments, the source of funds details are usually collected from the payer on the payment provider's website and provided to you when you retrieve the transaction details (for a successful transaction). However, for some payment types (such as giropay), you must collect the information from the payer and supply it here.
Fixed value

sourceOfFunds.provided.card   = OPTIONAL

Details as shown on the card.
Fixed value

sourceOfFunds.provided.card.devicePayment   = OPTIONAL

If the payer chose to pay using a device you must provide payment details in this parameter group.
Use this parameter group when accepting payments using device payment methods such as Apple Pay, Android Pay or Samsung Pay.
Fixed value

sourceOfFunds.provided.card.devicePayment.cryptogramFormat  Enumeration = OPTIONAL

The format of the cryptogram provided for the digital payment.Use this field for:
  • • Device payments: provide the cryptogram format when you decrypt the payment token and provide the payment details (including the online payment cryptogram) in the transaction request.

This field does not apply to Card Scheme token payments.
Existence
OPTIONAL
Fixed value
Validation Rules
XSD type
string
Value must be a member of the following list. The values are case sensitive.
3DSECURE
The payment data keys for the online payment cryptogram are provided using the 3-D Secure format.
EMV
The payment data keys for the online payment cryptogram are provided using the EMV format.

sourceOfFunds.provided.card.devicePayment.eciIndicator  Digits = OPTIONAL

The Electronic Commerce Indicator generated for payments made using a device payment method.
You source this field directly from the decrypted payment token.

You must provide this field if you have it. This field is not applicable for payments using digital wallets.
Existence
OPTIONAL
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9.
XSD type
string
minimum length
1
maximum length
2

sourceOfFunds.provided.card.devicePayment.onlinePaymentCryptogram  Base64 = OPTIONAL

A cryptogram used to authenticate the transaction.
Use this field for:
  • • Device payments: source this field directly from the decrypted payment token.
  • • Card scheme tokens: source this field directly from the decrypted transaction credentials. For MDES (Mastercard Digital Enablement Service) tokens this is the UCAF cryptogram (de48se43Data). For VTS (Visa Token Service) tokens this is the TAVV cryptogram.
Existence
OPTIONAL
Fixed value
Validation Rules
Data is Base64 encoded
XSD type
string
minimum length
1
maximum length
128

sourceOfFunds.provided.card.devicePayment.paymentToken  String = OPTIONAL

This is the payment token that you received from the device's payment SDK.
For example:

For Apple Pay - this is the PKPaymentToken.paymentData value.

For Google - this is PaymentMethodToken.getToken().

Note 1: The gateway API considers this value to be a string, NOT JSON itself. Therefore when using the JSON gateway API, this field will typically look like:

"sourceOfFunds": {
"provided": {
"card": {
"devicePayment": {
"paymentToken": "{\"data\":\"869ss19ew ....

Note 2: The gateway will ignore the currency and amount information in the payment token, and will instead use the values passed on the amount and currency fields. For normal usage, you should populate those fields with the exact same values as you got from the SDK.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
16384

sourceOfFunds.provided.card.number  Digits = OPTIONAL

The account number of the payer's account used for this authentication.
On requests, provide the number in the form that you receive it (as explained below). On responses, the gateway populates it with a form that the payer would recognize (also explained in more detail below).

  • Request

    On request, populate this field based on the payment method you are using for the payment:
    • • Card: the account number embossed onto the card.
    • • Scheme tokens such as MDES (Mastercard Digital Enablement Service) - supply the value called the "Token PAN" or VTS (Visa Token Service) - supply the value called "token".
  • Response

    On return, the card number will be populated in 6.4 masking format, for example, 000000xxxxxx0000.
Existence
OPTIONAL
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9.
XSD type
string
minimum length
9
maximum length
19

sourceOfFunds.token  Alphanumeric = OPTIONAL

A gateway token that contains account identifier details.
The account identifier details stored against this token will be used to process the request.
If account identifier details are also contained in the request, or the request contains a session with account identifier details, these take precedence over the details stored against the token.
Existence
OPTIONAL
Fixed value
Validation Rules
Data may consist of the characters 0-9, a-z, A-Z
XSD type
string
minimum length
1
maximum length
40

sourceOfFunds.type  Enumeration = OPTIONAL

The payment method used for this authentication.
If you are passing card or scheme token data on the API, then you need to set this value, and also provide the card or token details in the sourceOfFunds.provided.card group.

If you are making a payment with a gateway token, then you can leave this field unset, and only populate the sourceOfFund.token field.
Existence
OPTIONAL
Fixed value
Validation Rules
XSD type
string
Value must be a member of the following list. The values are case sensitive.
CARD
Use this value for authentications using the card number.
SCHEME_TOKEN
Use this value for authentications using scheme tokens.

subgatewayMerchant   = OPTIONAL

Information about your merchant.
This group only applies if you:

  • operate a gateway, and
  • you are not boarding your merchants onto the gateway, and
  • you are enabled for this capability on the gateway.

If you are such a gateway, use these fields to provide information about your merchant, so that our gateway can process their transaction on your behalf.

Note: In these cases, you must also provide a value for field order.merchantCategoryCode

Fixed value

subgatewayMerchant.acquirer[n]   = COMPULSORY

Details about this merchant's account with the acquirers they use for payment processing.
A merchant might have one or more acquirers.

Each record in this group applies to one acquirer. If your gateway knows exactly which acquirer will use for this transaction, then you can provide just that acquirer's data. Alternatively, you can specify a set of acquirers, in which case the gateway will select between them based on the routing rules that configured in our gateway.

In this group, the term 'acquirer' includes banks acquiring scheme cards (such as MasterCard,or Visa), and alternative providers (such as UnionPay, or SEPA)
Fixed value

subgatewayMerchant.acquirer[n].3DS1   = OPTIONAL

Information about the merchant's registration to use 3-D Secure authentication version 1 for this acquirer.
Fixed value

subgatewayMerchant.acquirer[n].3DS1.mastercardSecureCode   = OPTIONAL

Information about the merchant's registration to use Mastercard SecureCode 3-D Secure authentication version 1 for this acquirer.
Fixed value

subgatewayMerchant.acquirer[n].3DS1.mastercardSecureCode.merchantId  String = OPTIONAL

The unique identifier assigned to the merchant by their acquirer when they registered to use Mastercard SecureCode 3-D Secure authentication version 1.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
24

subgatewayMerchant.acquirer[n].3DS1.verifiedByVisa   = OPTIONAL

Information about the merchant's registration to use Verified by Visa 3-D Secure authentication version 1 for this acquirer.
Fixed value

subgatewayMerchant.acquirer[n].3DS1.verifiedByVisa.cardAcceptorId  String = OPTIONAL

The unique identifier assigned to the merchant by their acquirer when they registered to use Verified by Visa 3-D Secure authentication version 1.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
15

subgatewayMerchant.acquirer[n].3DS1.verifiedByVisa.cardAcceptorTerminalId  String = OPTIONAL

The unique identifier of a terminal provided to the merchant by their acquirer when they registered to use Verified by Visa 3-D Secure authentication version 1.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
8

subgatewayMerchant.acquirer[n].acquirerMerchantId  String = COMPULSORY

The identifier (ID/SE Number/account name or such ) allocated to your merchant by their acquiring institution.
Existence
COMPULSORY
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
0
maximum length
40

subgatewayMerchant.acquirer[n].amexSafeKey   = OPTIONAL

Information about the merchant's registration to use American Express SafeKey 3-D Secure authentication for this acquirer.
Fixed value

subgatewayMerchant.acquirer[n].amexSafeKey.merchantId  Regex = OPTIONAL

The unique identifier assigned to the merchant by their acquirer when they registered to use American Express SafeKey 3-D Secure authentication.
Existence
OPTIONAL
Fixed value
Validation Rules
Data must match regex
XSD type
string
regex
\d{10}|\d{10};\w{10,20}
message
First 10 characters must be all numeric. If length is longer than 10, then 11th character must be a semi colon (;). There must be at least 10 characters following the semi colon. Minimum length 10 Maximum length 31

subgatewayMerchant.acquirer[n].countryCode  Upper case alphabetic text = OPTIONAL

The ISO 3166 three-letter country code of the acquirer.
Existence
OPTIONAL
Fixed value
Validation Rules
Data must consist of the characters A-Z
XSD type
string
minimum length
3
maximum length
3

subgatewayMerchant.acquirer[n].fraudRate  Integer = OPTIONAL

The merchant's fraud rate, as determined by the acquirer, expressed in basis points (bps).
Existence
OPTIONAL
Fixed value
Validation Rules
A number comprising the digits 0-9, having at least one digit. (For a complete description, see http://www.w3.org/TR/xmlschema-2/#nonNegativeInteger.)
XSD type
nonNegativeInteger
minimum value
0
maximum value
99999

subgatewayMerchant.acquirer[n].id  String = COMPULSORY

The name of the acquirer on which your merchant has an account.This is the value as returned in transaction.acquirer.id, for example ACME_BANK.
Your payment service provider will supply the acquirer names that apply to you.
Existence
COMPULSORY
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
0
maximum length
40

subgatewayMerchant.acquirer[n].merchantCategoryCode  Digits = OPTIONAL

A 4-digit code used to classify the merchant’s business by the type of goods or services it offers.
This is also known as the Merchant Category Code (MCC).
You only need to provide this value if you are specifying more than one acquirer link, and some acquirers need different MCC values. If the same MCC applies to all acquirers, just specify it as order.merchantCategoryCode.
Existence
OPTIONAL
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9.
XSD type
string
minimum length
4
maximum length
4

subgatewayMerchant.address   = OPTIONAL

The address of this merchant.
Fixed value

subgatewayMerchant.address.city  String = COMPULSORY

The city or town of this merchant's billing address.
Existence
COMPULSORY
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
30

subgatewayMerchant.address.countryCode  Upper case alphabetic text = COMPULSORY

The country of this merchant's billing address.
The value must be a three-letter country code according to ISO 3166-1 alpha-3.
Existence
COMPULSORY
Fixed value
Validation Rules
Data must consist of the characters A-Z
XSD type
string
minimum length
3
maximum length
3

subgatewayMerchant.address.postcodeZip  String = COMPULSORY

The zip or postal code of this merchant's billing address.
Existence
COMPULSORY
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
16

subgatewayMerchant.address.stateProvince  String = COMPULSORY

The state or province code of the merchant's billing address.
For merchants in the United States provide the 2-letter ISO 3166-2 state code. For US military bases provide one of AE, AA, AP.

For Canadian merchants provide the 2-letter ISO 3166-2 province code.
Existence
COMPULSORY
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
30

subgatewayMerchant.address.street1  String = COMPULSORY

The first line of the street address of this merchant's billing address.
Existence
COMPULSORY
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
40

subgatewayMerchant.address.street2  String = OPTIONAL

The second line of the street address of this merchant's billing address.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
40

subgatewayMerchant.authentication[n]   = OPTIONAL

Information about the merchant's registration to use a payer authentication protocol.
For example, using 3-D Secure authentication.
Fixed value

subgatewayMerchant.authentication[n].3DS2   = OPTIONAL

Information about the merchant's registration to use 3-D Secure authentication version 2.
These details are used to identify the merchant to the card schemes directory server.

This API assumes that a merchant has only one registration for a each 3DS2 scheme across all the acquirers. If your merchant has more than one 3DS2 registration that could apply to this transaction, then you need to provide a lineOfBusiness field to narrow to one registration.

Fixed value

subgatewayMerchant.authentication[n].3DS2.requestorId  String = OPTIONAL

The unique identifier assigned to the merchant by the card scheme directory server when the merchant registered to use 3-D Secure authentication version 2 with their acquirer.
Do not provide this value for Mastercard SecureCode, JCB JSecure, Discover ProtectBuy or Verified by Visa, For these authentication schemes, it will be generated by the gateway. For American Express if it is provided it will be used otherwise it will be generated by the gateway.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
35

subgatewayMerchant.authentication[n].3DS2.requestorName  String = OPTIONAL

The unique name assigned to the merchant by the card scheme directory server when the merchant registered to use 3-D Secure authentication version 2 with their acquirer.
Do not provide this value for Mastercard SecureCode, JCB JSecure, Discover ProtectBuy or Verified by Visa, For these authentication schemes, it will be generated by the gateway. For American Express if it is provided it will be used otherwise it will be generated by the gateway.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
40

subgatewayMerchant.authentication[n].acquirerBIN  Digits = OPTIONAL

The acquirer's Bank Identification Number (BIN).
This is used to identify the acquirer in messages to the scheme's Directory Server for 3-D Secure authentication version 2 transactions
Existence
OPTIONAL
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9.
XSD type
string
minimum length
4
maximum length
11

subgatewayMerchant.authentication[n].protocol  Enumeration = COMPULSORY

The protocol used for payer authentication.
Existence
COMPULSORY
Fixed value
Validation Rules
XSD type
string
Value must be a member of the following list. The values are case sensitive.
AMEX_SAFEKEY
American Express SafeKey EMV 3DS authentication
DINERS_PROTECTBUY
Diners ProtectBuy EMV 3DS authentication
FASTR_BY_CB
Carte Bancaire FAST'R by CB using EMV 3DS authentication
JCB_JSECURE
JCB J/Secure using EMV 3DS authentication
MASTERCARD_SECURECODE
Mastercard SecureCode EMV 3DS authentication
RUPAY
VERIFIED_BY_VISA
Visa Verified by Visa EMV 3DS authentication

subgatewayMerchant.id  Alphanumeric + additional characters = COMPULSORY

The identifier you use to uniquely identify this merchant on your system.
Existence
COMPULSORY
Fixed value
Validation Rules
Data may consist of the characters 0-9, a-z, A-Z, '_', '-'
XSD type
string
minimum length
1
maximum length
36

subgatewayMerchant.name  String = COMPULSORY

This merchant's registered business, trading or organization name.
This must match the merchant name you provided during registration with scheme Directory Servers.
Existence
COMPULSORY
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
100

subgatewayMerchant.websiteUrl  Url = COMPULSORY

The URL of the merchant's website.
You must provide a value if you want the gateway to perform 3-D Secure authentication of the payer.
Existence
COMPULSORY
Fixed value
Validation Rules
Ensure that this is a valid URL according to RFC 1738.
XSD type
string

transaction   = OPTIONAL

Information about this transaction.
Fixed value

transaction.reference  String = OPTIONAL

An optional identifier for this transaction.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
40

transaction.id  String = COMPULSORY

Unique identifier for this transaction to distinguish it from any other transaction on the order.
An order can have transactions representing:
  • Movement of money. For example, payments and refunds.
  • Validations. For example, account verification or 3-D Secure authentication of the payer.
  • Undoing other transactions. For example, voiding a payment transaction.
  • Chargebacks.
  • Fees from your payment service provider.
Each transaction on the order must have a unique id that identifies that transaction. Some transactions also hold the transaction identifier of other transactions on the order. For example a void payment transaction references the original payment transaction that is being voided.

If you attempt an operation and it fails (eg you try to PAY on a card with no funds), then you need a new id for each retry.
Existence
COMPULSORY
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
40

Response Parameters

merchant  Alphanumeric + additional characters = Always Provided

The unique identifier issued to you by your payment provider.
Existence
Always Provided
Fixed value
Validation Rules
Data may consist of the characters 0-9, a-z, A-Z, '-', '_'
XSD type
string
minimum length
1
maximum length
40

order   = Always Provided

Information about the order associated with this transaction.
Fixed value

order.creationTime  DateTime = Always Provided

Indicates the date and time the gateway considers the order to have been created.
Existence
Always Provided
Fixed value
Validation Rules
An instant in time expressed in ISO8601 date + time format - "YYYY-MM-DDThh:mm:ss.SSSZ"
XSD type
string

order.currency  Upper case alphabetic text = Always Provided

The currency of the order expressed as an ISO 4217 alpha code, e.g. USD.
Existence
Always Provided
Fixed value
Validation Rules
Data must consist of the characters A-Z
XSD type
string
minimum length
3
maximum length
3

order.id  String = Always Provided

A unique identifier for this order to distinguish it from any other order you create.
Use this identifier when referring to this order in subsequent transactions and in retrieval operations. This value must be unique for every order created by your merchant profile.
Existence
Always Provided
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
40

order.lastUpdatedTime  DateTime = Always Provided

Indicates the date and time the gateway considers the order to have last been updated.
Existence
Always Provided
Fixed value
Validation Rules
An instant in time expressed in ISO8601 date + time format - "YYYY-MM-DDThh:mm:ss.SSSZ"
XSD type
string

order.totalAuthorizedAmount  Decimal = Always Provided

The amount that has been successfully authorized for this order.
Existence
Always Provided
Fixed value
Validation Rules
A sequence of digits 0-9 separated by a '.' as a decimal indicator. Leading and trailing zeroes are optional. If the fractional part is zero, the '.' and following zero(es) can be omitted. (For a complete description, see http://www.w3.org/TR/xmlschema-2/#decimal.)
XSD type
decimal
maximum value
1000000000000
minimum value
0
maximum post-decimal digits
3

order.totalCapturedAmount  Decimal = Always Provided

The amount that has been successfully captured for this order.
Existence
Always Provided
Fixed value
Validation Rules
A sequence of digits 0-9 separated by a '.' as a decimal indicator. Leading and trailing zeroes are optional. If the fractional part is zero, the '.' and following zero(es) can be omitted. (For a complete description, see http://www.w3.org/TR/xmlschema-2/#decimal.)
XSD type
decimal
maximum value
1000000000000
minimum value
0
maximum post-decimal digits
3

order.totalRefundedAmount  Decimal = Always Provided

The amount that has been successfully refunded for this order.
Existence
Always Provided
Fixed value
Validation Rules
A sequence of digits 0-9 separated by a '.' as a decimal indicator. Leading and trailing zeroes are optional. If the fractional part is zero, the '.' and following zero(es) can be omitted. (For a complete description, see http://www.w3.org/TR/xmlschema-2/#decimal.)
XSD type
decimal
maximum value
1000000000000
minimum value
0
maximum post-decimal digits
3

response   = Always Provided

Fixed value

response.gatewayCode  Enumeration = Always Provided

Summary of the success or otherwise of the operation.
Existence
Always Provided
Fixed value
Validation Rules
XSD type
string
Value must be a member of the following list. The values are case sensitive.
ABORTED
Transaction aborted by payer
ACQUIRER_SYSTEM_ERROR
Acquirer system error occurred processing the transaction
APPROVED
Transaction Approved
APPROVED_AUTO
The transaction was automatically approved by the gateway. it was not submitted to the acquirer.
APPROVED_PENDING_SETTLEMENT
Transaction Approved - pending batch settlement
AUTHENTICATION_FAILED
Payer authentication failed
AUTHENTICATION_IN_PROGRESS
The operation determined that payer authentication is possible for the given card, but this has not been completed, and requires further action by the merchant to proceed.
BALANCE_AVAILABLE
A balance amount is available for the card, and the payer can redeem points.
BALANCE_UNKNOWN
A balance amount might be available for the card. Points redemption should be offered to the payer.
BLOCKED
Transaction blocked due to Risk or 3D Secure blocking rules
CANCELLED
Transaction cancelled by payer
DECLINED
The requested operation was not successful. For example, a payment was declined by issuer or payer authentication was not able to be successfully completed.
DECLINED_AVS
Transaction declined due to address verification
DECLINED_AVS_CSC
Transaction declined due to address verification and card security code
DECLINED_CSC
Transaction declined due to card security code
DECLINED_DO_NOT_CONTACT
Transaction declined - do not contact issuer
DECLINED_INVALID_PIN
Transaction declined due to invalid PIN
DECLINED_PAYMENT_PLAN
Transaction declined due to payment plan
DECLINED_PIN_REQUIRED
Transaction declined due to PIN required
DEFERRED_TRANSACTION_RECEIVED
Deferred transaction received and awaiting processing
DUPLICATE_BATCH
Transaction declined due to duplicate batch
EXCEEDED_RETRY_LIMIT
Transaction retry limit exceeded
EXPIRED_CARD
Transaction declined due to expired card
INSUFFICIENT_FUNDS
Transaction declined due to insufficient funds
INVALID_CSC
Invalid card security code
LOCK_FAILURE
Order locked - another transaction is in progress for this order
NOT_ENROLLED_3D_SECURE
Card holder is not enrolled in 3D Secure
NOT_SUPPORTED
Transaction type not supported
NO_BALANCE
A balance amount is not available for the card. The payer cannot redeem points.
PARTIALLY_APPROVED
The transaction was approved for a lesser amount than requested. The approved amount is returned in order.totalAuthorizedAmount.
PENDING
Transaction is pending
REFERRED
Transaction declined - refer to issuer
SUBMITTED
The transaction has successfully been created in the gateway. It is either awaiting submission to the acquirer or has been submitted to the acquirer but the gateway has not yet received a response about the success or otherwise of the payment.
SYSTEM_ERROR
Internal system error occurred processing the transaction
TIMED_OUT
The gateway has timed out the request to the acquirer because it did not receive a response. Points redemption should not be offered to the payer.
UNKNOWN
The transaction has been submitted to the acquirer but the gateway was not able to find out about the success or otherwise of the payment. If the gateway subsequently finds out about the success of the payment it will update the response code.
UNSPECIFIED_FAILURE
Transaction could not be processed

result  Enumeration = Always Provided

A system-generated high level overall result of the operation.
Existence
Always Provided
Fixed value
Validation Rules
XSD type
string
Value must be a member of the following list. The values are case sensitive.
FAILURE
The operation was declined or rejected by the gateway, acquirer or issuer
PENDING
The operation is currently in progress or pending processing
SUCCESS
The operation was successfully processed
UNKNOWN
The result of the operation is unknown

transaction   = Always Provided

Information about this transaction.
Fixed value

transaction.amount  Decimal = Always Provided

The total amount for the transaction.
Existence
Always Provided
Fixed value
Validation Rules
A sequence of digits 0-9 separated by a '.' as a decimal indicator. Leading and trailing zeroes are optional. If the fractional part is zero, the '.' and following zero(es) can be omitted. (For a complete description, see http://www.w3.org/TR/xmlschema-2/#decimal.)
XSD type
decimal
maximum value
1000000000000
minimum value
0
maximum post-decimal digits
3

transaction.currency  Upper case alphabetic text = Always Provided

The currency of the transaction expressed as an ISO 4217 alpha code, e.g. USD.
Existence
Always Provided
Fixed value
Validation Rules
Data must consist of the characters A-Z
XSD type
string
minimum length
3
maximum length
3

transaction.id  String = Always Provided

Unique identifier for this transaction to distinguish it from any other transaction on the order.
An order can have transactions representing:
  • Movement of money. For example, payments and refunds.
  • Validations. For example, account verification or 3-D Secure authentication of the payer.
  • Undoing other transactions. For example, voiding a payment transaction.
  • Chargebacks.
  • Fees from your payment service provider.
Each transaction on the order must have a unique id that identifies that transaction. Some transactions also hold the transaction identifier of other transactions on the order. For example a void payment transaction references the original payment transaction that is being voided.

If you attempt an operation and it fails (eg you try to PAY on a card with no funds), then you need a new id for each retry.
Existence
Always Provided
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
40

transaction.type  Enumeration = Always Provided

Indicates the type of action performed on the order.
Existence
Always Provided
Fixed value
Validation Rules
XSD type
string
Value must be a member of the following list. The values are case sensitive.
AUTHENTICATION
Authentication
AUTHORIZATION
Authorization
AUTHORIZATION_UPDATE
Authorization Update
CAPTURE
Capture
CHARGEBACK
Chargeback
DISBURSEMENT
Disbursement
FUNDING
The transaction transfers money to or from the merchant, without the involvement of a payer. For example, recording monthly merchant service fees from your payment service provider.
PAYMENT
Payment (Purchase)
REFUND
Refund
REFUND_REQUEST
Refund Request
VERIFICATION
Verification
VOID_AUTHORIZATION
Void Authorization
VOID_CAPTURE
Void Capture
VOID_PAYMENT
Void Payment
VOID_REFUND
Void Refund

authentication   = CONDITIONAL

Information about how the payer's identity is verified.
For example, using 3-D Secure authentication.
This parameter group include payer authentication options available to you, parameters you need to perform payer authentication for an available method, and the results of payer authentication.
Fixed value

authentication.3ds1   = CONDITIONAL

Information about payer authentication using 3-D Secure authentication version 1.
Fixed value

authentication.3ds1.veResEnrolled  Alpha = Always Provided

Indicates whether or not payer authentication is available for the card number you provided.
This is for experts only - most users should use the response.gatewayRecommendation field.

This is the value returned in the 'enrolled' field of the Verify Enrollment Response (VERes) message from the card scheme's Directory Server. For example, Y, N, or U. Refer to the relevant documentation for Mastercard SecureCode™, Verified by Visa™, JCB J/Secure™, American Express SafeKey™, or Diners Club ProtectBuy™.
Existence
Always Provided
Fixed value
Validation Rules
Data may consist of the characters a-z, A-Z
XSD type
string
minimum length
1
maximum length
1

authentication.redirect   = CONDITIONAL

Information you can use to optimize and initiate the user experience for payer authentication.
Put the HTML returned in field authentication.redirect.html in your payment page.

  • Initiate Authentication response: If supported by the issuer's Access Control Server (ACS), the HTML will submit a 3DS method call in your hidden iframe to the ACS. This call gathers additional browser information prior to the Authenticate Payer request and helps facilitate the transaction risk assessment by the issuer's ACS.

  • Authenticate Payer response: If required, the HTML will redirect the payer's browser to the issuer's ACS to complete the challenge.

Alternatively, you can use the details provided in the authentication.redirect.customizedHtml parameter group to create the required payer experience yourself. In this case you must follow the EMVCo specification. If a method call is required, the Initiate Authentication response provides the URL and POST data for the method call. If a challenge is required, the Authenticate Payer response provides the ACS URL and challenge request.
Fixed value

authentication.redirect.customizedHtml   = CONDITIONAL

If, instead of simply using authentication.redirect.html, you want to create the required user experience yourself, you can customize it using the parameters provided in this group.
See EMVCo specification for details about how to use the fields provided in this parameter group.
Fixed value

authentication.redirect.customizedHtml.3ds2   = CONDITIONAL

The parameters required to customize the payer experience for 3-D Secure authentication version 2.
Fixed value

authentication.redirect.customizedHtml.3ds2.methodPostData  Base64 = CONDITIONAL

Base64 URL encoded frame contents to be posted to the URL provided in authentication.redirect.customizedHtml.3ds2.methodUrl.
This is used by the issuer's Access Control Server (ACS) to obtain additional information about the payer's browser to assist their risk assessment process. This information will only be provided by the gateway if the payer's browser is present (authentication.channel=PAYER_BROWSER) and the issuer's Access Control Server (ACS) supports a method call.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data is Base64 encoded
XSD type
string
minimum length
3
maximum length
1000

authentication.redirect.customizedHtml.3ds2.methodUrl  Url = CONDITIONAL

The URL provided by the issuer to which you must post the data provided in authentication.redirect.customizedHtml.3ds2.methodPostData.
This information will only be provided by the gateway if the payer's browser is present (authentication.channel=PAYER_BROWSER) and the issuer's Access Control Server (ACS) supports a method call.
Existence
CONDITIONAL
Fixed value
Validation Rules
Ensure that this is a valid URL according to RFC 1738.
XSD type
string

authentication.redirect.html  String = CONDITIONAL

Write this HTML into an empty <DIV> element being the last element in the <BODY> element of your payment page.
This will execute the required next step in the payer authentication flow.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
0
maximum length
40960

correlationId  String = CONDITIONAL

A transient identifier for the request, that can be used to match the response to the request.
The value provided is not validated, does not persist in the gateway, and is returned as provided in the response to the request.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
100

encryptedData   = CONDITIONAL

This group is an encrypted JSON object containing authentication data obtained during the authentication process.
You can ignore this group if you are making a subsequent payment or Verify operation with the gateway, instead just rely on the response.gatewayRecommendation field.

However this group is applicable if:
  • you want to use 3-D Secure authentication data obtained to process the payment via another channel
  • you want to interpret some details of the 3-D Secure authentication response.
The data is encrypted by the gateway using, AES256 in GCM mode. To decrypt, use the key obtained from the Create Session response and the parameters in this group.

The decryption will yield a JSON object which will contain a subset of the following fields.
  • authentication.3ds.authenticationToken
  • authentication.3ds.acsEci
  • authentication.3ds.transactionId
  • authentication.3ds2.statusReasonCode
  • authentication.3ds2.transactionStatus
  • authentication.3ds2.dsTransactionId
  • authentication.3ds1.veResEnrolled
  • authentication.3ds1.paResStatus
  • sourceOfFunds.provided.card.expiry.month
  • sourceOfFunds.provided.card.expiry.year
  • sourceOfFunds.provided.card.number
  • sourceOfFunds.token
  • order.id
  • transaction.authenticationStatus
  • transaction.id
These elements correspond to the similarly named items in the response to merchant-authenticated Authenticate Payer requests.
Fixed value

encryptedData.ciphertext  String = Always Provided

Base64 encoded ciphertext.
Existence
Always Provided
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
10000

encryptedData.nonce  String = Always Provided

Base64 encoded GCM nonce.
Existence
Always Provided
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
16
maximum length
16

encryptedData.tag  String = Always Provided

Base64 encoded GCM tag.
Existence
Always Provided
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
24
maximum length
24

lineOfBusiness  String = CONDITIONAL

Your payment service provider might have configured your merchant profile to support several lines of business.
Each line of business can have different payment parameters, such as bank account, supported cards or such.

For example, lineOfBusiness = TICKET_SALES can have a different bank account from lineOfBusiness = MERCHANDISING. One line of business on your profile might be "null". To use that, do not provide the lineOfBusiness field.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters except space
XSD type
string
minimum length
1
maximum length
100

merchant  Alphanumeric + additional characters = Always Provided

The unique identifier issued to you by your payment provider.
Existence
Always Provided
Fixed value
Validation Rules
Data may consist of the characters 0-9, a-z, A-Z, '-', '_'
XSD type
string
minimum length
1
maximum length
40

order   = Always Provided

Information about the order associated with this transaction.
Fixed value

order.authenticationStatus  Enumeration = CONDITIONAL

Indicates the result of payer authentication.
Existence
CONDITIONAL
Fixed value
Validation Rules
XSD type
string
Value must be a member of the following list. The values are case sensitive.
AUTHENTICATION_ATTEMPTED
Payer authentication was attempted and a proof of authentication attempt was obtained.
AUTHENTICATION_AVAILABLE
Payer authentication is available for the payment method provided.
AUTHENTICATION_EXEMPT
Exemption from the Regulatory Technical Standards (RTS) requirements for Strong Customer Authentication (SCA) under the Payment Services Directive 2 (PSD2) regulations in the European Economic Area has been claimed or granted.
AUTHENTICATION_FAILED
The payer was not authenticated. You should not proceed with this transaction.
AUTHENTICATION_NOT_IN_EFFECT
There is no authentication information associated with this transaction.
AUTHENTICATION_NOT_SUPPORTED
The requested authentication method is not supported for this payment method.
AUTHENTICATION_PENDING
Payer authentication is pending completion of a challenge process.
AUTHENTICATION_REJECTED
The issuer rejected the authentication request and requested that you do not attempt authorization of a payment.
AUTHENTICATION_REQUIRED
Payer authentication is required for this payment, but was not provided.
AUTHENTICATION_SUCCESSFUL
The payer was successfully authenticated.
AUTHENTICATION_UNAVAILABLE
The payer was not able to be authenticated due to a technical or other issue.

order.creationTime  DateTime = Always Provided

Indicates the date and time the gateway considers the order to have been created.
Existence
Always Provided
Fixed value
Validation Rules
An instant in time expressed in ISO8601 date + time format - "YYYY-MM-DDThh:mm:ss.SSSZ"
XSD type
string

order.currency  Upper case alphabetic text = Always Provided

The currency of the order expressed as an ISO 4217 alpha code, e.g. USD.
Existence
Always Provided
Fixed value
Validation Rules
Data must consist of the characters A-Z
XSD type
string
minimum length
3
maximum length
3

order.id  String = Always Provided

A unique identifier for this order to distinguish it from any other order you create.
Use this identifier when referring to this order in subsequent transactions and in retrieval operations. This value must be unique for every order created by your merchant profile.
Existence
Always Provided
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
40

order.lastUpdatedTime  DateTime = Always Provided

Indicates the date and time the gateway considers the order to have last been updated.
Existence
Always Provided
Fixed value
Validation Rules
An instant in time expressed in ISO8601 date + time format - "YYYY-MM-DDThh:mm:ss.SSSZ"
XSD type
string

order.merchantCategoryCode  Digits = CONDITIONAL

A 4-digit code used to classify your business by the type of goods or services it offers.This is also known as the Merchant Category Code (MCC).
You only need to provide the MCC if you want to override the default value configured for your acquirer link.The value you provide must match one of those configured by your payment service provider.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9.
XSD type
string
minimum length
4
maximum length
4

order.notificationUrl  Url = CONDITIONAL

The URL to which the gateway will send Webhook notifications when an order is created or updated.
To receive notifications at this URL, you must enable Webhook notifications in Merchant Administration. Ensure the URL is HTTPS
Existence
CONDITIONAL
Fixed value
Validation Rules
Ensure that this is a valid URL according to RFC 1738.
XSD type
string

order.reference  String = CONDITIONAL

An optional identifier for the order.
For example, a shopping cart number, an order number, or an invoice number.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
200

order.status  Enumeration = CONDITIONAL

The current progression of this order through the payment process.
Existence
CONDITIONAL
Fixed value
Validation Rules
XSD type
string
Value must be a member of the following list. The values are case sensitive.
AUTHENTICATED
The payer was successfully authenticated.
AUTHENTICATION_INITIATED
Payer authentication has been initiated but not completed.
AUTHENTICATION_NOT_NEEDED
Payer authentication was not performed as it was not needed.
AUTHENTICATION_UNSUCCESSFUL
Payer authentication was not able to be successfully completed.
AUTHORIZED
The payment has been authorized successfully but the authorized amount has not yet been captured, in part, full, or excess.
CANCELLED
The initial transaction for this order has been voided successfully.
CAPTURED
The authorized amount for this order, in full or excess, has been captured successfully.
CHARGEBACK_PROCESSED
A Chargeback has been processed against this order.
DISBURSED
The order amount has successfully been disbursed to the payer.
DISPUTED
The payment has been disputed and is under investigation. A request for information has been received or a chargeback is pending.
EXCESSIVELY_REFUNDED
The payment has been captured in part, full, or excess, but the captured amount in excess has been refunded successfully.
FAILED
The payment has not been successful.
FUNDING
The order transfers money to or from the merchant, without the involvement of a payer. For example, recording monthly merchant service fees from your payment service provider.
INITIATED
A browser payment that has successfully been initiated for this order. No payment has yet been made.
PARTIALLY_CAPTURED
The authorized amount for this order, in part, has been captured successfully.
PARTIALLY_REFUNDED
The payment has been captured in part, full, or excess, but the captured amount in part has been refunded successfully.
REFUNDED
The payment has been captured in part, full, or excess, but the captured amount in full has been refunded successfully.
REFUND_REQUESTED
A refund against captured amounts on this order has been requested but not executed. Requires further action to approve the refund.
VERIFIED
The card details for this order have successfully been verified. No payment has yet been initiated or made.

order.subMerchant   = CONDITIONAL

Provide these parameters if you are a payment aggregator or facilitator and process payments on behalf of other merchants.
These merchants are referred to as your sub-merchants.

The sub-merchant's details you provide may be displayed on the payer's cardholder statement.

Note that your acquirer may require you to register with the card scheme(s) before allowing you to submit sub-merchant details with a transaction.

This data must be on the initial transaction of an order, subsequent transactions with sub-merchant will be rejected.

Note: If you are requesting payer authentication using 3-D Secure Version 2 then you must provide values for order.subMerchant.address.country and order.subMerchant.bankIndustryCode.
Fixed value

order.subMerchant.address   = CONDITIONAL

The sub-merchant's address.
Fixed value

order.subMerchant.address.city  String = CONDITIONAL

The city portion of the address.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
100

order.subMerchant.address.company  String = CONDITIONAL

The name of the company associated with this address.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
100

order.subMerchant.address.country  Upper case alphabetic text = CONDITIONAL

The 3 letter ISO standard alpha country code of the address.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data must consist of the characters A-Z
XSD type
string
minimum length
3
maximum length
3

order.subMerchant.address.postcodeZip  Alphanumeric + additional characters = CONDITIONAL

The post code or zip code of the address.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data may consist of the characters 0-9, a-z, A-Z, ' ', '-'
XSD type
string
minimum length
1
maximum length
10

order.subMerchant.address.stateProvince  String = CONDITIONAL

The state or province of the address.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
20

order.subMerchant.address.street  String = CONDITIONAL

The first line of the address.
For example, this may be the street name and number, or the Post Office Box details.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
100

order.subMerchant.address.street2  String = CONDITIONAL

The second line of the address (if provided).
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
100

order.subMerchant.authentication[n]   = CONDITIONAL

Information about the sub-merchant's registration to use a payer authentication protocol.
For example, using 3-D Secure authentication.
Fixed value

order.subMerchant.authentication[n].3DS2   = CONDITIONAL

Information about the sub-merchant's registration to use 3-D Secure authentication version 2.
These details are used to identify the sub-merchant to the card scheme's directory server.
Fixed value

order.subMerchant.authentication[n].3DS2.requestorId  String = CONDITIONAL

The unique identifier assigned to the merchant by the card scheme directory server when the merchant registered to use 3-D Secure authentication version 2 with their acquirer.
Do not provide this value for Mastercard SecureCode or Verified by Visa. For these authentication schemes, it will be generated by the gateway. For American Express if it is provided it will be used otherwise it will be generated by the gateway.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
35

order.subMerchant.authentication[n].3DS2.requestorName  String = CONDITIONAL

The unique name assigned to the merchant by the card scheme directory server when the merchant registered to use 3-D Secure authentication version 2 with their acquirer.
Do not provide this value for Mastercard SecureCode or Verified by Visa. For these authentication schemes, it will be generated by the gateway. For American Express if it is provided it will be used otherwise it will be generated by the gateway.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
40

order.subMerchant.authentication[n].protocol  Enumeration = Always Provided

The protocol used for payer authentication.
Existence
Always Provided
Fixed value
Validation Rules
XSD type
string
Value must be a member of the following list. The values are case sensitive.
AMEX_SAFEKEY
American Express SafeKey EMV 3DS authentication
DINERS_PROTECTBUY
Diners ProtectBuy EMV 3DS authentication
FASTR_BY_CB
Carte Bancaire FAST'R by CB using EMV 3DS authentication
JCB_JSECURE
JCB J/Secure using EMV 3DS authentication
VERIFIED_BY_VISA
Visa Verified by Visa EMV 3DS authentication

order.subMerchant.bankIndustryCode  Digits = CONDITIONAL

Code used by acquirer to describe the business or industry the sub-merchant operates in.
You must provide a value if you want the gateway to perform 3-D Secure Version 2 authentication of the payer.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9.
XSD type
string
minimum length
4
maximum length
4

order.subMerchant.disputeContactPhone  Telephone Number = CONDITIONAL

Only provide this field if you have received a notification from the scheme that either you or the sub-merchant has a high number of disputes.
In this case, provide a phone number that payers can use to contact the sub-merchant in case of a dispute. Where applicable, the issuer may display this phone number on the cardholder statement. The phone number must be provided in ITU-T E123 format.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data consists of '+', country code (1, 2 or 3 digits), 'space', and national number (which may embed single space characters for readability)
XSD type
string
mandatory country code
true
maximum total digits
15

order.subMerchant.email  Email = CONDITIONAL

The sub-merchant's email address.
Existence
CONDITIONAL
Fixed value
Validation Rules
Ensures that the email address is longer than 3 characters and adheres to a generous subset of valid RFC 2822 email addresses
XSD type
string

order.subMerchant.identifier  Alphanumeric + additional characters = Always Provided

Your identifier for the sub-merchant.
You can use this identifier in searches and reports in the gateway.
Existence
Always Provided
Fixed value
Validation Rules
Data may consist of the characters 0-9, a-z, A-Z, '-', '_', ' ', '&', '+', '!', '$', '.'
XSD type
string
minimum length
1
maximum length
100

order.subMerchant.phone  String = CONDITIONAL

The sub-merchant's phone number
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
20

order.subMerchant.registeredName  String = CONDITIONAL

The legal name of the sub-merchant.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
100

order.subMerchant.tradingName  String = Always Provided

The trading name of the sub-merchant, also known as doing business as (DBA), operating as or trading as.
For MasterCard transactions the name must not exceed 21 characters. For American Express transactions the name must not exceed 27 characters (or 36 characters including the aggregator name). The trading name may be displayed on the payer's cardholder statement. Therefore if you need to shorten it, use an abbreviation that will be meaningful to the payer when displayed on their statement.
Existence
Always Provided
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
100

order.subMerchant.websiteUrl  Url = CONDITIONAL

The URL of the sub-merchant's website.
Existence
CONDITIONAL
Fixed value
Validation Rules
Ensure that this is a valid URL according to RFC 1738.
XSD type
string

order.totalAuthorizedAmount  Decimal = Always Provided

The amount that has been successfully authorized for this order.
Existence
Always Provided
Fixed value
Validation Rules
A sequence of digits 0-9 separated by a '.' as a decimal indicator. Leading and trailing zeroes are optional. If the fractional part is zero, the '.' and following zero(es) can be omitted. (For a complete description, see http://www.w3.org/TR/xmlschema-2/#decimal.)
XSD type
decimal
maximum value
1000000000000
minimum value
0
maximum post-decimal digits
3

order.totalCapturedAmount  Decimal = Always Provided

The amount that has been successfully captured for this order.
Existence
Always Provided
Fixed value
Validation Rules
A sequence of digits 0-9 separated by a '.' as a decimal indicator. Leading and trailing zeroes are optional. If the fractional part is zero, the '.' and following zero(es) can be omitted. (For a complete description, see http://www.w3.org/TR/xmlschema-2/#decimal.)
XSD type
decimal
maximum value
1000000000000
minimum value
0
maximum post-decimal digits
3

order.totalRefundedAmount  Decimal = Always Provided

The amount that has been successfully refunded for this order.
Existence
Always Provided
Fixed value
Validation Rules
A sequence of digits 0-9 separated by a '.' as a decimal indicator. Leading and trailing zeroes are optional. If the fractional part is zero, the '.' and following zero(es) can be omitted. (For a complete description, see http://www.w3.org/TR/xmlschema-2/#decimal.)
XSD type
decimal
maximum value
1000000000000
minimum value
0
maximum post-decimal digits
3

order.walletProvider  Enumeration = CONDITIONAL

The wallet provider used to collect the customer's payment details used for this transaction.
Existence
CONDITIONAL
Fixed value
Validation Rules
XSD type
string
Value must be a member of the following list. The values are case sensitive.
AMEX_EXPRESS_CHECKOUT
Amex Express Checkout wallet provider.
APPLE_PAY
Apple Pay mobile wallet provider.
CHASE_PAY
Chase Pay wallet provider.
GOOGLE_PAY
Google Pay mobile wallet provider.
MASTERPASS_ONLINE
MasterPass Online wallet provider.
SAMSUNG_PAY
Samsung Pay mobile wallet provider.
VISA_CHECKOUT
Visa Checkout wallet provider.

partnerSolutionId  String = CONDITIONAL

If, when integrating with the gateway, you are using a solution (e.g. a shopping cart or e-commerce solution) provided, supported or certified by your payment service provider, enter the solution ID issued by your payment service provider here.
If your payment service provider has not provided you with a solution ID, you should ignore this field.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
40

response   = Always Provided

Fixed value

response.accountUpdater   = CONDITIONAL

If the gateway submitted a request to the scheme's Account Updater service, this parameter group contains details about the outcome of this request.
Fixed value

response.accountUpdater.gatewayCode  Enumeration = CONDITIONAL

Code generated by the gateway that indicates if the card details were updated by Account Updater before the transaction was submitted to the acquirer for processing.
If response.accountUpdater.gatewayCode=UPDATED, invoke the Retrieve Token request to check if a replacement token has been generated. This step is not required to be completed immediately.
The gateway assigns a replacement token, if your token repository is configured with the 'UNIQUE_ACCOUNT_IDENTIFIER' token management strategy and the repository already contains a token for the new card that was updated by the Account Updater.
For more details see Gateway Tokenization
Existence
CONDITIONAL
Fixed value
Validation Rules
XSD type
string
Value must be a member of the following list. The values are case sensitive.
NOT_UPDATED
The card details were not updated.
UPDATED
The card details were updated and these details were used to process the transaction request and are contained in the sourceOfFunds parameter group. The token contained in the request has also been updated with these details.

response.debugInformation  String = CONDITIONAL

The container for additional information about a transaction.
Only returned for some errors and is dependent on the merchant's configuration. Returned in error, declined and approved scenarios, but would only be used to trouble shoot issues.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
2064

response.gatewayCode  Enumeration = Always Provided

Summary of the success or otherwise of the operation.
Existence
Always Provided
Fixed value
Validation Rules
XSD type
string
Value must be a member of the following list. The values are case sensitive.
ABORTED
Transaction aborted by payer
ACQUIRER_SYSTEM_ERROR
Acquirer system error occurred processing the transaction
APPROVED
Transaction Approved
APPROVED_AUTO
The transaction was automatically approved by the gateway. it was not submitted to the acquirer.
APPROVED_PENDING_SETTLEMENT
Transaction Approved - pending batch settlement
AUTHENTICATION_FAILED
Payer authentication failed
AUTHENTICATION_IN_PROGRESS
The operation determined that payer authentication is possible for the given card, but this has not been completed, and requires further action by the merchant to proceed.
BALANCE_AVAILABLE
A balance amount is available for the card, and the payer can redeem points.
BALANCE_UNKNOWN
A balance amount might be available for the card. Points redemption should be offered to the payer.
BLOCKED
Transaction blocked due to Risk or 3D Secure blocking rules
CANCELLED
Transaction cancelled by payer
DECLINED
The requested operation was not successful. For example, a payment was declined by issuer or payer authentication was not able to be successfully completed.
DECLINED_AVS
Transaction declined due to address verification
DECLINED_AVS_CSC
Transaction declined due to address verification and card security code
DECLINED_CSC
Transaction declined due to card security code
DECLINED_DO_NOT_CONTACT
Transaction declined - do not contact issuer
DECLINED_INVALID_PIN
Transaction declined due to invalid PIN
DECLINED_PAYMENT_PLAN
Transaction declined due to payment plan
DECLINED_PIN_REQUIRED
Transaction declined due to PIN required
DEFERRED_TRANSACTION_RECEIVED
Deferred transaction received and awaiting processing
DUPLICATE_BATCH
Transaction declined due to duplicate batch
EXCEEDED_RETRY_LIMIT
Transaction retry limit exceeded
EXPIRED_CARD
Transaction declined due to expired card
INSUFFICIENT_FUNDS
Transaction declined due to insufficient funds
INVALID_CSC
Invalid card security code
LOCK_FAILURE
Order locked - another transaction is in progress for this order
NOT_ENROLLED_3D_SECURE
Card holder is not enrolled in 3D Secure
NOT_SUPPORTED
Transaction type not supported
NO_BALANCE
A balance amount is not available for the card. The payer cannot redeem points.
PARTIALLY_APPROVED
The transaction was approved for a lesser amount than requested. The approved amount is returned in order.totalAuthorizedAmount.
PENDING
Transaction is pending
REFERRED
Transaction declined - refer to issuer
SUBMITTED
The transaction has successfully been created in the gateway. It is either awaiting submission to the acquirer or has been submitted to the acquirer but the gateway has not yet received a response about the success or otherwise of the payment.
SYSTEM_ERROR
Internal system error occurred processing the transaction
TIMED_OUT
The gateway has timed out the request to the acquirer because it did not receive a response. Points redemption should not be offered to the payer.
UNKNOWN
The transaction has been submitted to the acquirer but the gateway was not able to find out about the success or otherwise of the payment. If the gateway subsequently finds out about the success of the payment it will update the response code.
UNSPECIFIED_FAILURE
Transaction could not be processed

response.gatewayRecommendation  Enumeration = CONDITIONAL

Provides a recommendation for your next action based on the outcome of this transaction.
The recommendation may advise you that you:
  • can proceed as planned.
  • must not proceed. For example, because there is suspected fraud.
  • can take action to obtain a successful Authorization. For example, by authenticating the payer, or asking the payer for updated or new payment details.
  • must make a review decision.
Existence
CONDITIONAL
Fixed value
Validation Rules
XSD type
string
Value must be a member of the following list. The values are case sensitive.
DO_NOT_PROCEED
Do not proceed using this card. This will be presented if the gateway fails the request, but there is no apparent way for this transaction to succeed.
PROCEED
Proceed with the next step in processing this payment. If the Initiate Authentication response indicated that payer authentication is available, proceed with authenticating the payer using the Authenticate Payer operation. If the Authenticate Payer operation indicates that the payer is sufficiently authenticated, proceed with submitting an Authorize or Pay request. If the Authorization for the payment was successful proceed with capturing the funds and if applicable, ship the goods.
RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS
Ask the payer for alternative payment details (e.g. a new card or another payment method) and resubmit the request with the new details. Do not resubmit the same request.

result  Enumeration = Always Provided

A system-generated high level overall result of the operation.
Existence
Always Provided
Fixed value
Validation Rules
XSD type
string
Value must be a member of the following list. The values are case sensitive.
FAILURE
The operation was declined or rejected by the gateway, acquirer or issuer
PENDING
The operation is currently in progress or pending processing
SUCCESS
The operation was successfully processed
UNKNOWN
The result of the operation is unknown

sourceOfFunds   = CONDITIONAL

Information about the payment type selected by the payer for this payment and the source of the funds.
Depending on the payment type the source of the funds can be a debit or credit card, bank account, or account with a browser payment provider (such as PayPal).

For card payments the source of funds information may be represented by combining one or more of the following: explicitly provided card details, a session identifier which the gateway will use to look up the card details and/or a card token. Precedence rules will be applied in that explicitly provided card details will override session card details which will override card token details. Each of these may represent partial card details, however the combination must result in a full and complete set of card details. See Using Multiple Sources of Card Details for examples.
Fixed value

sourceOfFunds.provided   = CONDITIONAL

Information about the source of funds when it is directly provided (as opposed to via a token or session).
For browser payments, the source of funds details are usually collected from the payer on the payment provider's website and provided to you when you retrieve the transaction details (for a successful transaction). However, for some payment types (such as giropay), you must collect the information from the payer and supply it here.
Fixed value

sourceOfFunds.provided.ach   = CONDITIONAL

For ACH payments, the details about the payers bank account used for the payment as well as the type of ACH payment are provided in this parameter group.
Fixed value

sourceOfFunds.provided.ach.accountType  Enumeration = CONDITIONAL

An indicator identifying the type of bank account.
  • Consumer (checking or savings), or
  • Business

For pre-arranged payments (sourceOfFunds.provided.ach.secCode=PPD) retrieve this information from the payer.

If payments were telephone-initiated (sourceOfFunds.provided.ach.secCode=TEL) or internet-initiated (sourceOfFunds.provided.ach.secCode=WEB) you may choose to limit the payer's options (e.g. only support consumer checking accounts), depending on your type of business (e.g. B2C online webshop).

Existence
CONDITIONAL
Fixed value
Validation Rules
XSD type
string
Value must be a member of the following list. The values are case sensitive.
CONSUMER_CHECKING
Consumer Checking Account
CONSUMER_SAVINGS
Consumer Savings Account
CORPORATE_CHECKING
Business Checking Account

sourceOfFunds.provided.ach.bankAccountHolder  String = CONDITIONAL

The name of the bank account holder, as it appears on the account at the receiving financial institution.
Retrieve this information from the payer.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
28

sourceOfFunds.provided.ach.bankAccountNumber  Alphanumeric + additional characters = CONDITIONAL

The identifier of the bank account at the receiving financial institution.
By default, the bank account number will be returned in a masked format, for example, xxxxxx0000. If you wish to return unmasked bank account numbers, you must have the requisite permission, set responseControls.sensitiveData, and authenticate your call to the API using certificate authentication. Contact your payment service provider for further information.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data may consist of the characters 0-9, a-z, A-Z, ' ', '-', '/'
XSD type
string
minimum length
1
maximum length
17

sourceOfFunds.provided.ach.routingNumber  Digits = CONDITIONAL

The identifier of the receiving financial institution.
Also known as:
  • Routing number,
  • Transit number, or
  • ABA number

Retrieve this information from the payer.

See also http://en.wikipedia.org/wiki/Routing_transit_number.

Existence
CONDITIONAL
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9.
XSD type
string
minimum length
9
maximum length
9

sourceOfFunds.provided.ach.secCode  Enumeration = CONDITIONAL

Identifies the Standard Entry Class (SEC) code to be sent to the issuer.
The SEC is defined by NACHA and describes the origin and intent of the payment. For details please refer to https://www.nacha.org/.
Existence
CONDITIONAL
Fixed value
Validation Rules
XSD type
string
Value must be a member of the following list. The values are case sensitive.
PPD
An ACH debit or credit payment (B2C) that has been authorized by an authenticated customer in written form (signed or similarly authenticated). PPD is used for pre-arranged payments (e.g. employee payroll, mortgage payments, expense reimbursement).
TEL
An ACH debit payment (B2C) that has been authorized by an authenticated customer via phone. TEL may only be used if a relationship already exists between you and the consumer, or, the consumer initiates the contact with you.
WEB
An ACH debit payment (B2C) that has been authorized by an authenticated customer via the internet or a wireless network.

sourceOfFunds.provided.bancontact   = CONDITIONAL

Additional details related to a Bancontact payment.
Fixed value

sourceOfFunds.provided.bancontact.bankAccountHolder  String = Always Provided

The name of the bank account holder for the payer's bank account.
Existence
Always Provided
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
255

sourceOfFunds.provided.blik   = CONDITIONAL

Additional details related to a BLIK browser payment.
Fixed value

sourceOfFunds.provided.blik.bankAccountHolder  String = Always Provided

The name of the bank account holder for the payer's bank account.
Existence
Always Provided
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
255

sourceOfFunds.provided.boletoBancario   = CONDITIONAL

Additional details related to a Boleto Bancario browser payment.
When processing a Boleto Bancario payment you must also provide the payer's national identifier (customer.nationalId), your reference to the payer (customer.id) and the payer's date of birth (customer.dateOfBirth)
Fixed value

sourceOfFunds.provided.boletoBancario.actionType  Enumeration = CONDITIONAL

The action to take if the payment is not honored.
Existence
CONDITIONAL
Fixed value
Validation Rules
XSD type
string
Value must be a member of the following list. The values are case sensitive.
WRITE_OFF
Write off the Boleto.

sourceOfFunds.provided.boletoBancario.bankAccountHolder  String = Always Provided

The name of the bank account holder for the payer's bank account.
Existence
Always Provided
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
255

sourceOfFunds.provided.boletoBancario.customerType  Enumeration = CONDITIONAL

Type of the Customer i.e. Individual or Company.
If the value is not provided it will be defaulted to INDIVIDUAL.
Existence
CONDITIONAL
Fixed value
Validation Rules
XSD type
string
Value must be a member of the following list. The values are case sensitive.
COMPANY
Customer is an organization.
INDIVIDUAL
Customer is an individual.

sourceOfFunds.provided.boletoBancario.daysBeforeAction  Digits = CONDITIONAL

Number of days granted by you to the customer after the due date of Boleto payment before the specified action is taken.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9.
XSD type
string
minimum length
1
maximum length
2

sourceOfFunds.provided.boletoBancario.dueDate  Date = CONDITIONAL

The date by which the Boleto amount needs to be paid.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data must comply with ISO 8601 extended date format, yyyy-mm-dd
XSD type
string

sourceOfFunds.provided.boletoBancario.slipUrl  Url = CONDITIONAL

The URL issued by the gateway which you must use to retrieve collection bank slip.
Existence
CONDITIONAL
Fixed value
Validation Rules
Ensure that this is a valid URL according to RFC 1738.
XSD type
string

sourceOfFunds.provided.card   = CONDITIONAL

Details about the card.
Use this parameter group when you have sourced payment details using:
Cards: the card details entered directly or collected using a Point of Sale (POS) terminal.
Device payment methods such as Apple Pay, Android Pay, Samsung Pay or Google Pay.
Digital wallets such as Masterpass, Visa Checkout or Amex Express Checkout.
Card scheme tokens where the card was tokenized using a card scheme tokenization service such as Mastercard Digital Enablement Service (MDES).
Fixed value

sourceOfFunds.provided.card.accountType  Enumeration = CONDITIONAL

You can provide this field for card types that have a savings/checking option, such as Maestro cards.
If you do not provide a value, we will use the acquirer's default. You can use paymentTypes.card.cardTypes in the 'Retrieve Payment Options' operation response to determine the card type.
Existence
CONDITIONAL
Fixed value
Validation Rules
XSD type
string
Value must be a member of the following list. The values are case sensitive.
CHECKING
SAVINGS

sourceOfFunds.provided.card.brand  Enumeration = Always Provided

The brand name used to describe the card that is recognized and accepted globally.
For many major card types this will match the scheme name. In some markets, a card may also be co-branded with a local brand that is recognized and accepted within its country/region of origin (see card.localBrand).
You may use this information to support surcharging decisions. This information is gathered from 3rd party sources and may not be accurate in all circumstances.
Existence
Always Provided
Fixed value
Validation Rules
XSD type
string
Value must be a member of the following list. The values are case sensitive.
AMEX
American Express
CHINA_UNIONPAY
China UnionPay
DINERS_CLUB
Diners Club
DISCOVER
Discover
JCB
JCB (Japan Credit Bureau)
LOCAL_BRAND_ONLY
The card does not have a global brand.
MAESTRO
Maestro
MASTERCARD
MasterCard
RUPAY
RuPay
UATP
UATP (Universal Air Travel Plan)
UNKNOWN
The brand of the card used in the transaction could not be identified
VISA
Visa

sourceOfFunds.provided.card.devicePayment   = CONDITIONAL

Use this parameter group if the payer used a device payment technology (eg ApplePay).
You can either just present the device's payment token in the paymentToken subfield, or decrypt the payment token yourself and pass the components in the 3dSecure subfields.
Fixed value

sourceOfFunds.provided.card.devicePayment.cryptogramFormat  Enumeration = CONDITIONAL

The format of the cryptogram provided for the device payment.
You must provide the cryptogram format when you decrypt the payment token and provide the payment details (including the online payment cryptogram) in the transaction request.

You do not need to provide the cryptogram format if you provide the payment token in sourceOfFunds.provided.card.devicePayment.paymentToken
Existence
CONDITIONAL
Fixed value
Validation Rules
XSD type
string
Value must be a member of the following list. The values are case sensitive.
3DSECURE
The payment data keys for the online payment cryptogram are provided using the 3-D Secure format.
EMV
The payment data keys for the online payment cryptogram are provided using the EMV format.

sourceOfFunds.provided.card.deviceSpecificExpiry   = CONDITIONAL

The expiry date of the account number associated with a digital payment method.
The associated account number is returned in sourceOfFunds.provided.card.deviceSpecificNumber. This field is returned for:
  • • Device payments: the expiry date for the Device Primary Account Number (DPAN).
  • • Digital wallets: the expiry date for the Token PAN.
  • • Card scheme tokens: the expiry date for the Token PAN.
Fixed value

sourceOfFunds.provided.card.deviceSpecificExpiry.month  Digits = Always Provided

Month from the expiry date of the device specific account number.
Months are numbered January=1, through to December=12.
Existence
Always Provided
Fixed value
Validation Rules
Data is a number between 1 and 12 represented as a string.
XSD type
string

sourceOfFunds.provided.card.deviceSpecificExpiry.year  Digits = Always Provided

Year from the expiry date of the device specific account number.
The Common Era year is 2000 plus this value.
Existence
Always Provided
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9.
XSD type
string
minimum length
2
maximum length
2

sourceOfFunds.provided.card.deviceSpecificNumber  Masked digits = Always Provided

The payer's account number associated with a digital payment method.
Use this field for:
  • • Device payments: the payers's account number associated with the mobile device used for the payment. This is also known as the Device Primary Account Number (DPAN).
  • • Digital wallets: the Token PAN returned by a digital wallet. The gateway only returns this value for Amex Express Checkout.
  • • Card scheme tokens: the token generated by a card scheme tokenization service such as Mastercard Digital Enablement Service (MDES). The token is used as an identifier of the payer's Primary Account Number (PAN) securely stored by the service. For MDES, this token is referred to as the Token PAN. For VTS, this is the Token
Existence
Always Provided
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9, plus 'x' for masking
XSD type
string
minimum length
9
maximum length
19

sourceOfFunds.provided.card.emvRequest  String = CONDITIONAL

This field only applies to transactions that originate from an EMV capable terminal.
It contains selected EMV fields as provided by the terminal.

For the list of field tags to include (if provided by the terminal), see Card Present Payments. Requests with any other tags are rejected by the gateway.

Some of the tags represent data that can occur on explicit fields in this API. You can submit the value either in this field, or in both places. For example, the PAN can be presented as EMV tag 5A in this field, or included both the sourceOfFunds.provided.card.number API field and in EMV tag 5A in this field.

If you specify the EMV tag only, we can populate the explicit field in the API. Fields where this is supported have the text "This field corresponds to EMV tag <tag name>" in their field descriptions.

If you specify both places, there will be no population of the explicit field or validation that the data matches.

The API response will not contain PCI sensitive fields.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
250

sourceOfFunds.provided.card.emvResponse  String = CONDITIONAL

This field only applies to transactions that originate from an EMV capable terminal.
It contains the EMV fields returned from the issuer in response to an authorization request for the chip transaction when the transaction was sent online.

The card/terminal uses data returned from the issuer to make the final decision to accept or decline the transaction.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
250

sourceOfFunds.provided.card.encryption  Enumeration = CONDITIONAL

The encryption framework used for the payment details received by the gateway.
Existence
CONDITIONAL
Fixed value
Validation Rules
XSD type
string
Value must be a member of the following list. The values are case sensitive.
DEVICE
Encrypted by a payer's device (such as a mobile phone).
DIGITAL_WALLET
Encrypted by a payer's digital wallet.
DUKPT
Encrypted by a payment terminal using Derived Unique Key Per Transaction (DUKPT).

sourceOfFunds.provided.card.expiry   = CONDITIONAL

Expiry date, as shown on the card.
This field corresponds to EMV tag 5F24
Fixed value

sourceOfFunds.provided.card.expiry.month  Digits = Always Provided

Month, as shown on the card.
Months are numbered January=1, through to December=12.
Existence
Always Provided
Fixed value
Validation Rules
Data is a number between 1 and 12 represented as a string.
XSD type
string

sourceOfFunds.provided.card.expiry.year  Digits = Always Provided

Year, as shown on the card.
The Common Era year is 2000 plus this value.
Existence
Always Provided
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9.
XSD type
string
minimum length
2
maximum length
2

sourceOfFunds.provided.card.fundingMethod  Enumeration = Always Provided

The method used by the payer to provide the funds for the payment.
You may use this information to support surcharging decisions. This information is gathered from 3rd party sources and may not be accurate in all circumstances.
Existence
Always Provided
Fixed value
Validation Rules
XSD type
string
Value must be a member of the following list. The values are case sensitive.
CHARGE
The payer has a line of credit with the issuer which must be paid off monthly.
CREDIT
The payer has a revolving line of credit with the issuer.
DEBIT
Funds are immediately debited from the payer's account with the issuer.
UNKNOWN
The account funding method could not be determined.

sourceOfFunds.provided.card.issuer  String = CONDITIONAL

The issuer of the card, if known.
WARNING: This information may be incorrect or incomplete – use at your own risk.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
0
maximum length
255

sourceOfFunds.provided.card.localBrand  String = CONDITIONAL

The brand name used to describe a card that is recognized and accepted within its country/region of origin.
The card may also be co-branded with a brand name that is recognized and accepted globally (see card.brand).
You may use this information to support surcharging decisions. This information is gathered from 3rd party sources and may not be accurate in all circumstances.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
3
maximum length
50

sourceOfFunds.provided.card.nameOnCard  String = CONDITIONAL

The cardholder's name as printed on the card.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
256

sourceOfFunds.provided.card.number  Masked digits = Always Provided

The account number of the payer's account used for this authentication.
On requests, provide the number in the form that you receive it (as explained below). On responses, the gateway populates it with a form that the payer would recognize (also explained in more detail below).

  • Request

    On request, populate this field based on the payment method you are using for the payment:
    • • Card: the account number embossed onto the card.
    • • Scheme tokens such as MDES (Mastercard Digital Enablement Service) - supply the value called the "Token PAN" or VTS (Visa Token Service) - supply the value called "token".
  • Response

    On return, the card number will be populated in 6.4 masking format, for example, 000000xxxxxx0000.
Existence
Always Provided
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9, plus 'x' for masking
XSD type
string
minimum length
9
maximum length
19

sourceOfFunds.provided.card.pin   = CONDITIONAL

The PIN (Personal Identification Number) entered by a payer at the point of sale that is used to authenticate their identity as the cardholder with the issuer.
Provide this data in the case where you want the PIN verified online by the issuer. The gateway can support PINs encoded in ISO 9564-1 formats 0, 1, 3 and 4, but the supported format will depend on integration.
Fixed value

sourceOfFunds.provided.card.pin.encryptionState  Enumeration = CONDITIONAL

The PIN encryption state as determined by the terminal.
INVALID means the terminal detected some form of error in the encryption process. The gateway will decline transactions with INVALID encryption state. This field may be omitted when the value is VALID.
Existence
CONDITIONAL
Fixed value
Validation Rules
XSD type
string
Value must be a member of the following list. The values are case sensitive.
INVALID
The encryption state is invalid.
VALID
The encryption state is valid.

sourceOfFunds.provided.card.pin.keySerialNumber  Hex = Always Provided

The DUKPT key serial number supplied by the terminal.
Existence
Always Provided
Fixed value
Validation Rules
Data is hexadecimal encoded
XSD type
string
minimum length
20
maximum length
20

sourceOfFunds.provided.card.scheme  Enumeration = Always Provided

The organization that owns a card brand and defines operating regulations for its use.
The card scheme also controls authorization and settlement of card transactions among issuers and acquirers.
Existence
Always Provided
Fixed value
Validation Rules
XSD type
string
Value must be a member of the following list. The values are case sensitive.
AMEX
American Express
CHINA_UNIONPAY
China UnionPay
DINERS_CLUB
Diners Club
DISCOVER
Discover
JCB
JCB (Japan Credit Bureau)
MASTERCARD
MasterCard
OTHER
The scheme of the card used in the transaction could not be identified.
RUPAY
RuPay
UATP
UATP (Universal Air Travel Plan)
VISA
Visa

sourceOfFunds.provided.card.sequenceNumber  Digits = CONDITIONAL

A number used to differentiate between cards with the same Primary Account Number (PAN).
This field corresponds to EMV tag 5F34
Existence
CONDITIONAL
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9.
XSD type
string
minimum length
3
maximum length
3

sourceOfFunds.provided.card.storedOnFile  Enumeration = CONDITIONAL

This field only applies if you collect cards from your payers, store them, and either you or your payers use the stored value for subsequent payments.
If you store using gateway tokenization then you can ignore this field, unless you do payments with both stored and non-stored cards. If you do both, then you must supply the NOT_STORED value for the non-stored case.

If you use Scheme Tokenization services like MDES and store the tokens provided, you have to provide the value STORED and if you pass the token value with out storing them, provide the value NOT_STORED.

If you store yourself, you have to provide the TO_BE_STORED or STORED values for all payments.
Existence
CONDITIONAL
Fixed value
Validation Rules
XSD type
string
Value must be a member of the following list. The values are case sensitive.
NOT_STORED
Set this value if the card or token details provided will not be stored. This is the default value for merchants without tokenization.
STORED
Set this value if the card or token details provided have been stored previously. This is the default value when paying with a gateway token.
TO_BE_STORED
Set this value if this is the first transaction using the card and you intend to store the card or token details on success. This is the default value for tokenization merchants who present a payment with a PAN.

sourceOfFunds.provided.card.tags  String = CONDITIONAL

Tags provide you with additional information about the card.
For example, identifying if it is an EBT (Electronic Benefits Transfer) or Health Benefit Card. You can use this information to support your decisions about accepting payments with this card. The data is encoded in JSON as an object map indexed on the tag name. Some standard tag names are EBT and HEALTH_BENEFIT_CARD_IIAS. If these tags apply to the card, the tag will have value true, otherwise it will be absent. Other tag names with other values might also exist, depending on which acquirer processed the transaction. For example, an EBT card might return value: {"ACME_CARD_IDENTIFIER":"23", "EBT":true} Contact your payment provider if you wish to understand all tags available for your acquirers.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
2048

sourceOfFunds.provided.card.trackDataProvided  Boolean = CONDITIONAL

Indicates whether card track data is provided.
Existence
CONDITIONAL
Fixed value
Validation Rules
The values 'true' or 'false'. (For a complete description, see http://www.w3.org/TR/xmlschema-2/#boolean.)
XSD type
boolean

sourceOfFunds.provided.ebt   = CONDITIONAL

If the payer chose to pay using a Electronic Benefits Transfer card, you must submit sourceOfFunds.type=EBT_CARD and provide the payer's card details in this parameter group.
Fixed value

sourceOfFunds.provided.ebt.accountType  Enumeration = CONDITIONAL

Indicates the type of benefits account used for the payment.
Existence
CONDITIONAL
Fixed value
Validation Rules
XSD type
string
Value must be a member of the following list. The values are case sensitive.
CASH_BENEFITS
Benefits provided as cash.
EWIC_BENEFITS
Benefits provided under the Special Supplemental Nutrition Program for Women, Infants, and Children.
SNAP_BENEFITS
Benefits provided under the Supplemental Nutrition Assistance Program.

sourceOfFunds.provided.ebt.manualAuthorizationCode  Digits = CONDITIONAL

Value provided to you by the EBT merchant helpline when you requested manual authorization of the payment because you were unable to authorize the payment online.
For example, your point of sale (POS) machine is not working. When you manually authorize a payment you also need to provided the voucher number used to record the payment in sourceOfFunds.provided.EBT.voucherNumber.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9.
XSD type
string
minimum length
1
maximum length
6

sourceOfFunds.provided.ebt.merchantFns  Digits = CONDITIONAL

The identifier assigned to you by the USDA Food and Nutrition Service (FNS) when they authorized you to accept EBT payments at your store.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9.
XSD type
string
minimum length
1
maximum length
7

sourceOfFunds.provided.ebt.voucherNumber  Digits = CONDITIONAL

The number of the paper form (voucher) that you used to record details of an EBT payment when you were unable to authorize the payment online.
For example, your point of sale (POS) machine is not working. When you use a voucher you also need to provide an authorization code in sourceOfFunds.provided.benefits.ebt.manualAuthorizationCode.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9.
XSD type
string
minimum length
1
maximum length
15

sourceOfFunds.provided.enets   = CONDITIONAL

Additional details related to an eNETS browser payment.
Note: if you provide data for an eNETS payment, then you must also provide an email address for the customer in customer.email and a phone number for the customer in either customer.phone or customer.mobilePhone
Fixed value

sourceOfFunds.provided.enets.bankAccountHolder  String = Always Provided

The name of the bank account holder for the payer's bank account.
Existence
Always Provided
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
255

sourceOfFunds.provided.epsUeberweisung   = CONDITIONAL

Additional details related to a eps-Überweisung browser payment.
Fixed value

sourceOfFunds.provided.epsUeberweisung.bankAccountCountryCode  Alpha = Always Provided

The country where the payer has their bank account.
Provide the ISO 3166 alpha-3 country code for this country.
Existence
Always Provided
Fixed value
Validation Rules
Data may consist of the characters a-z, A-Z
XSD type
string
minimum length
3
maximum length
3

sourceOfFunds.provided.epsUeberweisung.bankAccountHolder  String = CONDITIONAL

The name of the bank account holder for the payer's bank account.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
0
maximum length
255

sourceOfFunds.provided.giftCard   = CONDITIONAL

A gift card was used.
The payer's gift card details are provided in this parameter group.
Fixed value

sourceOfFunds.provided.giftCard.brand  Enumeration = Always Provided

The brand name used to describe the card that is recognized and accepted globally.
For many major card types this will match the scheme name.
Existence
Always Provided
Fixed value
Validation Rules
XSD type
string
Value must be a member of the following list. The values are case sensitive.
LOCAL_BRAND_ONLY
The card does not have a global brand.

sourceOfFunds.provided.giftCard.localBrand  String = Always Provided

The brand name used to describe a card as determined by the gateway, based on the BIN range of the card.
Existence
Always Provided
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
50

sourceOfFunds.provided.giftCard.number  Masked digits = Always Provided

Card number as printed or embossed on the gift card.
Existence
Always Provided
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9, plus 'x' for masking
XSD type
string
minimum length
9
maximum length
19

sourceOfFunds.provided.giftCard.pin  Masked digits = CONDITIONAL

PIN number for the gift card.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9, plus 'x' for masking
XSD type
string
minimum length
4
maximum length
8

sourceOfFunds.provided.giftCard.scheme  Enumeration = Always Provided

The organization that owns a card brand and defines operating regulations for its use.
Existence
Always Provided
Fixed value
Validation Rules
XSD type
string
Value must be a member of the following list. The values are case sensitive.
OTHER
The scheme of the card used in the transaction could not be identified.

sourceOfFunds.provided.giropay   = CONDITIONAL

The additional details required to initiate a giropay browser payment.
Fixed value

sourceOfFunds.provided.giropay.bankIdentifier  Digits = CONDITIONAL

German bank identifier (Bankleitzahl) for the payer's bank account.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9.
XSD type
string
minimum length
8
maximum length
8

sourceOfFunds.provided.giropay.bic  Alphanumeric = CONDITIONAL

The international Business Identifier Code (BIC) for the payer's bank account.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data may consist of the characters 0-9, a-z, A-Z
XSD type
string
minimum length
8
maximum length
11

sourceOfFunds.provided.giropay.iban  String = CONDITIONAL

The International Bank Account Number (IBAN) for the payer's bank account.
By default, the bank account number will be returned in a masked format, for example, xxxxxx0000. If you wish to return unmasked bank account numbers, you must have the requisite permission, set responseControls.sensitiveData, and authenticate your call to the API using certificate authentication. Contact your payment service provider for further information.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
50

sourceOfFunds.provided.grabPay   = CONDITIONAL

Additional details related to GrabPay browser payment.
Fixed value

sourceOfFunds.provided.grabPay.accountHolder  String = Always Provided

The name of the account holder for the payer’s GrabPay account.
Existence
Always Provided
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
3
maximum length
100

sourceOfFunds.provided.ideal   = CONDITIONAL

Information about the payer's iDEAL account provided to you when the payer successfully makes a payment.
Fixed value

sourceOfFunds.provided.ideal.bankAccountHolder  String = CONDITIONAL

The name of the bank account holder for the payer's bank account.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
255

sourceOfFunds.provided.ideal.bic  Alphanumeric = CONDITIONAL

The international Business Identifier Code (BIC) for the payer's bank account.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data may consist of the characters 0-9, a-z, A-Z
XSD type
string
minimum length
8
maximum length
11

sourceOfFunds.provided.ideal.iban  String = CONDITIONAL

The International Bank Account Number (IBAN) for the payer's bank account.
By default, the bank account number will be returned in a masked format, for example, xxxxxx0000. If you wish to return unmasked bank account numbers, you must have the requisite permission, set responseControls.sensitiveData, and authenticate your call to the API using certificate authentication. Contact your payment service provider for further information.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
50

sourceOfFunds.provided.klarnaPayLater   = CONDITIONAL

Additional details related to a Klarna Pay Later payment.
Fixed value

sourceOfFunds.provided.klarnaPayLater.bankAccountCountryCode  Upper case alphabetic text = Always Provided

The country where the payer has their bank account.
Provide the ISO 3166 alpha-3 country code for this country.
Existence
Always Provided
Fixed value
Validation Rules
Data must consist of the characters A-Z
XSD type
string
minimum length
3
maximum length
3

sourceOfFunds.provided.klarnaPayNow   = CONDITIONAL

Additional details related to a Klarna Pay Now payment.
Fixed value

sourceOfFunds.provided.klarnaPayNow.bankAccountCountryCode  Alpha = Always Provided

The country where the payer has their bank account.
Provide the ISO 3166 alpha-3 country code for this country.
Existence
Always Provided
Fixed value
Validation Rules
Data may consist of the characters a-z, A-Z
XSD type
string
minimum length
3
maximum length
3

sourceOfFunds.provided.openBankingBankTransfer   = CONDITIONAL

Additional details related to Open Banking Bank Transfer.
Fixed value

sourceOfFunds.provided.openBankingBankTransfer.aspspId  String = Always Provided

Identifier of the payer's bank, also known as ASPSP (Account Servicing Payment Services Provider)
Existence
Always Provided
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
256

sourceOfFunds.provided.oxxo   = CONDITIONAL

Additional details related to an OXXO browser payment.
When processing an OXXO payment you must also provide the payer's national identifier (customer.nationalId), your reference to the payer (customer.id) and the payer's date of birth (customer.dateOfBirth).
Fixed value

sourceOfFunds.provided.oxxo.bankAccountHolder  String = Always Provided

The name of the bank account holder for the payer's bank account.
Existence
Always Provided
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
255

sourceOfFunds.provided.oxxo.dueDate  Date = CONDITIONAL

The date by which your payer has to make the payment.
Do not provide a due date for USD currency transactions.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data must comply with ISO 8601 extended date format, yyyy-mm-dd
XSD type
string

sourceOfFunds.provided.payU   = CONDITIONAL

Additional details related to a PayU browser payment.
Fixed value

sourceOfFunds.provided.payU.bankAccountCountryCode  Alpha = Always Provided

The country where the payer has their bank account.
Provide the ISO 3166 alpha-3 country code for this country.
Existence
Always Provided
Fixed value
Validation Rules
Data may consist of the characters a-z, A-Z
XSD type
string
minimum length
3
maximum length
3

sourceOfFunds.provided.payU.bankAccountHolder  String = CONDITIONAL

The name of the bank account holder for the payer's bank account.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
0
maximum length
255

sourceOfFunds.provided.paypal   = CONDITIONAL

Information about the payer's PayPal account.
It is provided to you when the payer successfully makes a payment using PayPal or when you have established a billing agreement with the payer.
Fixed value

sourceOfFunds.provided.paypal.accountEmail  Email = CONDITIONAL

The email address of the payer's PayPal account.
Existence
CONDITIONAL
Fixed value
Validation Rules
Ensures that the email address is longer than 3 characters and adheres to a generous subset of valid RFC 2822 email addresses
XSD type
string

sourceOfFunds.provided.paypal.accountHolder  String = CONDITIONAL

The name of the account holder of the payer's PayPal account.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
255

sourceOfFunds.provided.paypal.billingAgreement   = CONDITIONAL

Details about the agreement you have established with the payer that allows you to bill the payer's PayPal account for goods or services.
Fixed value

sourceOfFunds.provided.paypal.billingAgreement.cardinality  Enumeration = CONDITIONAL

Indicates the number of billing agreements between you and this payer.
Existence
CONDITIONAL
Fixed value
Validation Rules
XSD type
string
Value must be a member of the following list. The values are case sensitive.
MULTIPLE
Indicates that you have multiple billing agreements with this payer. This means that a new agreement ID will be returned in response to each request.
SINGLE
Indicates that you have a single billing agreement with this payer. This means that the same agreement ID will be returned in response to each request.

sourceOfFunds.provided.paypal.billingAgreement.description  String = CONDITIONAL

Your description for the PayPal billing agreement.
This description is displayed to the payer when they are asked to approve the billing agreement.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
255

sourceOfFunds.provided.paypal.billingAgreement.id  String = CONDITIONAL

An identifier provided by PayPal for the billing agreement.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
100

sourceOfFunds.provided.paypal.billingAgreement.name  String = CONDITIONAL

Your name for the PayPal billing agreement.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
255

sourceOfFunds.provided.paypal.payerId  String = CONDITIONAL

The unique identifier for the payer assigned by PayPal.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
13

sourceOfFunds.provided.paysafecard   = CONDITIONAL

Additional details related to a paysafecard browser payment.
Fixed value

sourceOfFunds.provided.paysafecard.accountEmail  Email = Always Provided

The mypaysafecard account email identifying the mypaysafecard account that will be refunded.
Existence
Always Provided
Fixed value
Validation Rules
Ensures that the email address is longer than 3 characters and adheres to a generous subset of valid RFC 2822 email addresses
XSD type
string

sourceOfFunds.provided.paysafecard.countryCode  Alpha = Always Provided

The country where the payer has their bank account.
Provide the ISO 3166 alpha-3 country code for this country.
Existence
Always Provided
Fixed value
Validation Rules
Data may consist of the characters a-z, A-Z
XSD type
string
minimum length
3
maximum length
3

sourceOfFunds.provided.pbba   = CONDITIONAL

Additional details related to Pay by Bank app payment.
Fixed value

sourceOfFunds.provided.pbba.paymentRequestId  Digits = CONDITIONAL

A unique reference to the payment request, also known as the Pay by Bank app secure token.
This identifier should be used when invoking the banking app within the payer’s mobile.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9.
XSD type
string
minimum length
18
maximum length
18

sourceOfFunds.provided.pbba.paymentRequestInputCode  Upper case alphabetic text = CONDITIONAL

The one-time six character code identifying the payment request, also known as the Pay by Bank app Basket Reference Number.
This code may be used by the payer to confirm the payment within their mobile banking app.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data must consist of the characters A-Z
XSD type
string
minimum length
6
maximum length
6

sourceOfFunds.provided.poli   = CONDITIONAL

Additional details related to a POLi browser payment.
Fixed value

sourceOfFunds.provided.poli.bankAccountHolder  String = Always Provided

The name of the bank account holder for the payer's bank account.
Existence
Always Provided
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
255

sourceOfFunds.provided.przelewy24   = CONDITIONAL

Additional details related to a Przelewy24 browser payment.
Fixed value

sourceOfFunds.provided.przelewy24.bankAccountHolder  String = Always Provided

The name of the bank account holder for the payer's bank account.
Existence
Always Provided
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
255

sourceOfFunds.provided.sepa   = CONDITIONAL

Details about the payer's bank account used for a payment made using SEPA
Fixed value

sourceOfFunds.provided.sepa.bankAccountHolder  String = Always Provided

The name of the bank account holder for the payer's bank account.
Existence
Always Provided
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
3
maximum length
100

sourceOfFunds.provided.sepa.bic  Alphanumeric = CONDITIONAL

The international Business Identifier Code (BIC) for the payer's bank account.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data may consist of the characters 0-9, a-z, A-Z
XSD type
string
minimum length
8
maximum length
11

sourceOfFunds.provided.sepa.iban  String = Always Provided

The International Bank Account Number (IBAN) for the payer's bank account.
By default, the bank account number will be returned in a masked format, for example, xxxxxx0000. If you wish to return unmasked bank account numbers, you must have the requisite permission, set responseControls.sensitiveData, and authenticate your call to the API using certificate authentication. Contact your payment service provider for further information.
Existence
Always Provided
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
50

sourceOfFunds.provided.sofort   = CONDITIONAL

Additional details related to a Sofort (Klarna) payment.
Fixed value

sourceOfFunds.provided.sofort.bankAccountCountryCode  Upper case alphabetic text = CONDITIONAL

The country where the payer has their bank account.
Provide the ISO 3166 alpha-3 country code for this country.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data must consist of the characters A-Z
XSD type
string
minimum length
3
maximum length
3

sourceOfFunds.provided.sofort.bankAccountHolder  String = CONDITIONAL

The name of the bank account holder for the payer's bank account.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
255

sourceOfFunds.provided.sofort.bankAccountNumber  String = CONDITIONAL

The country-specific bank account number for the payer's bank account.
By default, the bank account number will be returned in a masked format, for example, xxxxxx0000. If you wish to return unmasked bank account numbers, you must have the requisite permission, set responseControls.sensitiveData, and authenticate your call to the API using certificate authentication. Contact your payment service provider for further information.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
30

sourceOfFunds.provided.sofort.bankIdentifier  String = CONDITIONAL

The country-specific bank identifier for the payer's bank account.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
30

sourceOfFunds.provided.sofort.bic  String = CONDITIONAL

The international Business Identifier Code (BIC) for the payer's bank account.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
50

sourceOfFunds.provided.sofort.iban  String = CONDITIONAL

The International Bank Account Number (IBAN) for the payer's bank account.
By default, the bank account number will be returned in a masked format, for example, xxxxxx0000. If you wish to return unmasked bank account numbers, you must have the requisite permission, set responseControls.sensitiveData, and authenticate your call to the API using certificate authentication. Contact your payment service provider for further information.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
50

sourceOfFunds.provided.trustly   = CONDITIONAL

Additional details related to a Trustly.
Fixed value

sourceOfFunds.provided.trustly.bankAccountCountryCode  Alpha = Always Provided

The country where the payer has their bank account.
Provide the ISO 3166 alpha-3 country code for this country.
Existence
Always Provided
Fixed value
Validation Rules
Data may consist of the characters a-z, A-Z
XSD type
string
minimum length
3
maximum length
3

sourceOfFunds.provided.trustly.bankAccountHolder  String = Always Provided

The name of the bank account holder for the payer's bank account.
Existence
Always Provided
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
255

sourceOfFunds.provided.weChatPay   = CONDITIONAL

Additional details related to a WeChat Pay browser payment.
Fixed value

sourceOfFunds.provided.weChatPay.accountHolder  String = Always Provided

The name of the account holder for the payer's WeChat Pay account.
Existence
Always Provided
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
255

sourceOfFunds.token  Alphanumeric = CONDITIONAL

Gateway token that uniquely identifies a card and associated details.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data may consist of the characters 0-9, a-z, A-Z
XSD type
string
minimum length
1
maximum length
40

sourceOfFunds.tokenRequestorID  Alphanumeric = CONDITIONAL

The unique identifier assigned to you by the Token Service Provider that you requested a token from for this payment.
This field is mandatory for payments where the Chase Pay wallet was used.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data may consist of the characters 0-9, a-z, A-Z
XSD type
string
minimum length
11
maximum length
11

sourceOfFunds.type  Enumeration = CONDITIONAL

The payment method used for this authentication.
If you are passing card or scheme token data on the API, then you need to set this value, and also provide the card or token details in the sourceOfFunds.provided.card group.

If you are making a payment with a gateway token, then you can leave this field unset, and only populate the sourceOfFund.token field.
Existence
CONDITIONAL
Fixed value
Validation Rules
XSD type
string
Value must be a member of the following list. The values are case sensitive.
ACH
The payer chose to pay using an electronic fund transfer, to be processed via the Automated Clearing House (ACH) Network. You must provide the payer's bank account details and information about the type of ACH payment under the sourceOfFunds.provided.ach parameter group.
ALIPAY
The payer selected the payment method Alipay.
BOLETO_BANCARIO
The payer selected the payment method Boleto Bancario.
CARD
Use this value for authentications using the card number.
EBT_CARD
Use this value for Electronic Benefits Transfer (EBT) card payments. The additional EBT data must also be provided in the sourceOfFunds.provided.ebt parameter group.
ENETS
The payer selected the payment method eNETS.
GIFT_CARD
Use this value for gift cards.
GIROPAY
The payer selected the payment method giropay.
IDEAL
The payer selected the payment method iDEAL.
KLARNA
The payer selected the payment method Klarna.
MULTIBANCO
The payer selected the payment method Multibanco.
NONE
The transaction transfers money to or from the merchant, without the involvement of a payer. For example, recording monthly merchant service fees from your payment service provider.
OXXO
The payer selected the payment method OXXO.
PAYPAL
The payer selected the payment method PayPal.
POLI
The payer selected the payment method POLi.
SCHEME_TOKEN
Use this value for authentications using scheme tokens.
SEPA
The payer selected the payment method SEPA.
SOFORT
The payer selected the payment method Sofortbanking.
UNION_PAY
The payer selected the payment method UnionPay.
WECHAT_PAY
The payer selected the payment method WeChatPay.

subgatewayMerchant   = CONDITIONAL

Information about your merchant.
This group only applies if you:

  • operate a gateway, and
  • you are not boarding your merchants onto the gateway, and
  • you are enabled for this capability on the gateway.

If you are such a gateway, use these fields to provide information about your merchant, so that our gateway can process their transaction on your behalf.

Note: In these cases, you must also provide a value for field order.merchantCategoryCode

Fixed value

subgatewayMerchant.acquirer[n]   = Always Provided

Details about this merchant's account with the acquirers they use for payment processing.
A merchant might have one or more acquirers.

Each record in this group applies to one acquirer. If your gateway knows exactly which acquirer will use for this transaction, then you can provide just that acquirer's data. Alternatively, you can specify a set of acquirers, in which case the gateway will select between them based on the routing rules that configured in our gateway.

In this group, the term 'acquirer' includes banks acquiring scheme cards (such as MasterCard,or Visa), and alternative providers (such as UnionPay, or SEPA)
Fixed value

subgatewayMerchant.acquirer[n].3DS1   = CONDITIONAL

Information about the merchant's registration to use 3-D Secure authentication version 1 for this acquirer.
Fixed value

subgatewayMerchant.acquirer[n].3DS1.mastercardSecureCode   = CONDITIONAL

Information about the merchant's registration to use Mastercard SecureCode 3-D Secure authentication version 1 for this acquirer.
Fixed value

subgatewayMerchant.acquirer[n].3DS1.mastercardSecureCode.merchantId  String = CONDITIONAL

The unique identifier assigned to the merchant by their acquirer when they registered to use Mastercard SecureCode 3-D Secure authentication version 1.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
24

subgatewayMerchant.acquirer[n].3DS1.verifiedByVisa   = CONDITIONAL

Information about the merchant's registration to use Verified by Visa 3-D Secure authentication version 1 for this acquirer.
Fixed value

subgatewayMerchant.acquirer[n].3DS1.verifiedByVisa.cardAcceptorId  String = CONDITIONAL

The unique identifier assigned to the merchant by their acquirer when they registered to use Verified by Visa 3-D Secure authentication version 1.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
15

subgatewayMerchant.acquirer[n].3DS1.verifiedByVisa.cardAcceptorTerminalId  String = CONDITIONAL

The unique identifier of a terminal provided to the merchant by their acquirer when they registered to use Verified by Visa 3-D Secure authentication version 1.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
8

subgatewayMerchant.acquirer[n].acquirerMerchantId  String = Always Provided

The identifier (ID/SE Number/account name or such ) allocated to your merchant by their acquiring institution.
Existence
Always Provided
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
0
maximum length
40

subgatewayMerchant.acquirer[n].amexSafeKey   = CONDITIONAL

Information about the merchant's registration to use American Express SafeKey 3-D Secure authentication for this acquirer.
Fixed value

subgatewayMerchant.acquirer[n].amexSafeKey.merchantId  Regex = CONDITIONAL

The unique identifier assigned to the merchant by their acquirer when they registered to use American Express SafeKey 3-D Secure authentication.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data must match regex
XSD type
string
regex
\d{10}|\d{10};\w{10,20}
message
First 10 characters must be all numeric. If length is longer than 10, then 11th character must be a semi colon (;). There must be at least 10 characters following the semi colon. Minimum length 10 Maximum length 31

subgatewayMerchant.acquirer[n].countryCode  Upper case alphabetic text = CONDITIONAL

The ISO 3166 three-letter country code of the acquirer.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data must consist of the characters A-Z
XSD type
string
minimum length
3
maximum length
3

subgatewayMerchant.acquirer[n].fraudRate  Integer = CONDITIONAL

The merchant's fraud rate, as determined by the acquirer, expressed in basis points (bps).
Existence
CONDITIONAL
Fixed value
Validation Rules
A number comprising the digits 0-9, having at least one digit. (For a complete description, see http://www.w3.org/TR/xmlschema-2/#nonNegativeInteger.)
XSD type
nonNegativeInteger
minimum value
0
maximum value
99999

subgatewayMerchant.acquirer[n].id  String = Always Provided

The name of the acquirer on which your merchant has an account.This is the value as returned in transaction.acquirer.id, for example ACME_BANK.
Your payment service provider will supply the acquirer names that apply to you.
Existence
Always Provided
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
0
maximum length
40

subgatewayMerchant.acquirer[n].merchantCategoryCode  Digits = CONDITIONAL

A 4-digit code used to classify the merchant’s business by the type of goods or services it offers.
This is also known as the Merchant Category Code (MCC).
You only need to provide this value if you are specifying more than one acquirer link, and some acquirers need different MCC values. If the same MCC applies to all acquirers, just specify it as order.merchantCategoryCode.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9.
XSD type
string
minimum length
4
maximum length
4

subgatewayMerchant.address   = CONDITIONAL

The address of this merchant.
Fixed value

subgatewayMerchant.address.city  String = Always Provided

The city or town of this merchant's billing address.
Existence
Always Provided
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
30

subgatewayMerchant.address.countryCode  Upper case alphabetic text = Always Provided

The country of this merchant's billing address.
The value must be a three-letter country code according to ISO 3166-1 alpha-3.
Existence
Always Provided
Fixed value
Validation Rules
Data must consist of the characters A-Z
XSD type
string
minimum length
3
maximum length
3

subgatewayMerchant.address.postcodeZip  String = Always Provided

The zip or postal code of this merchant's billing address.
Existence
Always Provided
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
16

subgatewayMerchant.address.stateProvince  String = Always Provided

The state or province code of the merchant's billing address.
For merchants in the United States provide the 2-letter ISO 3166-2 state code. For US military bases provide one of AE, AA, AP.

For Canadian merchants provide the 2-letter ISO 3166-2 province code.
Existence
Always Provided
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
30

subgatewayMerchant.address.street1  String = Always Provided

The first line of the street address of this merchant's billing address.
Existence
Always Provided
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
40

subgatewayMerchant.address.street2  String = CONDITIONAL

The second line of the street address of this merchant's billing address.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
40

subgatewayMerchant.authentication[n]   = CONDITIONAL

Information about the merchant's registration to use a payer authentication protocol.
For example, using 3-D Secure authentication.
Fixed value

subgatewayMerchant.authentication[n].3DS2   = CONDITIONAL

Information about the merchant's registration to use 3-D Secure authentication version 2.
These details are used to identify the merchant to the card schemes directory server.

This API assumes that a merchant has only one registration for a each 3DS2 scheme across all the acquirers. If your merchant has more than one 3DS2 registration that could apply to this transaction, then you need to provide a lineOfBusiness field to narrow to one registration.

Fixed value

subgatewayMerchant.authentication[n].3DS2.requestorId  String = CONDITIONAL

The unique identifier assigned to the merchant by the card scheme directory server when the merchant registered to use 3-D Secure authentication version 2 with their acquirer.
Do not provide this value for Mastercard SecureCode, JCB JSecure, Discover ProtectBuy or Verified by Visa, For these authentication schemes, it will be generated by the gateway. For American Express if it is provided it will be used otherwise it will be generated by the gateway.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
35

subgatewayMerchant.authentication[n].3DS2.requestorName  String = CONDITIONAL

The unique name assigned to the merchant by the card scheme directory server when the merchant registered to use 3-D Secure authentication version 2 with their acquirer.
Do not provide this value for Mastercard SecureCode, JCB JSecure, Discover ProtectBuy or Verified by Visa, For these authentication schemes, it will be generated by the gateway. For American Express if it is provided it will be used otherwise it will be generated by the gateway.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
40

subgatewayMerchant.authentication[n].acquirerBIN  Digits = CONDITIONAL

The acquirer's Bank Identification Number (BIN).
This is used to identify the acquirer in messages to the scheme's Directory Server for 3-D Secure authentication version 2 transactions
Existence
CONDITIONAL
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9.
XSD type
string
minimum length
4
maximum length
11

subgatewayMerchant.authentication[n].protocol  Enumeration = Always Provided

The protocol used for payer authentication.
Existence
Always Provided
Fixed value
Validation Rules
XSD type
string
Value must be a member of the following list. The values are case sensitive.
AMEX_SAFEKEY
American Express SafeKey EMV 3DS authentication
DINERS_PROTECTBUY
Diners ProtectBuy EMV 3DS authentication
FASTR_BY_CB
Carte Bancaire FAST'R by CB using EMV 3DS authentication
JCB_JSECURE
JCB J/Secure using EMV 3DS authentication
MASTERCARD_SECURECODE
Mastercard SecureCode EMV 3DS authentication
RUPAY
VERIFIED_BY_VISA
Visa Verified by Visa EMV 3DS authentication

subgatewayMerchant.id  Alphanumeric + additional characters = Always Provided

The identifier you use to uniquely identify this merchant on your system.
Existence
Always Provided
Fixed value
Validation Rules
Data may consist of the characters 0-9, a-z, A-Z, '_', '-'
XSD type
string
minimum length
1
maximum length
36

subgatewayMerchant.name  String = Always Provided

This merchant's registered business, trading or organization name.
This must match the merchant name you provided during registration with scheme Directory Servers.
Existence
Always Provided
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
100

subgatewayMerchant.websiteUrl  Url = Always Provided

The URL of the merchant's website.
You must provide a value if you want the gateway to perform 3-D Secure authentication of the payer.
Existence
Always Provided
Fixed value
Validation Rules
Ensure that this is a valid URL according to RFC 1738.
XSD type
string

timeOfLastUpdate  DateTime = CONDITIONAL

Indicates the date and time the gateway considers the transaction to have last been updated.
Existence
CONDITIONAL
Fixed value
Validation Rules
An instant in time expressed in ISO8601 date + time format - "YYYY-MM-DDThh:mm:ss.SSSZ"
XSD type
string

timeOfRecord  DateTime = CONDITIONAL

Indicates the date and time the gateway considers the transaction to have been created.
The gateway uses timeOfRecord as a point-in-time value for operations such as sorting, billing, and reporting.
Existence
CONDITIONAL
Fixed value
Validation Rules
An instant in time expressed in ISO8601 date + time format - "YYYY-MM-DDThh:mm:ss.SSSZ"
XSD type
string

transaction   = Always Provided

Information about this transaction.
Fixed value

transaction.amount  Decimal = Always Provided

The total amount for the transaction.
Existence
Always Provided
Fixed value
Validation Rules
A sequence of digits 0-9 separated by a '.' as a decimal indicator. Leading and trailing zeroes are optional. If the fractional part is zero, the '.' and following zero(es) can be omitted. (For a complete description, see http://www.w3.org/TR/xmlschema-2/#decimal.)
XSD type
decimal
maximum value
1000000000000
minimum value
0
maximum post-decimal digits
3

transaction.authenticationStatus  Enumeration = CONDITIONAL

Indicates the result of payer authentication.
Existence
CONDITIONAL
Fixed value
Validation Rules
XSD type
string
Value must be a member of the following list. The values are case sensitive.
AUTHENTICATION_ATTEMPTED
Payer authentication was attempted and a proof of authentication attempt was obtained.
AUTHENTICATION_AVAILABLE
Payer authentication is available for the payment method provided.
AUTHENTICATION_EXEMPT
Exemption from the Regulatory Technical Standards (RTS) requirements for Strong Customer Authentication (SCA) under the Payment Services Directive 2 (PSD2) regulations in the European Economic Area has been claimed or granted.
AUTHENTICATION_FAILED
The payer was not authenticated. You should not proceed with this transaction.
AUTHENTICATION_NOT_IN_EFFECT
There is no authentication information associated with this transaction.
AUTHENTICATION_NOT_SUPPORTED
The requested authentication method is not supported for this payment method.
AUTHENTICATION_PENDING
Payer authentication is pending completion of a challenge process.
AUTHENTICATION_REJECTED
The issuer rejected the authentication request and requested that you do not attempt authorization of a payment.
AUTHENTICATION_REQUIRED
Payer authentication is required for this payment, but was not provided.
AUTHENTICATION_SUCCESSFUL
The payer was successfully authenticated.
AUTHENTICATION_UNAVAILABLE
The payer was not able to be authenticated due to a technical or other issue.

transaction.currency  Upper case alphabetic text = Always Provided

The currency of the transaction expressed as an ISO 4217 alpha code, e.g. USD.
Existence
Always Provided
Fixed value
Validation Rules
Data must consist of the characters A-Z
XSD type
string
minimum length
3
maximum length
3

transaction.id  String = Always Provided

Unique identifier for this transaction to distinguish it from any other transaction on the order.
An order can have transactions representing:
  • Movement of money. For example, payments and refunds.
  • Validations. For example, account verification or 3-D Secure authentication of the payer.
  • Undoing other transactions. For example, voiding a payment transaction.
  • Chargebacks.
  • Fees from your payment service provider.
Each transaction on the order must have a unique id that identifies that transaction. Some transactions also hold the transaction identifier of other transactions on the order. For example a void payment transaction references the original payment transaction that is being voided.

If you attempt an operation and it fails (eg you try to PAY on a card with no funds), then you need a new id for each retry.
Existence
Always Provided
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
40

transaction.reference  String = CONDITIONAL

An optional identifier for this transaction.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
40

transaction.type  Enumeration = Always Provided

Indicates the type of action performed on the order.
Existence
Always Provided
Fixed value
Validation Rules
XSD type
string
Value must be a member of the following list. The values are case sensitive.
AUTHENTICATION
Authentication
AUTHORIZATION
Authorization
AUTHORIZATION_UPDATE
Authorization Update
CAPTURE
Capture
CHARGEBACK
Chargeback
DISBURSEMENT
Disbursement
FUNDING
The transaction transfers money to or from the merchant, without the involvement of a payer. For example, recording monthly merchant service fees from your payment service provider.
PAYMENT
Payment (Purchase)
REFUND
Refund
REFUND_REQUEST
Refund Request
VERIFICATION
Verification
VOID_AUTHORIZATION
Void Authorization
VOID_CAPTURE
Void Capture
VOID_PAYMENT
Void Payment
VOID_REFUND
Void Refund

version  String = CONDITIONAL

The Web Services API version that you submitted the request in.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
8

error   = CONDITIONAL

Information on possible error conditions that may occur while processing an operation using the API.
Fixed value

error.cause  Enumeration = CONDITIONAL

Broadly categorizes the cause of the error.
For example, errors may occur due to invalid requests or internal system failures.
Fixed value
Validation Rules
XSD type
string
Value must be a member of the following list. The values are case sensitive.
INVALID_REQUEST
The request was rejected because it did not conform to the API protocol.
REQUEST_REJECTED
The request was rejected due to security reasons such as firewall rules, expired certificate, etc.
SERVER_BUSY
The server did not have enough resources to process the request at the moment.
SERVER_FAILED
There was an internal system failure.

error.explanation  String = CONDITIONAL

Textual description of the error based on the cause.
This field is returned only if the cause is INVALID_REQUEST or SERVER_BUSY.
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
1000

error.field  String = CONDITIONAL

Indicates the name of the field that failed validation.
This field is returned only if the cause is INVALID_REQUEST and a field level validation error was encountered.
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
100

error.supportCode  String = CONDITIONAL

Indicates the code that helps the support team to quickly identify the exact cause of the error.
This field is returned only if the cause is SERVER_FAILED or REQUEST_REJECTED.
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
100

error.validationType  Enumeration = CONDITIONAL

Indicates the type of field validation error.
This field is returned only if the cause is INVALID_REQUEST and a field level validation error was encountered.
Fixed value
Validation Rules
XSD type
string
Value must be a member of the following list. The values are case sensitive.
INVALID
The request contained a field with a value that did not pass validation.
MISSING
The request was missing a mandatory field.
UNSUPPORTED
The request contained a field that is unsupported.

result  Enumeration = CONDITIONAL

A system-generated high level overall result of the operation.
Fixed value
Validation Rules
XSD type
string
Value must be a member of the following list. The values are case sensitive.
ERROR
The operation resulted in an error and hence cannot be processed.

Copyright © 2023 Mastercard