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://api/rest/version/100 / 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.methodNotificationUrl Copied to clipboard Url OPTIONAL

The URL to which the gateway will send the 3DS Method completion notification.

You only need to provide this value if you want to be notified on completion of the 3DS Method call.

If you do not specify a value, and if Method URL is supported for the transaction, then the gateway will handle the Method completion on behalf of you.

Ensure that this is a valid URL according to RFC 1738.

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.
  • • If you set this value to AGREEMENT_CANCELLATION, you must provide the agreement.id and order.amount for which the agreement was registered in the AUTHENTICATE_PAYER request.

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.

AGREEMENT_CANCELLATION

Authentication performed before cancelling the agreement.

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

The code that represents a partnership agreement, between you and the issuer.

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

Min length: 1 Max length: 6
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.governmentCountryCode Copied to clipboard Upper case alphabetic text OPTIONAL

Only provide this field if the sub merchant is a government owned or controlled merchant.

A sub merchant is considered a government owned or controlled entity (government controlled merchant) if 50% or more of the sub merchant is owned by the government. Provide the ISO 3166 three-letter country code of the government country where this differs from the sub merchant's physical location country.

Data must consist of the characters A-Z

Min length: 3 Max length: 3
order.subMerchant.identifier Copied to clipboard Alphanumeric + additional characters REQUIRED

Your identifier for the sub-merchant.

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

Data may consist of the characters 0-9, a-z, A-Z, '-', '_', ' ', '&', '+', '!', '$', '.'

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

If the sub merchant is a marketplace, provide the marketplace ID assigned to them by Visa.

A sub merchant is considered a marketplace if they operate a platform (online commerce website or mobile application) where retailers can sell goods and services.

Data can consist of any characters

Min length: 1 Max length: 11
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 this is a valid URL according to RFC 1738.

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 this is a valid URL according to RFC 1738.

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
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 this is a valid URL according to RFC 1738.

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

Use this parameter group when transaction service location is different than your registered business location.

transaction.serviceLocation.city Copied to clipboard String OPTIONAL

The city where cardholder received the service.

Data can consist of any characters

Min length: 1 Max length: 100
transaction.serviceLocation.country Copied to clipboard Upper case alphabetic text OPTIONAL

The country where cardholder received the service.

Data must consist of the characters A-Z

Min length: 3 Max length: 3
transaction.serviceLocation.postCodeZip Copied to clipboard Alphanumeric + additional characters OPTIONAL

The zip or postal code where cardholder received the service.

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

Min length: 1 Max length: 10
transaction.serviceLocation.stateProvinceCode Copied to clipboard String OPTIONAL

The state or province where cardholder received the service.

The value must match the second part of the ISO 3166-2 code. For an address in the United States provide the 2-letter ISO 3166-2 state code. For US military bases provide one of AE, AA, AP. For an address in Canada provide the 2-letter ISO 3166-2 province code.

Data can consist of any characters

Min length: 1 Max length: 3

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

The EMV 3DS authentication scheme that was used to process the authentication request.You must provide this field for co-branded card transactions that were authenticated outside MPGS using an external 3DS provider.

For example, for externally authenticated Mada co-branded transactions, you must provide either MADA, MASTERCARD or VISA to specify the 3DS directory server.

Data can consist of any characters

Min length: 2 Max length: 50
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.
  • • If you set this value to AGREEMENT_CANCELLATION, you must provide the agreement.id and order.amount for which the agreement was registered in the AUTHENTICATE_PAYER request.

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.

AGREEMENT_CANCELLATION

Authentication performed before cancelling the agreement.

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

Information you can use to optimize and initiate the user experience for payer authentication.

Put the HTML returned in field authentication.redirect.html in your payment page.

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

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

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

authentication.redirect.customizedHtml Copied to clipboard CONDITIONAL

If, instead of simply using authentication.redirect.html, you want to create the required user experience yourself, you can customize it using the parameters provided in this group.

See EMVCo specification for details about how to use the fields provided in this parameter group.

authentication.redirect.customizedHtml.3ds2 Copied to clipboard CONDITIONAL

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

authentication.redirect.customizedHtml.3ds2.methodPostData Copied to clipboard Base64 CONDITIONAL

Base64 URL encoded frame contents to be posted to the URL provided in authentication.redirect.customizedHtml.3ds2.methodUrl.

This is used by the issuer's Access Control Server (ACS) to obtain additional information about the payer's browser to assist their risk assessment process. This information will only be provided by the gateway if the payer's browser is present (authentication.channel=PAYER_BROWSER) and the issuer's Access Control Server (ACS) supports a method call.

Data is Base64 encoded

Min length: 3 Max length: 1000
authentication.redirect.customizedHtml.3ds2.methodUrl Copied to clipboard Url CONDITIONAL

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

This information will only be provided by the gateway if the payer's browser is present (authentication.channel=PAYER_BROWSER) and the issuer's Access Control Server (ACS) supports a method call.

Ensure that this is a valid URL according to RFC 1738.

authentication.redirect.html Copied to clipboard String CONDITIONAL

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

This will execute the required next step in the payer authentication flow.

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

The code that represents a partnership agreement, between you and the issuer.

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

Min length: 1 Max length: 6
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 this is a valid URL according to RFC 1738.

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

Only provide this field if the sub merchant is a government owned or controlled merchant.

A sub merchant is considered a government owned or controlled entity (government controlled merchant) if 50% or more of the sub merchant is owned by the government. Provide the ISO 3166 three-letter country code of the government country where this differs from the sub merchant's physical location country.

Data must consist of the characters A-Z

Min length: 3 Max length: 3
order.subMerchant.identifier Copied to clipboard Alphanumeric + additional characters ALWAYS PROVIDED

Your identifier for the sub-merchant.

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

Data may consist of the characters 0-9, a-z, A-Z, '-', '_', ' ', '&', '+', '!', '$', '.'

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

If the sub merchant is a marketplace, provide the marketplace ID assigned to them by Visa.

A sub merchant is considered a marketplace if they operate a platform (online commerce website or mobile application) where retailers can sell goods and services.

Data can consist of any characters

Min length: 1 Max length: 11
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 this is a valid URL according to RFC 1738.

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

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

response.accountUpdater.gatewayCode Copied to clipboard Enumeration CONDITIONAL

Code generated by the gateway that indicates if the card details were updated by Account Updater before the transaction was submitted to the acquirer for processing.

If response.accountUpdater.gatewayCode=UPDATED, invoke the Retrieve Token request to check if a replacement token has been generated. This step is not required to be completed immediately.
The gateway assigns a replacement token, if your token repository is configured with the 'UNIQUE_ACCOUNT_IDENTIFIER' token management strategy and the repository already contains a token for the new card that was updated by the Account Updater.
For more details see Gateway Tokenization

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

NOT_UPDATED

The card details were not updated.

UPDATED

The card details were updated and these details were used to process the transaction request and are contained in the sourceOfFunds parameter group. The token contained in the request has also been updated with these details.

response.debugInformation 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

Provides a recommendation for your next action based on the outcome of this transaction.

The recommendation may advise you that you:

  • can proceed as planned.
  • must not proceed. For example, because there is suspected fraud.
  • can take action to obtain a successful Authorization. For example, by authenticating the payer, or asking the payer for updated or new payment details.
  • must make a review decision.

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

DO_NOT_PROCEED

Do not proceed using this card. This will be presented if the gateway fails the request, but there is no apparent way for this transaction to succeed.

PROCEED

Proceed with the next step in processing this payment. If the Initiate Authentication response indicated that payer authentication is available, proceed with authenticating the payer using the Authenticate Payer operation. If the Authenticate Payer operation indicates that the payer is sufficiently authenticated, proceed with submitting an Authorize or Pay request. If the Authorization for the payment was successful proceed with capturing the funds and if applicable, ship the goods.

RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS

Ask the payer for alternative payment details (e.g. a new card or another payment method) and resubmit the request with the new details. Do not resubmit the same request.

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

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

sourceOfFunds.provided.epsUeberweisung.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.epsUeberweisung.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: 0 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.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.klarnaPayLater Copied to clipboard CONDITIONAL

Additional details related to a Klarna Pay Later payment.

sourceOfFunds.provided.klarnaPayLater.bankAccountCountryCode Copied to clipboard Upper case alphabetic text ALWAYS PROVIDED

The country where the payer has their bank account.

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

Data must consist of the characters A-Z

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

Additional details related to a PayU browser payment.

sourceOfFunds.provided.payU.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.payU.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: 0 Max length: 255
sourceOfFunds.provided.paysafecard Copied to clipboard CONDITIONAL

Additional details related to a paysafecard browser payment.

sourceOfFunds.provided.paysafecard.accountEmail Copied to clipboard Email ALWAYS PROVIDED

The mypaysafecard account email identifying the mypaysafecard account that will be refunded.

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

sourceOfFunds.provided.paysafecard.countryCode 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.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.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.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.

CARD

Use this value for authentications using the card number.

POLI

The payer selected the payment method POLi.

SCHEME_TOKEN

Use this value for authentications using scheme tokens.

SOFORT

The payer selected the payment method Sofortbanking.

UNION_PAY

The payer selected the payment method UnionPay.

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 this is a valid URL according to RFC 1738.

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

Use this parameter group when transaction service location is different than your registered business location.

transaction.serviceLocation.city Copied to clipboard String CONDITIONAL

The city where cardholder received the service.

Data can consist of any characters

Min length: 1 Max length: 100
transaction.serviceLocation.country Copied to clipboard Upper case alphabetic text CONDITIONAL

The country where cardholder received the service.

Data must consist of the characters A-Z

Min length: 3 Max length: 3
transaction.serviceLocation.postCodeZip Copied to clipboard Alphanumeric + additional characters CONDITIONAL

The zip or postal code where cardholder received the service.

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

Min length: 1 Max length: 10
transaction.serviceLocation.stateProvinceCode Copied to clipboard String CONDITIONAL

The state or province where cardholder received the service.

The value must match the second part of the ISO 3166-2 code. For an address in the United States provide the 2-letter ISO 3166-2 state code. For US military bases provide one of AE, AA, AP. For an address in Canada provide the 2-letter ISO 3166-2 province code.

Data can consist of any characters

Min length: 1 Max length: 3
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.