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.

PUT https://test-gateway.mastercard.com/api/rest/version/65 / merchant / {merchantId} / order / {orderid} / transaction / {transactionid}

Authentication Copied to clipboard

This operation requires authentication via one of the following methods:


  • Certificate authentication.
  • Basic HTTP authentication as described at w3.org. Provide 'merchant.<your gateway merchant ID>' in the userid portion and your API password in the password portion.

Request Copied to clipboard

URL Parameters Copied to clipboard

{merchantId} Copied to clipboard Alphanumeric + additional characters REQUIRED

The unique identifier issued to you by your payment provider.


This identifier can be up to 12 characters in length.


Data may consist of the characters 0-9, a-z, A-Z, '-', '_'

Min length: 1 Max length: 40
{orderid} Copied to clipboard String REQUIRED

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.


Data can consist of any characters

Min length: 1 Max length: 40
{transactionid} Copied to clipboard String REQUIRED

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.


Data can consist of any characters

Min length: 1 Max length: 40

Fields Copied to clipboard

apiOperation Copied to clipboard String = INITIATE_AUTHENTICATION FIXED

Any sequence of zero or more unicode characters.

authentication Copied to clipboard 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.

authentication.acceptVersions Copied to clipboard Comma Separated Enumeration OPTIONAL

A comma separated list of the payer authentication methods that you will accept for this payment.

You only need to provide a value if you want to restrict the authentication methods you will accept.

If you do not specify a value, then the gateway treats it as if you will accept all available authentication methods.

If you accept both 3DS2 and 3DS1, then the gateway will use 3-D Secure version 2 if supported by the issuer and fallback to use 3-D Secure version 1 if it is not.

Value must be one or more comma separated members of the following list. The values are case sensitive.

3DS1

3-D Secure Version 1

3DS2

3-D Secure Version 2

authentication.channel Copied to clipboard Enumeration REQUIRED

Indicates the channel in which the authentication request is being initiated.

Value must be a member of the following list. The values are case sensitive.

MERCHANT_REQUESTED

The merchant is requesting authentication of a cardholder without the payer being available for interaction (for example. as part of processing of a recurring payment).

PAYER_APP

Payer is interacting via an application on their device which uses an EMVCo-certified SDK.

PAYER_BROWSER

Payer is interacting via web browser (for example, with the merchant's ecommerce web-site).

authentication.purpose Copied to clipboard Enumeration OPTIONAL

Indicates the context in which payer authentication is being requested.

If you do not provide a value, the gateway will use PAYMENT_TRANSACTION as the default.

If you are authenticating the payer when establishing a payment agreement with your payer for a series of recurring, installment or unscheduled payments you must provide details about the agreement in the agreement parameter group in the AUTHENTICATE_PAYER request for this transaction.

Note:

  • • If you set this value to ADD_CARD or MAINTAIN_CARD, then set order.amount to zero and order.currency to any currency you support.
  • • If the authentication scheme that applies to the account does not support the purpose that you have requested, this call will return an authenticationStatus of AUTHENTICATION_NOT_SUPPORTED.
  • • If you set this to REFRESH_AUTHENTICATION then when you perform the subsequent Authenticate Payer operation you must provide details of the original authentication, either by providing the authentication data explicitly via the fields customer.account.history.issuerAuthentication.acsTransactionId, customer.account.history.issuerAuthentication.authenticationToken, customer.account.history.issuerAuthentication.time and customer.account.history.issuerAuthentication.type, or by providing the gateway reference of the original authentication operation in customer.account.history.issuerAuthentication.transactionId.

Value must be a member of the following list. The values are case sensitive.

ADD_CARD

Authentication performed before a payer's card is stored on file either directly by the merchant or using the gateway's tokenization feature. A payment is not being processed.

MAINTAIN_CARD

Authentication performed before updating details of a payer's card stored on file either directly by the merchant or using the gateway's tokenization feature. A payment is not being processed.

PAYMENT_TRANSACTION

Authentication performed when of processing a card payment.

REFRESH_AUTHENTICATION

Authentication performed in order to obtain a new authentication token to replace one previously obtained for the order which is no longer valid (for example, because the order amount has changed in the time between originally performing authentication and submitting the financial transaction).

correlationId Copied to clipboard 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.

Data can consist of any characters

Min length: 1 Max length: 100
order Copied to clipboard OPTIONAL

Information about the order associated with this transaction.

order.reference Copied to clipboard String OPTIONAL

The identifier of the order.

For example, a shopping cart number, an order number, or an invoice number.

Data can consist of any characters

Min length: 1 Max length: 40
order.subMerchant Copied to clipboard 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.

order.subMerchant.address Copied to clipboard OPTIONAL

The sub-merchant's address.

order.subMerchant.address.city Copied to clipboard String OPTIONAL

The city portion of the address.

Data can consist of any characters

Min length: 1 Max length: 100
order.subMerchant.address.company Copied to clipboard String OPTIONAL

The name of the company associated with this address.

Data can consist of any characters

Min length: 1 Max length: 100
order.subMerchant.address.country Copied to clipboard Upper case alphabetic text OPTIONAL

The 3 letter ISO standard alpha country code of the address.

Data must consist of the characters A-Z

Min length: 3 Max length: 3
order.subMerchant.address.postcodeZip Copied to clipboard Alphanumeric + additional characters OPTIONAL

The post code or zip code of the address.

Data may consist of the characters 0-9, a-z, A-Z, ' ', '-'

Min length: 1 Max length: 10
order.subMerchant.address.stateProvince Copied to clipboard String OPTIONAL

The state or province of the address.

Data can consist of any characters

Min length: 1 Max length: 20
order.subMerchant.address.street Copied to clipboard String OPTIONAL

The first line of the address.

For example, this may be the street name and number, or the Post Office Box details.

Data can consist of any characters

Min length: 1 Max length: 100
order.subMerchant.address.street2 Copied to clipboard String OPTIONAL

The second line of the address (if provided).

Data can consist of any characters

Min length: 1 Max length: 100
order.subMerchant.authentication[n] Copied to clipboard OPTIONAL

Information about the sub-merchant's registration to use a payer authentication protocol.

For example, using 3-D Secure authentication.

order.subMerchant.authentication[n].3DS2 Copied to clipboard 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.

order.subMerchant.authentication[n].3DS2.requestorId Copied to clipboard 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.

For American Express and UnionPay if it is provided it will be used otherwise it will be generated by the gateway. This identifier should not be provided for other supported authentication schemes, as it will be generated by the gateway.

Data can consist of any characters

Min length: 1 Max length: 35
order.subMerchant.authentication[n].3DS2.requestorName Copied to clipboard 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.

For American Express and UnionPay if it is provided it will be used otherwise it will be generated by the gateway. This name should not be provided for other supported authentication schemes, as it will be generated by the gateway.

Data can consist of any characters

Min length: 1 Max length: 40
order.subMerchant.authentication[n].protocol Copied to clipboard Enumeration REQUIRED

The protocol used for payer authentication.

Value must be a member of the following list. The values are case sensitive.

AMEX_SAFEKEY

American Express SafeKey EMV 3DS authentication

UNIONPAY

UnionPay EMV 3DS authentication

VERIFIED_BY_VISA

Visa Verified by Visa EMV 3DS authentication

order.subMerchant.bankIndustryCode Copied to clipboard 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.

Data is a string that consists of the characters 0-9.

Min length: 4 Max length: 4
order.subMerchant.disputeContactPhone Copied to clipboard 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.

Data consists of '+', country code (1, 2 or 3 digits), 'space', and national number (which may embed single space characters for readability)

Mandatory country code: true Max total digits: 15
order.subMerchant.email Copied to clipboard Email OPTIONAL

The sub-merchant's email address.

Ensures that the email address is longer than 3 characters and adheres to a generous subset of valid RFC 2822 email addresses

order.subMerchant.identifier Copied to clipboard String REQUIRED

Your identifier for the sub-merchant.

You can use this identifier in searches and reports in the gateway.

Data can consist of any characters

Min length: 1 Max length: 100
order.subMerchant.phone Copied to clipboard String OPTIONAL

The sub-merchant's phone number

Data can consist of any characters

Min length: 1 Max length: 20
order.subMerchant.registeredName Copied to clipboard String OPTIONAL

The legal name of the sub-merchant.

Data can consist of any characters

Min length: 1 Max length: 100
order.subMerchant.tradingName Copied to clipboard String REQUIRED

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.

Data can consist of any characters

Min length: 1 Max length: 100
order.subMerchant.websiteUrl Copied to clipboard Url OPTIONAL

The URL of the sub-merchant's website.

Ensure that the URL begins with 'https' and is longer than 11 characters.

order.walletProvider Copied to clipboard Enumeration OPTIONAL

The wallet provider used to collect the customer's payment details used for this transaction.

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.

SECURE_REMOTE_COMMERCE

Secure Remote Commerce (SRC) wallet provider.

VISA_CHECKOUT

Visa Checkout wallet provider.

order.currency Copied to clipboard Upper case alphabetic text REQUIRED

The currency of the transaction expressed as an ISO 4217 alpha code, e.g. USD.

Data must consist of the characters A-Z

Min length: 3 Max length: 3
order.merchantCategoryCode Copied to clipboard 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.

Data is a string that consists of the characters 0-9.

Min length: 4 Max length: 4
order.notificationUrl Copied to clipboard 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

Ensure that the URL begins with 'https' and is longer than 11 characters.

partnerSolutionId Copied to clipboard 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.

Data can consist of any characters

Min length: 1 Max length: 40
session.id Copied to clipboard 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.

Data consists of ASCII characters

Min length: 31 Max length: 35
session.version Copied to clipboard 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.

Data consists of ASCII characters

Min length: 10 Max length: 10
sourceOfFunds Copied to clipboard 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.

sourceOfFunds.provided Copied to clipboard 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.

sourceOfFunds.provided.card Copied to clipboard OPTIONAL

Details as shown on the card.

sourceOfFunds.provided.card.devicePayment Copied to clipboard 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.

sourceOfFunds.provided.card.devicePayment.3DSecure Copied to clipboard OPTIONAL

Details used to process a digital payment where the payment data keys for the online payment cryptogram are provided using the 3-D Secure format.

Use this parameter group for:

  • • Device payments: if you decrypt the payment token yourself. In this case, you source these fields directly from the decrypted payment token.
    You do not need to use this parameter group if you provide the payment token in sourceOfFunds.provided.card.devicePayment.paymentToken.
  • • Card scheme tokens: if you decrypt the transaction credentials yourself.

sourceOfFunds.provided.card.devicePayment.3DSecure.eciIndicator Copied to clipboard 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.

Data is a string that consists of the characters 0-9.

Min length: 1 Max length: 2
sourceOfFunds.provided.card.devicePayment.3DSecure.onlinePaymentCryptogram Copied to clipboard 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.

Data is Base64 encoded

Min length: 1 Max length: 128
sourceOfFunds.provided.card.devicePayment.cryptogramFormat Copied to clipboard 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.

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.paymentToken Copied to clipboard 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.

Data can consist of any characters

Min length: 1 Max length: 16384
sourceOfFunds.provided.card.number Copied to clipboard 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.

Data is a string that consists of the characters 0-9.

Min length: 9 Max length: 19
sourceOfFunds.token Copied to clipboard Alphanumeric OPTIONAL

Gateway token that uniquely identifies a card and associated details.

Data may consist of the characters 0-9, a-z, A-Z

Min length: 1 Max length: 40
sourceOfFunds.type Copied to clipboard 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.

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 Copied to clipboard 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

subgatewayMerchant.acquirer[n] Copied to clipboard REQUIRED

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)

subgatewayMerchant.acquirer[n].3DS1 Copied to clipboard OPTIONAL

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

subgatewayMerchant.acquirer[n].3DS1.mastercardSecureCode Copied to clipboard OPTIONAL

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

subgatewayMerchant.acquirer[n].3DS1.mastercardSecureCode.merchantId Copied to clipboard 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.

Data can consist of any characters

Min length: 1 Max length: 24
subgatewayMerchant.acquirer[n].3DS1.verifiedByVisa Copied to clipboard OPTIONAL

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

subgatewayMerchant.acquirer[n].3DS1.verifiedByVisa.cardAcceptorId Copied to clipboard 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.

Data can consist of any characters

Min length: 1 Max length: 15
subgatewayMerchant.acquirer[n].3DS1.verifiedByVisa.cardAcceptorTerminalId Copied to clipboard 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.

Data can consist of any characters

Min length: 1 Max length: 8
subgatewayMerchant.acquirer[n].acquirerMerchantId Copied to clipboard String REQUIRED

The identifier (ID/SE Number/account name or such ) allocated to your merchant by their acquiring institution.

Data can consist of any characters

Min length: 0 Max length: 40
subgatewayMerchant.acquirer[n].amexSafeKey Copied to clipboard OPTIONAL

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

subgatewayMerchant.acquirer[n].amexSafeKey.merchantId Copied to clipboard Regex OPTIONAL

The unique identifier assigned to the merchant by their acquirer when they registered to use American Express SafeKey 3-D Secure authentication.

Data must match regex

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 Copied to clipboard Upper case alphabetic text OPTIONAL

The ISO 3166 three-letter country code of the acquirer.

Data must consist of the characters A-Z

Min length: 3 Max length: 3
subgatewayMerchant.acquirer[n].fraudRate Copied to clipboard Integer OPTIONAL

The merchant's fraud rate, as determined by the acquirer, expressed in basis points (bps).

JSON number data type, restricted to being positive or zero. In addition, the represented number may have no fractional part.

Min value: 0 Max value: 99999
subgatewayMerchant.acquirer[n].id Copied to clipboard String REQUIRED

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.

Data can consist of any characters

Min length: 0 Max length: 40
subgatewayMerchant.acquirer[n].merchantCategoryCode Copied to clipboard 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.

Data is a string that consists of the characters 0-9.

Min length: 4 Max length: 4
subgatewayMerchant.address Copied to clipboard OPTIONAL

The address of this merchant.

subgatewayMerchant.address.city Copied to clipboard String REQUIRED

The city or town of this merchant's billing address.

Data can consist of any characters

Min length: 1 Max length: 30
subgatewayMerchant.address.countryCode Copied to clipboard Upper case alphabetic text REQUIRED

The country of this merchant's billing address.

The value must be a three-letter country code according to ISO 3166-1 alpha-3.

Data must consist of the characters A-Z

Min length: 3 Max length: 3
subgatewayMerchant.address.postcodeZip Copied to clipboard String REQUIRED

The zip or postal code of this merchant's billing address.

Data can consist of any characters

Min length: 1 Max length: 16
subgatewayMerchant.address.stateProvince Copied to clipboard String REQUIRED

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.

Data can consist of any characters

Min length: 1 Max length: 30
subgatewayMerchant.address.street1 Copied to clipboard String REQUIRED

The first line of the street address of this merchant's billing address.

Data can consist of any characters

Min length: 1 Max length: 40
subgatewayMerchant.address.street2 Copied to clipboard String OPTIONAL

The second line of the street address of this merchant's billing address.

Data can consist of any characters

Min length: 1 Max length: 40
subgatewayMerchant.authentication[n] Copied to clipboard OPTIONAL

Information about the merchant's registration to use a payer authentication protocol.

For example, using 3-D Secure authentication.

subgatewayMerchant.authentication[n].3DS2 Copied to clipboard 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.

subgatewayMerchant.authentication[n].3DS2.requestorId Copied to clipboard 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.

Data can consist of any characters

Min length: 1 Max length: 35
subgatewayMerchant.authentication[n].3DS2.requestorName Copied to clipboard 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.

Data can consist of any characters

Min length: 1 Max length: 40
subgatewayMerchant.authentication[n].acquirerBIN Copied to clipboard 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

Data is a string that consists of the characters 0-9.

Min length: 4 Max length: 11
subgatewayMerchant.authentication[n].protocol Copied to clipboard Enumeration REQUIRED

The protocol used for payer authentication.

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 Copied to clipboard Alphanumeric + additional characters REQUIRED

The identifier you use to uniquely identify this merchant on your system.

Data may consist of the characters 0-9, a-z, A-Z, '_', '-'

Min length: 1 Max length: 36
subgatewayMerchant.name Copied to clipboard String REQUIRED

This merchant's registered business, trading or organization name.

This must match the merchant name you provided during registration with scheme Directory Servers.

Data can consist of any characters

Min length: 1 Max length: 100
subgatewayMerchant.websiteUrl Copied to clipboard Url REQUIRED

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.

Ensure that the URL begins with 'https' and is longer than 11 characters.

transaction Copied to clipboard OPTIONAL

Information about this transaction.

transaction.reference Copied to clipboard String OPTIONAL

An optional identifier for this transaction.

Data can consist of any characters

Min length: 1 Max length: 40

Response Copied to clipboard

Fields Copied to clipboard

authentication Copied to clipboard 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.

authentication.3ds1 Copied to clipboard CONDITIONAL

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

authentication.3ds1.veResEnrolled Copied to clipboard 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™.

Data may consist of the characters a-z, A-Z

Min length: 1 Max length: 1
authentication.3ds2 Copied to clipboard CONDITIONAL

Information about payer authentication using 3-D Secure authentication version 2.

authentication.3ds2.directoryServerId Copied to clipboard String CONDITIONAL

Unique identifier for the Directory Server (also called Registered Application Provider Identifier or RID).

This value is applicable when you authenticate the payer in-app using 3-D Secure authentication version 2.

In this case, provide this value in the directoryServerId field on the createTransaction method request message sent from the app on the payer's device to the 3-D Secure Software Development Kit (SDK).

Data can consist of any characters

Min length: 10 Max length: 10
authentication.3ds2.methodCompleted Copied to clipboard Boolean ALWAYS PROVIDED

Indicates if the issuer's Access Control Server (ACS) completed the method call to obtain additional information about the payer's browser.

JSON boolean values 'true' or 'false'.

authentication.3ds2.methodSupported Copied to clipboard Enumeration ALWAYS PROVIDED

Indicates if the issuer's Access Control Server (ACS) support the method call.

Value must be a member of the following list. The values are case sensitive.

NOT_SUPPORTED

The ACS does not support the method call protocol.

SUPPORTED

The ACS supports the method call protocol.

authentication.3ds2.protocolVersion Copied to clipboard Alphanumeric + additional characters CONDITIONAL

The version of the EMV 3-D Secure protocol used to perform 3-D Secure authentication, in the format specified by EMVCo.

For example, 2.1.0.

Data may consist of the characters 0-9, a-z, A-Z, '.'

Min length: 1 Max length: 20
authentication.3ds2.requestorId Copied to clipboard String ALWAYS PROVIDED

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.

Data can consist of any characters

Min length: 1 Max length: 35
authentication.3ds2.requestorName Copied to clipboard String ALWAYS PROVIDED

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.

Data can consist of any characters

Min length: 1 Max length: 40
authentication.acceptVersions Copied to clipboard Comma Separated Enumeration ALWAYS PROVIDED

A comma separated list of the payer authentication methods that you will accept for this payment.

You only need to provide a value if you want to restrict the authentication methods you will accept.

If you do not specify a value, then the gateway treats it as if you will accept all available authentication methods.

If you accept both 3DS2 and 3DS1, then the gateway will use 3-D Secure version 2 if supported by the issuer and fallback to use 3-D Secure version 1 if it is not.

Value must be one or more comma separated members of the following list. The values are case sensitive.

3DS1

3-D Secure Version 1

3DS2

3-D Secure Version 2

authentication.channel Copied to clipboard Enumeration ALWAYS PROVIDED

Indicates the channel in which the authentication request is being initiated.

Value must be a member of the following list. The values are case sensitive.

MERCHANT_REQUESTED

The merchant is requesting authentication of a cardholder without the payer being available for interaction (for example. as part of processing of a recurring payment).

PAYER_APP

Payer is interacting via an application on their device which uses an EMVCo-certified SDK.

PAYER_BROWSER

Payer is interacting via web browser (for example, with the merchant's ecommerce web-site).

authentication.method Copied to clipboard Enumeration CONDITIONAL

The method that the issuer will use to authenticate the payer.

Value must be a member of the following list. The values are case sensitive.

DYNAMIC

The payer is authenticated using dynamic data. For example, a code sent to the payer's phone.

OUT_OF_BAND

The payer is authenticated by the issuer using another method. For example, by using a bank app on the payer's mobile device.

STATIC

The payer is authenticated using static data. For example, by providing responses to security questions for the payer's account.

authentication.purpose Copied to clipboard Enumeration CONDITIONAL

Indicates the context in which payer authentication is being requested.

If you do not provide a value, the gateway will use PAYMENT_TRANSACTION as the default.

If you are authenticating the payer when establishing a payment agreement with your payer for a series of recurring, installment or unscheduled payments you must provide details about the agreement in the agreement parameter group in the AUTHENTICATE_PAYER request for this transaction.

Note:

  • • If you set this value to ADD_CARD or MAINTAIN_CARD, then set order.amount to zero and order.currency to any currency you support.
  • • If the authentication scheme that applies to the account does not support the purpose that you have requested, this call will return an authenticationStatus of AUTHENTICATION_NOT_SUPPORTED.
  • • If you set this to REFRESH_AUTHENTICATION then when you perform the subsequent Authenticate Payer operation you must provide details of the original authentication, either by providing the authentication data explicitly via the fields customer.account.history.issuerAuthentication.acsTransactionId, customer.account.history.issuerAuthentication.authenticationToken, customer.account.history.issuerAuthentication.time and customer.account.history.issuerAuthentication.type, or by providing the gateway reference of the original authentication operation in customer.account.history.issuerAuthentication.transactionId.

Value must be a member of the following list. The values are case sensitive.

ADD_CARD

Authentication performed before a payer's card is stored on file either directly by the merchant or using the gateway's tokenization feature. A payment is not being processed.

MAINTAIN_CARD

Authentication performed before updating details of a payer's card stored on file either directly by the merchant or using the gateway's tokenization feature. A payment is not being processed.

PAYMENT_TRANSACTION

Authentication performed when of processing a card payment.

REFRESH_AUTHENTICATION

Authentication performed in order to obtain a new authentication token to replace one previously obtained for the order which is no longer valid (for example, because the order amount has changed in the time between originally performing authentication and submitting the financial transaction).

authentication.redirect Copied to clipboard CONDITIONAL

A collection of parameters required to produce the UI for payer authentication.

An example of a payer authentication UI is the redirection of the payer's browser to the issuer's Access Control Server (ACS) for 3-D Secure authentication. The gateway supports two models:

  • SIMPLE: The gateway gives you content (HTML and JavaScript) to put on your payment page, and that automatically triggers the authentication user experience.
  • CUSTOMIZED: The gateway gives you the raw parameters for the authentication method, and you create the required user experience yourself.

If you selected the SIMPLE case, the gateway will provide the authenticationRedirect data, even if your authentication system does not require it. This lets you have a single flow through your code for all authentication cases.

authentication.redirect.customized Copied to clipboard CONDITIONAL

The raw parameters for the authentication method, for you to create the required user experience yourself.

authentication.redirect.customized.3DS Copied to clipboard CONDITIONAL

The raw parameters for 3-D Secure authentication.

authentication.redirect.customized.3DS.methodPostData Copied to clipboard Base64 ALWAYS PROVIDED

Base64 URL encoded frame contents to be posted to the URL provided in authentication.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. See EMVCo specification for details.

Data is Base64 encoded

Min length: 3 Max length: 1000
authentication.redirect.customized.3DS.methodUrl Copied to clipboard Url CONDITIONAL

The URL provided by the issuer to which you must post the data provided in authentication.3ds2.methodPostData.

See EMVCo specification for details.

Note: To simplify your integration, the gateway will always provide a methodURL that supports the EMVCo specification (even if the issuer's Access Control Server (ACS) does not provide a real one).

Ensure that the URL begins with 'https' and is longer than 11 characters.

authentication.redirectHtml Copied to clipboard String CONDITIONAL

Code to create the authentication UI.

Write this content into an empty <DIV> element being the last element in the <BODY> of your payment page.

Data can consist of any characters

Min length: 0 Max length: 40960
authentication.version Copied to clipboard Enumeration ALWAYS PROVIDED

If online authentication of the payer is available, then this field shows the type.

If no such authentication is available, the value is NONE.

Value must be a member of the following list. The values are case sensitive.

3DS1

3-D Secure Version 1 authentication is available.

3DS2

3-D Secure Version 2 authentication is available.

RUPAY

RuPay authentication is available.

NONE

No authentication is available.

correlationId Copied to clipboard 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.

Data can consist of any characters

Min length: 1 Max length: 100
encryptedData Copied to clipboard 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.

encryptedData.ciphertext Copied to clipboard String ALWAYS PROVIDED

Base64 encoded ciphertext.

Data can consist of any characters

Min length: 1 Max length: 10000
encryptedData.nonce Copied to clipboard String ALWAYS PROVIDED

Base64 encoded GCM nonce.

Data can consist of any characters

Min length: 16 Max length: 16
encryptedData.tag Copied to clipboard String ALWAYS PROVIDED

Base64 encoded GCM tag.

Data can consist of any characters

Min length: 24 Max length: 24
lineOfBusiness Copied to clipboard 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.

Data can consist of any characters except space

Min length: 1 Max length: 100
merchant Copied to clipboard Alphanumeric + additional characters ALWAYS PROVIDED

The unique identifier issued to you by your payment provider.

This identifier can be up to 12 characters in length.

Data may consist of the characters 0-9, a-z, A-Z, '-', '_'

Min length: 1 Max length: 40
order Copied to clipboard ALWAYS PROVIDED

Information about the order associated with this transaction.

order.authenticationStatus Copied to clipboard Enumeration CONDITIONAL

Indicates the result of payer authentication.

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 Copied to clipboard DateTime ALWAYS PROVIDED

Indicates the date and time the gateway considers the order to have been created.

An instant in time expressed in ISO8601 date + time format - "YYYY-MM-DDThh:mm:ss.SSSZ"

order.currency Copied to clipboard Upper case alphabetic text ALWAYS PROVIDED

The currency of the order expressed as an ISO 4217 alpha code, e.g. USD.

Data must consist of the characters A-Z

Min length: 3 Max length: 3
order.id Copied to clipboard 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.

Data can consist of any characters

Min length: 1 Max length: 40
order.lastUpdatedTime Copied to clipboard DateTime ALWAYS PROVIDED

Indicates the date and time the gateway considers the order to have last been updated.

An instant in time expressed in ISO8601 date + time format - "YYYY-MM-DDThh:mm:ss.SSSZ"

order.merchantCategoryCode Copied to clipboard 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.

Data is a string that consists of the characters 0-9.

Min length: 4 Max length: 4
order.notificationUrl Copied to clipboard 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

Ensure that the URL begins with 'https' and is longer than 11 characters.

order.reference Copied to clipboard String CONDITIONAL

An optional identifier for the order.

For example, a shopping cart number, an order number, or an invoice number.

Data can consist of any characters

Min length: 1 Max length: 200
order.status Copied to clipboard Enumeration CONDITIONAL

The current progression of this order through the payment process.

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 Copied to clipboard 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.

order.subMerchant.address Copied to clipboard CONDITIONAL

The sub-merchant's address.

order.subMerchant.address.city Copied to clipboard String CONDITIONAL

The city portion of the address.

Data can consist of any characters

Min length: 1 Max length: 100
order.subMerchant.address.company Copied to clipboard String CONDITIONAL

The name of the company associated with this address.

Data can consist of any characters

Min length: 1 Max length: 100
order.subMerchant.address.country Copied to clipboard Upper case alphabetic text CONDITIONAL

The 3 letter ISO standard alpha country code of the address.

Data must consist of the characters A-Z

Min length: 3 Max length: 3
order.subMerchant.address.postcodeZip Copied to clipboard Alphanumeric + additional characters CONDITIONAL

The post code or zip code of the address.

Data may consist of the characters 0-9, a-z, A-Z, ' ', '-'

Min length: 1 Max length: 10
order.subMerchant.address.stateProvince Copied to clipboard String CONDITIONAL

The state or province of the address.

Data can consist of any characters

Min length: 1 Max length: 20
order.subMerchant.address.street Copied to clipboard String CONDITIONAL

The first line of the address.

For example, this may be the street name and number, or the Post Office Box details.

Data can consist of any characters

Min length: 1 Max length: 100
order.subMerchant.address.street2 Copied to clipboard String CONDITIONAL

The second line of the address (if provided).

Data can consist of any characters

Min length: 1 Max length: 100
order.subMerchant.authentication[n] Copied to clipboard CONDITIONAL

Information about the sub-merchant's registration to use a payer authentication protocol.

For example, using 3-D Secure authentication.

order.subMerchant.authentication[n].3DS2 Copied to clipboard 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.

order.subMerchant.authentication[n].3DS2.requestorId Copied to clipboard 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.

For American Express and UnionPay if it is provided it will be used otherwise it will be generated by the gateway. This identifier should not be provided for other supported authentication schemes, as it will be generated by the gateway.

Data can consist of any characters

Min length: 1 Max length: 35
order.subMerchant.authentication[n].3DS2.requestorName Copied to clipboard 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.

For American Express and UnionPay if it is provided it will be used otherwise it will be generated by the gateway. This name should not be provided for other supported authentication schemes, as it will be generated by the gateway.

Data can consist of any characters

Min length: 1 Max length: 40
order.subMerchant.authentication[n].protocol Copied to clipboard Enumeration ALWAYS PROVIDED

The protocol used for payer authentication.

Value must be a member of the following list. The values are case sensitive.

AMEX_SAFEKEY

American Express SafeKey EMV 3DS authentication

UNIONPAY

UnionPay EMV 3DS authentication

VERIFIED_BY_VISA

Visa Verified by Visa EMV 3DS authentication

order.subMerchant.bankIndustryCode Copied to clipboard 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.

Data is a string that consists of the characters 0-9.

Min length: 4 Max length: 4
order.subMerchant.disputeContactPhone Copied to clipboard 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.

Data consists of '+', country code (1, 2 or 3 digits), 'space', and national number (which may embed single space characters for readability)

Mandatory country code: true Max total digits: 15
order.subMerchant.email Copied to clipboard Email CONDITIONAL

The sub-merchant's email address.

Ensures that the email address is longer than 3 characters and adheres to a generous subset of valid RFC 2822 email addresses

order.subMerchant.identifier Copied to clipboard String ALWAYS PROVIDED

Your identifier for the sub-merchant.

You can use this identifier in searches and reports in the gateway.

Data can consist of any characters

Min length: 1 Max length: 100
order.subMerchant.phone Copied to clipboard String CONDITIONAL

The sub-merchant's phone number

Data can consist of any characters

Min length: 1 Max length: 20
order.subMerchant.registeredName Copied to clipboard String CONDITIONAL

The legal name of the sub-merchant.

Data can consist of any characters

Min length: 1 Max length: 100
order.subMerchant.tradingName Copied to clipboard 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.

Data can consist of any characters

Min length: 1 Max length: 100
order.subMerchant.websiteUrl Copied to clipboard Url CONDITIONAL

The URL of the sub-merchant's website.

Ensure that the URL begins with 'https' and is longer than 11 characters.

order.totalAuthorizedAmount Copied to clipboard Decimal ALWAYS PROVIDED

The amount that has been successfully authorized for this order.

Data is a decimal number.

Max value: 1000000000000 Min value: 0 Max post-decimal digits: 3
order.totalCapturedAmount Copied to clipboard Decimal ALWAYS PROVIDED

The amount that has been successfully captured for this order.

Data is a decimal number.

Max value: 1000000000000 Min value: 0 Max post-decimal digits: 3
order.totalRefundedAmount Copied to clipboard Decimal ALWAYS PROVIDED

The amount that has been successfully refunded for this order.

Data is a decimal number.

Max value: 1000000000000 Min value: 0 Max post-decimal digits: 3
order.walletProvider Copied to clipboard Enumeration CONDITIONAL

The wallet provider used to collect the customer's payment details used for this transaction.

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.

SECURE_REMOTE_COMMERCE

Secure Remote Commerce (SRC) wallet provider.

VISA_CHECKOUT

Visa Checkout wallet provider.

partnerSolutionId Copied to clipboard 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.

Data can consist of any characters

Min length: 1 Max length: 40
response Copied to clipboard ALWAYS PROVIDED
response.debugInformation Copied to clipboard 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.

Data can consist of any characters

Min length: 1 Max length: 2064
response.gatewayCode Copied to clipboard Enumeration ALWAYS PROVIDED

Summary of the success or otherwise of the operation.

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 Copied to clipboard Enumeration CONDITIONAL

If a payment fails, this indicates how you could change the request to bring about success.

This field is only present if your gateway configuration supports optional payment features.

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 by either: Authenticating the payer using the Authenticate Payer operation or Submitting the payment request as the payer is sufficiently authenticated, or updating card details.

result Copied to clipboard Enumeration ALWAYS PROVIDED

A system-generated high level overall result of the operation.

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 Copied to clipboard 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.

sourceOfFunds.provided Copied to clipboard 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.

sourceOfFunds.provided.ach Copied to clipboard 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.

sourceOfFunds.provided.ach.accountType Copied to clipboard 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).

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 Copied to clipboard 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.

Data can consist of any characters

Min length: 1 Max length: 28
sourceOfFunds.provided.ach.bankAccountNumber Copied to clipboard 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.

Data may consist of the characters 0-9, a-z, A-Z, ' ', '-', '/'

Min length: 1 Max length: 17
sourceOfFunds.provided.ach.routingNumber Copied to clipboard 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.

Data is a string that consists of the characters 0-9.

Min length: 9 Max length: 9
sourceOfFunds.provided.ach.secCode Copied to clipboard 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/.

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 Copied to clipboard CONDITIONAL

Additional details related to a Bancontact payment.

sourceOfFunds.provided.bancontact.bankAccountHolder Copied to clipboard String ALWAYS PROVIDED

The name of the bank account holder for the payer's bank account.

Data can consist of any characters

Min length: 1 Max length: 255
sourceOfFunds.provided.blik Copied to clipboard CONDITIONAL

Additional details related to a BLIK browser payment.

sourceOfFunds.provided.blik.bankAccountHolder Copied to clipboard String ALWAYS PROVIDED

The name of the bank account holder for the payer's bank account.

Data can consist of any characters

Min length: 1 Max length: 255
sourceOfFunds.provided.boletoBancario Copied to clipboard 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)

sourceOfFunds.provided.boletoBancario.actionType Copied to clipboard Enumeration CONDITIONAL

The action to take if the payment is not honored.

Value must be a member of the following list. The values are case sensitive.

WRITE_OFF

Write off the Boleto.

sourceOfFunds.provided.boletoBancario.bankAccountHolder Copied to clipboard String ALWAYS PROVIDED

The name of the bank account holder for the payer's bank account.

Data can consist of any characters

Min length: 1 Max length: 255
sourceOfFunds.provided.boletoBancario.customerType Copied to clipboard Enumeration CONDITIONAL

Type of the Customer i.e. Individual or Company.

If the value is not provided it will be defaulted to INDIVIDUAL.

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 Copied to clipboard Digits CONDITIONAL

Number of days granted by you to the customer after the due date of Boleto payment before the specified action is taken.

Data is a string that consists of the characters 0-9.

Min length: 1 Max length: 2
sourceOfFunds.provided.boletoBancario.dueDate Copied to clipboard Date CONDITIONAL

The date by which the Boleto amount needs to be paid.

Data must comply with ISO 8601 extended date format, yyyy-mm-dd

sourceOfFunds.provided.boletoBancario.slipUrl Copied to clipboard Url CONDITIONAL

The URL issued by the gateway which you must use to retrieve collection bank slip.

Ensure that the URL begins with 'https' and is longer than 11 characters.

sourceOfFunds.provided.card Copied to clipboard 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).

sourceOfFunds.provided.card.accountType Copied to clipboard 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.

Value must be a member of the following list. The values are case sensitive.

CHECKING
SAVINGS
sourceOfFunds.provided.card.brand Copied to clipboard 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.

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 Copied to clipboard 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.

sourceOfFunds.provided.card.devicePayment.cryptogramFormat Copied to clipboard 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

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 Copied to clipboard 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.

sourceOfFunds.provided.card.deviceSpecificExpiry.month Copied to clipboard Digits ALWAYS PROVIDED

Month from the expiry date of the device specific account number.

Months are numbered January=1, through to December=12.

Data is a number between 1 and 12 represented as a string.

sourceOfFunds.provided.card.deviceSpecificExpiry.year Copied to clipboard Digits ALWAYS PROVIDED

Year from the expiry date of the device specific account number.

The Common Era year is 2000 plus this value.

Data is a string that consists of the characters 0-9.

Min length: 2 Max length: 2
sourceOfFunds.provided.card.deviceSpecificNumber Copied to clipboard 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

Data is a string that consists of the characters 0-9, plus 'x' for masking

Min length: 9 Max length: 19
sourceOfFunds.provided.card.emvRequest Copied to clipboard 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.

Data can consist of any characters

Min length: 1 Max length: 250
sourceOfFunds.provided.card.emvResponse Copied to clipboard 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.

Data can consist of any characters

Min length: 1 Max length: 250
sourceOfFunds.provided.card.encryption Copied to clipboard Enumeration CONDITIONAL

The encryption framework used for the payment details received by the gateway.

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 Copied to clipboard CONDITIONAL

Expiry date, as shown on the card.

This field corresponds to EMV tag 5F24

sourceOfFunds.provided.card.expiry.month Copied to clipboard Digits ALWAYS PROVIDED

Month, as shown on the card.

Months are numbered January=1, through to December=12.

Data is a number between 1 and 12 represented as a string.

sourceOfFunds.provided.card.expiry.year Copied to clipboard Digits ALWAYS PROVIDED

Year, as shown on the card.

The Common Era year is 2000 plus this value.

Data is a string that consists of the characters 0-9.

Min length: 2 Max length: 2
sourceOfFunds.provided.card.fundingMethod Copied to clipboard 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.

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 Copied to clipboard String CONDITIONAL

The issuer of the card, if known.

WARNING: This information may be incorrect or incomplete – use at your own risk.

Data can consist of any characters

Min length: 0 Max length: 255
sourceOfFunds.provided.card.localBrand Copied to clipboard 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.

Data can consist of any characters

Min length: 3 Max length: 50
sourceOfFunds.provided.card.nameOnCard Copied to clipboard String CONDITIONAL

The cardholder's name as printed on the card.

Data can consist of any characters

Min length: 1 Max length: 256
sourceOfFunds.provided.card.number Copied to clipboard 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.

Data is a string that consists of the characters 0-9, plus 'x' for masking

Min length: 9 Max length: 19
sourceOfFunds.provided.card.pin Copied to clipboard 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.

sourceOfFunds.provided.card.pin.encryptionState Copied to clipboard 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.

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 Copied to clipboard Hex ALWAYS PROVIDED

The DUKPT key serial number supplied by the terminal.

Data is hexadecimal encoded

Min length: 20 Max length: 20
sourceOfFunds.provided.card.scheme Copied to clipboard 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.

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 Copied to clipboard Digits CONDITIONAL

A number used to differentiate between cards with the same Primary Account Number (PAN).

This field corresponds to EMV tag 5F34

Data is a string that consists of the characters 0-9.

Min length: 3 Max length: 3
sourceOfFunds.provided.card.storedOnFile Copied to clipboard 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.

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 Copied to clipboard 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.

Data can consist of any characters

Min length: 1 Max length: 2048
sourceOfFunds.provided.card.trackDataProvided Copied to clipboard Boolean CONDITIONAL

Indicates whether card track data is provided.

JSON boolean values 'true' or 'false'.

sourceOfFunds.provided.ebt Copied to clipboard 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.

sourceOfFunds.provided.ebt.accountType Copied to clipboard Enumeration CONDITIONAL

Indicates the type of benefits account used for the payment.

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 Copied to clipboard 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.

Data is a string that consists of the characters 0-9.

Min length: 1 Max length: 6
sourceOfFunds.provided.ebt.merchantFns Copied to clipboard 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.

Data is a string that consists of the characters 0-9.

Min length: 1 Max length: 7
sourceOfFunds.provided.ebt.voucherNumber Copied to clipboard 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.

Data is a string that consists of the characters 0-9.

Min length: 1 Max length: 15
sourceOfFunds.provided.enets Copied to clipboard 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

sourceOfFunds.provided.enets.bankAccountHolder Copied to clipboard String ALWAYS PROVIDED

The name of the bank account holder for the payer's bank account.

Data can consist of any characters

Min length: 1 Max length: 255
sourceOfFunds.provided.giftCard Copied to clipboard CONDITIONAL

A gift card was used.

The payer's gift card details are provided in this parameter group.

sourceOfFunds.provided.giftCard.brand Copied to clipboard 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.

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 Copied to clipboard String ALWAYS PROVIDED

The brand name used to describe a card as determined by the gateway, based on the BIN range of the card.

Data can consist of any characters

Min length: 1 Max length: 50
sourceOfFunds.provided.giftCard.number Copied to clipboard Masked digits ALWAYS PROVIDED

Card number as printed or embossed on the gift card.

Data is a string that consists of the characters 0-9, plus 'x' for masking

Min length: 9 Max length: 19
sourceOfFunds.provided.giftCard.pin Copied to clipboard Masked digits CONDITIONAL

PIN number for the gift card.

Data is a string that consists of the characters 0-9, plus 'x' for masking

Min length: 4 Max length: 8
sourceOfFunds.provided.giftCard.scheme Copied to clipboard Enumeration ALWAYS PROVIDED

The organization that owns a card brand and defines operating regulations for its use.

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 Copied to clipboard CONDITIONAL

The additional details required to initiate a giropay browser payment.

sourceOfFunds.provided.giropay.bankIdentifier Copied to clipboard Digits CONDITIONAL

German bank identifier (Bankleitzahl) for the payer's bank account.

Data is a string that consists of the characters 0-9.

Min length: 8 Max length: 8
sourceOfFunds.provided.giropay.bic Copied to clipboard Alphanumeric CONDITIONAL

The international Business Identifier Code (BIC) for the payer's bank account.

Data may consist of the characters 0-9, a-z, A-Z

Min length: 8 Max length: 11
sourceOfFunds.provided.giropay.iban Copied to clipboard 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.

Data can consist of any characters

Min length: 1 Max length: 50
sourceOfFunds.provided.grabPay Copied to clipboard CONDITIONAL

Additional details related to GrabPay browser payment.

sourceOfFunds.provided.grabPay.accountHolder Copied to clipboard String ALWAYS PROVIDED

The name of the account holder for the payer's GrabPay account.

Data can consist of any characters

Min length: 3 Max length: 100
sourceOfFunds.provided.ideal Copied to clipboard CONDITIONAL

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

sourceOfFunds.provided.ideal.bankAccountHolder Copied to clipboard String CONDITIONAL

The name of the bank account holder for the payer's bank account.

Data can consist of any characters

Min length: 1 Max length: 255
sourceOfFunds.provided.ideal.bic Copied to clipboard Alphanumeric CONDITIONAL

The international Business Identifier Code (BIC) for the payer's bank account.

Data may consist of the characters 0-9, a-z, A-Z

Min length: 8 Max length: 11
sourceOfFunds.provided.ideal.iban Copied to clipboard 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.

Data can consist of any characters

Min length: 1 Max length: 50
sourceOfFunds.provided.klarnaPayNow Copied to clipboard CONDITIONAL

Additional details related to a Klarna Pay Now payment.

sourceOfFunds.provided.klarnaPayNow.bankAccountCountryCode Copied to clipboard Alpha ALWAYS PROVIDED

The country where the payer has their bank account.

Provide the ISO 3166 alpha-3 country code for this country.

Data may consist of the characters a-z, A-Z

Min length: 3 Max length: 3
sourceOfFunds.provided.openBankingBankTransfer Copied to clipboard CONDITIONAL

Additional details related to Open Banking Bank Transfer.

sourceOfFunds.provided.openBankingBankTransfer.aspspId Copied to clipboard String ALWAYS PROVIDED

Identifier of the payer's bank, also known as ASPSP (Account Servicing Payment Services Provider)

Data can consist of any characters

Min length: 1 Max length: 256
sourceOfFunds.provided.oxxo Copied to clipboard 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).

sourceOfFunds.provided.oxxo.bankAccountHolder Copied to clipboard String ALWAYS PROVIDED

The name of the bank account holder for the payer's bank account.

Data can consist of any characters

Min length: 1 Max length: 255
sourceOfFunds.provided.oxxo.dueDate Copied to clipboard Date CONDITIONAL

The date by which your payer has to make the payment.

Do not provide a due date for USD currency transactions.

Data must comply with ISO 8601 extended date format, yyyy-mm-dd

sourceOfFunds.provided.paypal Copied to clipboard 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.

sourceOfFunds.provided.paypal.accountEmail Copied to clipboard Email CONDITIONAL

The email address of the payer's PayPal account.

Ensures that the email address is longer than 3 characters and adheres to a generous subset of valid RFC 2822 email addresses

sourceOfFunds.provided.paypal.accountHolder Copied to clipboard String CONDITIONAL

The name of the account holder of the payer's PayPal account.

Data can consist of any characters

Min length: 1 Max length: 255
sourceOfFunds.provided.paypal.billingAgreement Copied to clipboard 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.

sourceOfFunds.provided.paypal.billingAgreement.cardinality Copied to clipboard Enumeration CONDITIONAL

Indicates the number of billing agreements between you and this payer.

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 Copied to clipboard 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.

Data can consist of any characters

Min length: 1 Max length: 255
sourceOfFunds.provided.paypal.billingAgreement.id Copied to clipboard String CONDITIONAL

An identifier provided by PayPal for the billing agreement.

Data can consist of any characters

Min length: 1 Max length: 100
sourceOfFunds.provided.paypal.billingAgreement.name Copied to clipboard String CONDITIONAL

Your name for the PayPal billing agreement.

Data can consist of any characters

Min length: 1 Max length: 255
sourceOfFunds.provided.paypal.payerId Copied to clipboard String CONDITIONAL

The unique identifier for the payer assigned by PayPal.

Data can consist of any characters

Min length: 1 Max length: 13
sourceOfFunds.provided.pbba Copied to clipboard CONDITIONAL

Additional details related to Pay by Bank app payment.

sourceOfFunds.provided.pbba.paymentRequestId Copied to clipboard 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.

Data is a string that consists of the characters 0-9.

Min length: 18 Max length: 18
sourceOfFunds.provided.pbba.paymentRequestInputCode Copied to clipboard 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.

Data must consist of the characters A-Z

Min length: 6 Max length: 6
sourceOfFunds.provided.poli Copied to clipboard CONDITIONAL

Additional details related to a POLi browser payment.

sourceOfFunds.provided.poli.bankAccountHolder Copied to clipboard String ALWAYS PROVIDED

The name of the bank account holder for the payer's bank account.

Data can consist of any characters

Min length: 1 Max length: 255
sourceOfFunds.provided.przelewy24 Copied to clipboard CONDITIONAL

Additional details related to a Przelewy24 browser payment.

sourceOfFunds.provided.przelewy24.bankAccountHolder Copied to clipboard String ALWAYS PROVIDED

The name of the bank account holder for the payer's bank account.

Data can consist of any characters

Min length: 1 Max length: 255
sourceOfFunds.provided.sepa Copied to clipboard CONDITIONAL

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

sourceOfFunds.provided.sepa.bankAccountHolder Copied to clipboard String ALWAYS PROVIDED

The name of the bank account holder for the payer's bank account.

Data can consist of any characters

Min length: 3 Max length: 100
sourceOfFunds.provided.sepa.bic Copied to clipboard Alphanumeric CONDITIONAL

The international Business Identifier Code (BIC) for the payer's bank account.

Data may consist of the characters 0-9, a-z, A-Z

Min length: 8 Max length: 11
sourceOfFunds.provided.sepa.iban Copied to clipboard 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.

Data can consist of any characters

Min length: 1 Max length: 50
sourceOfFunds.provided.sofort Copied to clipboard CONDITIONAL

Details about the payer's bank account used for a payment made using Sofortbanking.

The format of the bank account details differs per country.

sourceOfFunds.provided.sofort.bankAccountHolder Copied to clipboard String CONDITIONAL

The name of the bank account holder for the payer's bank account.

Data can consist of any characters

Min length: 1 Max length: 255
sourceOfFunds.provided.sofort.bankAccountNumber Copied to clipboard 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.

Data can consist of any characters

Min length: 1 Max length: 30
sourceOfFunds.provided.sofort.bankIdentifier Copied to clipboard String CONDITIONAL

The country-specific bank identifier for the payer's bank account.

Data can consist of any characters

Min length: 1 Max length: 30
sourceOfFunds.provided.sofort.bic Copied to clipboard String CONDITIONAL

The international Business Identifier Code (BIC) for the payer's bank account.

Data can consist of any characters

Min length: 1 Max length: 50
sourceOfFunds.provided.sofort.country Copied to clipboard Upper case alphabetic text CONDITIONAL

The 3 letter ISO standard alpha country code of the payer's bank account.

Data must consist of the characters A-Z

Min length: 3 Max length: 3
sourceOfFunds.provided.sofort.iban Copied to clipboard 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.

Data can consist of any characters

Min length: 1 Max length: 50
sourceOfFunds.provided.trustly Copied to clipboard CONDITIONAL

Additional details related to a Trustly.

sourceOfFunds.provided.trustly.bankAccountCountryCode Copied to clipboard Alpha ALWAYS PROVIDED

The country where the payer has their bank account.

Provide the ISO 3166 alpha-3 country code for this country.

Data may consist of the characters a-z, A-Z

Min length: 3 Max length: 3
sourceOfFunds.provided.trustly.bankAccountHolder Copied to clipboard String ALWAYS PROVIDED

The name of the bank account holder for the payer's bank account.

Data can consist of any characters

Min length: 1 Max length: 255
sourceOfFunds.provided.weChatPay Copied to clipboard CONDITIONAL

Additional details related to a WeChat Pay browser payment.

sourceOfFunds.provided.weChatPay.accountHolder Copied to clipboard String ALWAYS PROVIDED

The name of the account holder for the payer's WeChat Pay account.

Data can consist of any characters

Min length: 1 Max length: 255
sourceOfFunds.token Copied to clipboard Alphanumeric CONDITIONAL

Gateway token that uniquely identifies a card and associated details.

Data may consist of the characters 0-9, a-z, A-Z

Min length: 1 Max length: 40
sourceOfFunds.tokenRequestorID Copied to clipboard 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.

Data may consist of the characters 0-9, a-z, A-Z

Min length: 11 Max length: 11
sourceOfFunds.type Copied to clipboard 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.

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 Copied to clipboard 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

subgatewayMerchant.acquirer[n] Copied to clipboard 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)

subgatewayMerchant.acquirer[n].3DS1 Copied to clipboard CONDITIONAL

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

subgatewayMerchant.acquirer[n].3DS1.mastercardSecureCode Copied to clipboard CONDITIONAL

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

subgatewayMerchant.acquirer[n].3DS1.mastercardSecureCode.merchantId Copied to clipboard 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.

Data can consist of any characters

Min length: 1 Max length: 24
subgatewayMerchant.acquirer[n].3DS1.verifiedByVisa Copied to clipboard CONDITIONAL

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

subgatewayMerchant.acquirer[n].3DS1.verifiedByVisa.cardAcceptorId Copied to clipboard 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.

Data can consist of any characters

Min length: 1 Max length: 15
subgatewayMerchant.acquirer[n].3DS1.verifiedByVisa.cardAcceptorTerminalId Copied to clipboard 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.

Data can consist of any characters

Min length: 1 Max length: 8
subgatewayMerchant.acquirer[n].acquirerMerchantId Copied to clipboard String ALWAYS PROVIDED

The identifier (ID/SE Number/account name or such ) allocated to your merchant by their acquiring institution.

Data can consist of any characters

Min length: 0 Max length: 40
subgatewayMerchant.acquirer[n].amexSafeKey Copied to clipboard CONDITIONAL

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

subgatewayMerchant.acquirer[n].amexSafeKey.merchantId Copied to clipboard Regex CONDITIONAL

The unique identifier assigned to the merchant by their acquirer when they registered to use American Express SafeKey 3-D Secure authentication.

Data must match regex

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 Copied to clipboard Upper case alphabetic text CONDITIONAL

The ISO 3166 three-letter country code of the acquirer.

Data must consist of the characters A-Z

Min length: 3 Max length: 3
subgatewayMerchant.acquirer[n].fraudRate Copied to clipboard Integer CONDITIONAL

The merchant's fraud rate, as determined by the acquirer, expressed in basis points (bps).

JSON number data type, restricted to being positive or zero. In addition, the represented number may have no fractional part.

Min value: 0 Max value: 99999
subgatewayMerchant.acquirer[n].id Copied to clipboard 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.

Data can consist of any characters

Min length: 0 Max length: 40
subgatewayMerchant.acquirer[n].merchantCategoryCode Copied to clipboard 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.

Data is a string that consists of the characters 0-9.

Min length: 4 Max length: 4
subgatewayMerchant.address Copied to clipboard CONDITIONAL

The address of this merchant.

subgatewayMerchant.address.city Copied to clipboard String ALWAYS PROVIDED

The city or town of this merchant's billing address.

Data can consist of any characters

Min length: 1 Max length: 30
subgatewayMerchant.address.countryCode Copied to clipboard 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.

Data must consist of the characters A-Z

Min length: 3 Max length: 3
subgatewayMerchant.address.postcodeZip Copied to clipboard String ALWAYS PROVIDED

The zip or postal code of this merchant's billing address.

Data can consist of any characters

Min length: 1 Max length: 16
subgatewayMerchant.address.stateProvince Copied to clipboard 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.

Data can consist of any characters

Min length: 1 Max length: 30
subgatewayMerchant.address.street1 Copied to clipboard String ALWAYS PROVIDED

The first line of the street address of this merchant's billing address.

Data can consist of any characters

Min length: 1 Max length: 40
subgatewayMerchant.address.street2 Copied to clipboard String CONDITIONAL

The second line of the street address of this merchant's billing address.

Data can consist of any characters

Min length: 1 Max length: 40
subgatewayMerchant.authentication[n] Copied to clipboard CONDITIONAL

Information about the merchant's registration to use a payer authentication protocol.

For example, using 3-D Secure authentication.

subgatewayMerchant.authentication[n].3DS2 Copied to clipboard 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.

subgatewayMerchant.authentication[n].3DS2.requestorId Copied to clipboard 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.

Data can consist of any characters

Min length: 1 Max length: 35
subgatewayMerchant.authentication[n].3DS2.requestorName Copied to clipboard 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.

Data can consist of any characters

Min length: 1 Max length: 40
subgatewayMerchant.authentication[n].acquirerBIN Copied to clipboard 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

Data is a string that consists of the characters 0-9.

Min length: 4 Max length: 11
subgatewayMerchant.authentication[n].protocol Copied to clipboard Enumeration ALWAYS PROVIDED

The protocol used for payer authentication.

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 Copied to clipboard Alphanumeric + additional characters ALWAYS PROVIDED

The identifier you use to uniquely identify this merchant on your system.

Data may consist of the characters 0-9, a-z, A-Z, '_', '-'

Min length: 1 Max length: 36
subgatewayMerchant.name Copied to clipboard 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.

Data can consist of any characters

Min length: 1 Max length: 100
subgatewayMerchant.websiteUrl Copied to clipboard 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.

Ensure that the URL begins with 'https' and is longer than 11 characters.

timeOfLastUpdate Copied to clipboard DateTime CONDITIONAL

Indicates the date and time the gateway considers the transaction to have last been updated.

An instant in time expressed in ISO8601 date + time format - "YYYY-MM-DDThh:mm:ss.SSSZ"

timeOfRecord Copied to clipboard 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.

An instant in time expressed in ISO8601 date + time format - "YYYY-MM-DDThh:mm:ss.SSSZ"

transaction Copied to clipboard ALWAYS PROVIDED

Information about this transaction.

transaction.amount Copied to clipboard Decimal ALWAYS PROVIDED

The total amount for the transaction.

Data is a decimal number.

Max value: 1000000000000 Min value: 0 Max post-decimal digits: 3
transaction.authenticationStatus Copied to clipboard Enumeration CONDITIONAL

Indicates the result of payer authentication.

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 Copied to clipboard Upper case alphabetic text ALWAYS PROVIDED

The currency of the transaction expressed as an ISO 4217 alpha code, e.g. USD.

Data must consist of the characters A-Z

Min length: 3 Max length: 3
transaction.id Copied to clipboard 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.

Data can consist of any characters

Min length: 1 Max length: 40
transaction.reference Copied to clipboard String CONDITIONAL

An optional identifier for this transaction.

Data can consist of any characters

Min length: 1 Max length: 40
transaction.type Copied to clipboard Enumeration ALWAYS PROVIDED

Indicates the type of action performed on the order.

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 Copied to clipboard String CONDITIONAL

The Web Services API version that you submitted the request in.

Data can consist of any characters

Min length: 1 Max length: 8

Errors Copied to clipboard

error Copied to clipboard

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

error.cause Copied to clipboard Enumeration

Broadly categorizes the cause of the error.

For example, errors may occur due to invalid requests or internal system failures.

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 Copied to clipboard String

Textual description of the error based on the cause.

This field is returned only if the cause is INVALID_REQUEST or SERVER_BUSY.

Data can consist of any characters

Min length: 1 Max length: 1000
error.field Copied to clipboard String

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.

Data can consist of any characters

Min length: 1 Max length: 100
error.supportCode Copied to clipboard String

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.

Data can consist of any characters

Min length: 1 Max length: 100
error.validationType Copied to clipboard Enumeration

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.

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 Copied to clipboard Enumeration

A system-generated high level overall result of the operation.

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.