Mastercard Payment Gateway API Reference: Operations -
Version 69,
Protocol: REST-JSON

Authenticate Payer

Request to authenticate a payer, i.e. verify the identity of a cardholder. You can subsequently use the resulting authentication data when submitting a financial transaction request to prove that you have performed payer authentication.

You must first invoke the Initiate Authentication operation and where the response indicates that payer authentication is available, you must then invoke the Authenticate Payer operation with the same orderId and transactionId submitted on the Initiate Authentication operation.

To increase the likelihood of the authentication being successful, provide as much information about the payer and the transaction as possible.

If the information in the request is sufficient to allow the authentication scheme to confirm the payer's identity the response will include the authentication data (frictionless flow). Alternatively (challenge flow), it may be necessary for the payer to interact with the authentication scheme to confirm their identity (e.g. by providing a one-time password sent to them by their card issuer). In this case the response will contain an HTML excerpt that you must inject into your page. This will establish the interaction between the payer and the authentication scheme. After authentication has been completed the payer will be redirected back to your website using the URL provided by you in field authentication.redirectResponseUrl in the Authenticate Payer request.

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.

Usage Note

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

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

URL https://na.gateway.mastercard.com/api/rest/version/69/merchant/{merchantId}/order/{orderid}/transaction/{transactionid}
HTTP Method PUT
Authentication 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 Parameters

apiOperation  String =AUTHENTICATE_PAYER FIXED

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

order   = COMPULSORY

Information about the order associated with this transaction.
Fixed value

order.amount  Decimal = OPTIONAL

The total amount for the order.  This is the net amount plus any merchant charge amounts.If you provide any sub-total amounts, then the sum of these amounts (order.itemAmount, order.taxAmount, order.shippingAndHandlingAmount, order.cashbackAmount, order.gratuityAmount, order.merchantCharge.amount and order.dutyAmount), minus the order.discountAmount must equal the net amount.
The value of this field in the response is zero if payer funds are not transferred.
Existence
OPTIONAL
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9 and '.' and represents a valid decimal number.
JSON type
String
minimum length
1
maximum length
14

order.currency  Upper case alphabetic text = COMPULSORY

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

session.id  ASCII Text = OPTIONAL

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

accountFunding   = OPTIONAL

Additional details for account funding transactions (order.purchaseType=ACCOUNT_FUNDING).
Account funding transactions are transactions that pull money from the sender's card account for the purpose of funding another account, the recipient's account. Depending on the type of account funding transaction you may be required to provide some or all the details in this parameter group.
Fixed value

accountFunding.purpose  Enumeration = OPTIONAL

Defines the purpose of the account funding payment.If not provided the value is defaulted to OTHER.
Existence
OPTIONAL
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
CRYPTOCURRENCY_PURCHASE
The funds from this account funding transaction will be used to purchase cryptocurrency.
MERCHANT_SETTLEMENT
The funds from this account funding transaction will be used to settle the proceeds of processing card transactions.
OTHER
The funds from this account funding transaction will be used for any other purpose, e.g. transferring funds from a person to a person or transferring funds into a staged wallet.This is the default value.
PAYROLL
The funds from this account funding transaction will be used to pay salaries.

accountFunding.recipient   = OPTIONAL

Details about the recipient who will subsequently receive the funds that you are debiting from the sender in this transaction.
Fixed value

accountFunding.recipient.country  Upper case alphabetic text = OPTIONAL

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

accountFunding.recipient.dateOfBirth  Date = OPTIONAL

The date of birth of the recipient in yyyy-mm-dd format.
Existence
OPTIONAL
Fixed value
Validation Rules
Data must comply with ISO 8601 extended date format, yyyy-mm-dd
JSON type
String

accountFunding.recipient.firstName  String = OPTIONAL

First name of the recipient.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
50

accountFunding.recipient.lastName  String = OPTIONAL

Last name of the recipient.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
50

accountFunding.recipient.postCodeZip  String = OPTIONAL

The post code or zip code of the recipient.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
10

accountFunding.recipient.stateProvinceCode  String = OPTIONAL

The state or province code of the recipient.
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.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
3

accountFunding.senderIsRecipient  Boolean = OPTIONAL

Defines if the sender and recipient of the account funding payment are the same or not.
If not provided the value is defaulted to FALSE.
Existence
OPTIONAL
Fixed value
Validation Rules
JSON boolean values 'true' or 'false'.
JSON type
Boolean

accountFunding.senderType  Enumeration = OPTIONAL

Defines if the sender is a person, a commercial organization, a non-profit organization or a government
Existence
OPTIONAL
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
COMMERCIAL_ORGANIZATION
The sender is a commercial organization. Examples include account to account transfers initiated by a commercial organization for the purpose of transferring funds to one of their accounts, business to business payments, and disbursements for insurance claims, payroll, investment dividends, merchant rebates.
GOVERNMENT
The sender is a government or government agency. Examples include government agencies paying salaries, pensions, social benefits or tax credits.
NON_PROFIT_ORGANIZATION
The sender is a non-profit organization. Examples include non-profit organizations delivering emergency aid payments.
PERSON
The sender is a person. Examples include account to account transfers initiated by a person to their own account or a different person's account and adding funds to a staged wallet.

agreement   = OPTIONAL

A commercial agreement you have with the payer that allows you to store and use their payment details for later payments.
For example, an agreement to a series of recurring payments (a mobile phone subscription), an agreement to take payment for a purchase by a series of installments (hire purchase), an agreement to make additional payments when required (account top up), or to fulfil a standard industry practice (no show penalty charge).

Do not provide this parameter group if you are storing the payment details for subsequent payer-initiated payments only.

See Credential on File, Cardholder, and Merchant Initiated Transactions for details.
Fixed value

agreement.amountVariability  Enumeration = OPTIONAL

Indicates if all the payments within the agreement use the same amount or if the amount differs between the payments.
The field must be provided for recurring payment agreements.
Existence
OPTIONAL
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
FIXED
All payments in the recurring payment agreement have the same amount. Examples include magazine subscriptions or gym memberships.
VARIABLE
The amount for the payments within the recurring payment agreement differs between payments. Examples include usage-based charges like utility or phone bills.

agreement.expiryDate  Date = OPTIONAL

Date at which your agreement with the payer to process payments expires.
Existence
OPTIONAL
Fixed value
Validation Rules
Data must comply with ISO 8601 extended date format, yyyy-mm-dd
JSON type
String

agreement.id  String = OPTIONAL

Your identifier for the agreement you have with the payer to process payments.
When you collect cards from your payers and store them for later use, you must provide an agreement ID when you use the stored values for:

  • Recurring payments: you have an agreement with the payer that authorizes you to automatically debit their account at agreed intervals for fixed or variable amounts. For example, gym membership, phone bills, or magazine subscriptions.
  • Installment payments: you have an agreement with the payer that authorizes you to process multiple payments over an agreed period of time for a single purchase. For example, the payer purchases an item for $1000 and pays for it in four monthly installments.
  • Unscheduled: you have an agreement with the payer that authorizes you to process future payments when required. For example, the payer authorizes you to process an account top-up transaction for a transit card when the account balance drops below a certain threshold.
  • Industry Practice: you have an agreement with the payer that authorizes you to initiate additional transactions to fulfil a standard business practice related to an original payment initiated by the payer. For example, a delayed charge for use of the hotel mini bar after the payer has checked out or a no show penalty charge when the payer fails to show for a booking.
When you first establish an agreement with the payer you should also specify the type of agreement in agreement.type.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
100

agreement.maximumAmountPerPayment  Decimal = OPTIONAL

The maximum amount for a single payment in the series as agreed with the payer under your agreement with them.
The amount must be provided in the currency of the order.
Existence
OPTIONAL
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9 and '.' and represents a valid decimal number.
JSON type
String
minimum length
1
maximum length
14

agreement.minimumDaysBetweenPayments  Integer = OPTIONAL

The minimum number of days between payments agreed with the payer under your agreement with them.
Existence
OPTIONAL
Fixed value
Validation Rules
JSON number data type, restricted to being positive or zero. In addition, the represented number may have no fractional part.
JSON type
Number
minimum value
1
maximum value
9999

agreement.numberOfPayments  Integer = OPTIONAL

The number of merchant-initiated payments within the recurring payment agreement.
Existence
OPTIONAL
Fixed value
Validation Rules
JSON number data type, restricted to being positive or zero. In addition, the represented number may have no fractional part.
JSON type
Number
minimum value
1
maximum value
999

agreement.paymentFrequency  Enumeration = OPTIONAL

The frequency of the payments within the series as agreed with the payer under your agreement with them.
Existence
OPTIONAL
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
AD_HOC
The agreement if for payments on an ah-hoc basis.
DAILY
The agreement if for a daily payment.
FORTNIGHTLY
The agreement if for a fortnightly payment.
MONTHLY
The agreement if for a monthly payment.
OTHER
The agreement is for payments according to a schedule other than the ones listed in the other enumeration values for this field.
QUARTERLY
The agreement if for a quarterly payment.
TWICE_YEARLY
The agreement if for a payment twice a year.
WEEKLY
The agreement if for a weekly payment.
YEARLY
The agreement if for a yearly payment.

agreement.type  Enumeration = OPTIONAL

The type of commercial agreement that the payer has with you.
Specify the agreement type when you have provided a value for agreement.id and this payment is the first in a series of payments. The default value is OTHER.

The gateway will use the value you specify for subsequent payments in the series.
Existence
OPTIONAL
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
INDUSTRY_PRACTICE
An agreement where the payer authorizes you to initiate additional transactions to fulfil a standard business practice related to an original payment initiated by the payer. These additional payments are triggered by an event not known at the time of the payer's initial agreement. For example, a delayed charge for use of the hotel mini bar after the payer has checked out or a no show charge when the payer fails to show for a booking.
INSTALLMENT
An agreement where the payer authorizes the payment for a single purchase to be split into a number of payments processed at agreed intervals. For example, pay for a purchase in six monthly installments.
OTHER
An agreement where you want to link related payments for any purpose other than processing recurring, installment, or unscheduled payments. For example, split tender payments.
RECURRING
An agreement where the payer authorizes you to process repeat payments for bills or invoices at agreed intervals (for example, weekly, monthly). The amount might be fixed or variable.
UNSCHEDULED
An agreement where the payer authorizes you to automatically deduct funds for a payment for an agreed purchase when required (unscheduled). For example, auto top-ups when the account value falls below a threshold.

apiOperation  String =AUTHENTICATE_PAYER FIXED

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

authentication   = OPTIONAL

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

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

authentication.3ds2   = OPTIONAL

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

authentication.3ds2.sdk   = OPTIONAL

Information provided by the 3-D Secure Software Development Kit (SDK) that is used by an app on the payer's device to enable 3-D Secure authentication of the payer to be performed in-app.
You must populate the fields in this parameter group when you authenticate the payer in-app using 3-D Secure authentication version 2.
Fixed value

authentication.3ds2.sdk.appId  String = COMPULSORY

A unique identifier for the app on the payer's device.
The 3-D Secure SDK generates this identifier each time the app is installed or updated.

This field corresponds to EMVCo field sdkAppID
Existence
COMPULSORY
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
36
maximum length
36

authentication.3ds2.sdk.encryptedData  String = COMPULSORY

Information about the payer's device collected and encrypted by the 3-D Secure SDK.
The data is a JSON Web Encryption (JWE) object in JSON format. When using the REST/JSON gateway API, express this as a JSON string (i.e. the embedded quotes will be escaped).

This field corresponds to EMVCo field sdkEncData
Existence
COMPULSORY
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
0
maximum length
64000

authentication.3ds2.sdk.ephemeralPublicKey  JSON Text = COMPULSORY

A public key generated by the 3-D Secure SDK.
This key is used to establish a secure session between the 3DS SDK and the issuer's Access Control Server (ACS) when the payer is required to be presented with an authentication challenge.

The key is a JSON Web Key (JWK) object in JSON format. When using the REST/JSON gateway API, express this as a JSON string (i.e the embedded quotes will be escaped).

This field corresponds to EMVCo field sdkEphemPubKey
Existence
COMPULSORY
Fixed value
Validation Rules
Data is valid Json Format
JSON type
String
minimum length
0
maximum length
256

authentication.3ds2.sdk.interface  Enumeration = OPTIONAL

The User Interface (UI) formats that the payer's device supports.
These are the formats that can be used to render the screens presented to the payer during an authentication challenge.

You only need to provide this value if you only support one of these formats.

This field corresponds to EMVCo data element sdkInterface in the field deviceRenderOptions.
Existence
OPTIONAL
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
HTML
The device supports HTML format.
NATIVE
The device supports the UI format native to the payer's device.

authentication.3ds2.sdk.referenceNumber  String = COMPULSORY

An identifier of the vendor and version of the 3-D Secure SDK assigned by EMVCo.
This field corresponds to EMVCo field sdkReferenceNumber
Existence
COMPULSORY
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
32

authentication.3ds2.sdk.timeout  Integer = OPTIONAL

The duration (in seconds) available to the payer to authenticate.
Will default to 900 if not provided. Note: The value will be rounded up to the nearest minute.

This field corresponds to EMVCo field sdkMaxTimeout
Existence
OPTIONAL
Fixed value
Validation Rules
JSON number data type, restricted to being positive or zero. In addition, the represented number may have no fractional part.
JSON type
Number
minimum value
300
maximum value
900

authentication.3ds2.sdk.transactionId  String = COMPULSORY

A unique identifier assigned by the 3-D Secure SDK for the transaction.
This field corresponds to EMVCo field sdkTransID
Existence
COMPULSORY
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
36
maximum length
36

authentication.3ds2.sdk.uiType  Comma separated enumeration = OPTIONAL

Indicates the UI types which the SDK supports for displaying authentication challenges within the app.
A comma separated list of the payer authentication methods that you will accept for this payment.

You only need to provide this value if all of these values are not supported.

Note: OTHER_HTML is only supported when authentication.3ds2.sdk.interface allows a HTML UI format.

This field corresponds to EMVCo data element sdkUiType in the field deviceRenderOptions.
Existence
OPTIONAL
Fixed value
Validation Rules
Indicates the UI types which the SDK supports for displaying authentication challenges within the app.
JSON type
String
Value must be one or more comma separated members of the following list. The values are case sensitive.
TEXT
The payer is asked to enter text into a field displayed on the UI. For example, ask the payer to enter a One Time Password sent to their registered mobile phone number.
SINGLE_SELECT
The payer is asked to select a single option from a number of presented options. For example, ask the payer if they want a One Time Password to be sent to either their email address or mobile phone number registered with their issuer.
MULTI_SELECT
The payer is asked to select multiple options from a number of presented options. For example, ask the payer to select valid responses to a question.
OUT_OF_BAND
The payer is presented with screens rendered by an out-of-band service during an authentication challenge, For example, the payer is asked to confirm the payment from their banking app.
OTHER_HTML
The payer is presented with an authentication challenge using other mechanisms supported in HTML but not in the native UI format. For example, the payer is asked to confirm an image presented on the screen.

authentication.challengePreference  Enumeration = OPTIONAL

Indicates if you want the payer to be presented with an authentication challenge for this transaction.
You can use this to support local mandates or your risk tolerance. For example, you may prefer that a challenge is always performed when you store card details on file.

If you do not provide a value, the gateway will use NO_PREFERENCE. If there is no payer present (for example, recurring payments), then the gateway will ignore this field and use NO_CHALLENGE.

Note: 'challenge' means requiring the payer to take action to identify themselves, for example, entering a password.
Existence
OPTIONAL
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
CHALLENGE_MANDATED
The merchant requires that the payer is presented with an authentication challenge.
CHALLENGE_PREFERRED
The merchant prefers that the payer is presented with an authentication challenge.
NO_CHALLENGE
The merchant prefers that the payer is not presented with an authentication challenge.
NO_PREFERENCE
The issuer determines whether or not the payer should be presented with an authentication challenge. The merchant does not have a preference.
REQUEST_WHITELISTING
Tells the issuer that you prefer them to present the payer with a challenge and that you want them to invite the payer to add you to their list of trusted merchants. If the payer whitelists you, they can skip authentication for any future payments. You will be able to tell whether the payer has added you to their list of trusted merchants by looking at authentication.psd2.whitelistStatus in the authentication response following the completion of the challenge.

authentication.goodsDescription  String = OPTIONAL

Description of the goods being purchased.
If supported, this description will be displayed on the authentication UI presented to the payer.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
0
maximum length
30

authentication.psd2   = OPTIONAL

This parameter group is only applicable if you are subject to the Regulatory Technical Standards (RTS) requirements for Strong Customer Authentication (SCA) under the Payment Services Directive 2 (PSD2) regulations in the European Economic Area.
It provides details about SCA exemptions under PSD2.
Fixed value

authentication.psd2.exemption  Enumeration = OPTIONAL

Indicates if you believe this payment to be exempt or excluded from the Strong Customer Authentication (SCA) requirement.
Note:
  • For recurring payments, provide the MERCHANT_INITIATED_TRANSACTION value only if the amount is the same. If the amount is variable, provide RECURRING_PAYMENT instead.
Existence
OPTIONAL
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
AUTO
If either a LOW_RISK or LOW_VALUE_PAYMENT exemption applies to the transaction, it is automatically claimed by the gateway on behalf of the merchant.
LOW_RISK
Exemption is claimed because the acquirer has a low fraud rate.
LOW_VALUE_PAYMENT
Exemption is claimed as the amount is below 30 Euro.
MERCHANT_INITIATED_TRANSACTION
The transaction is excluded as it was initiated by the merchant based on an agreement with the payer. For example, a recurring payment (for a fixed amount), installment payment, or account top-up. In these cases, the payer is not present and cannot participate in an authentication interaction. Merchant initiated transactions are only applicable to subsequent transactions on the order and are out of scope of the PSD2 RTS on Strong Customer Authentication (SCA). The payer must be authenticated during the first transaction that established the agreement.
NONE
An exemption is not claimed for this transaction. The merchant requires Strong Customer Authentication (SCA) be performed.
RECURRING_PAYMENT
The transaction is exempt as it was initiated by the merchant based on an agreement with the payer for a recurring payment for a variable amount. This value is only applicable to subsequent transactions on the order. In this case, the payer is not present and cannot participate in an authentication interaction. The payer must be authenticated during the first transaction that established the agreement.
SECURE_CORPORATE_PAYMENT
The transaction is exempt as it is a corporate or Business-to-Business (B2B) payment performed using dedicated payment processes and protocols that are not available to consumers and offer at least equivalent security levels.
WHITELISTED_MERCHANT
The transaction is exempt because the payer has added you to the list of their trusted merchants (as maintained by the issuer).

authentication.redirectResponseUrl  Url = OPTIONAL

The URL to which you want to redirect the payer after completing the payer authentication process.
This will be a URL on your website, with the URL encoded as defined in RFC3986. This means special characters such spaces, hyphens, etc must be encoded.

You must provide this URL, unless you are certain that there will be no interaction with the payer.
Existence
OPTIONAL
Fixed value
Validation Rules
Ensure that the URL begins with 'https' and is longer than 11 characters.
JSON type
String

billing   = OPTIONAL

Details of the payer's billing address.
Fixed value

billing.address   = OPTIONAL

The payer's billing address.
This data may be used to qualify for better interchange rates on corporate purchase card transactions.
Fixed value

billing.address.city  String = OPTIONAL

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

billing.address.company  String = OPTIONAL

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

billing.address.country  Upper case alphabetic text = OPTIONAL

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

billing.address.postcodeZip  Alphanumeric + additional characters = OPTIONAL

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

billing.address.stateProvince  String = OPTIONAL

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

billing.address.stateProvinceCode  String = OPTIONAL

The three character ISO 3166-2 country subdivision code for the state or province of the address.
Providing this field might improve your payer experience for 3-D Secure payer authentication.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
3

billing.address.street  String = OPTIONAL

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

billing.address.street2  String = OPTIONAL

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

correlationId  String = OPTIONAL

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

customer   = OPTIONAL

Information associated with the customer's account.
Fixed value

customer.email  Email = OPTIONAL

The email address of the customer.
The field format restriction ensures that the email address is longer than 3 characters and adheres to a generous subset of valid RFC 2822 email addresses.
Existence
OPTIONAL
Fixed value
Validation Rules
Ensures that the email address is longer than 3 characters and adheres to a generous subset of valid RFC 2822 email addresses
JSON type
String

customer.firstName  String = OPTIONAL

The payer's first name.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
50

customer.lastName  String = OPTIONAL

The payer's last or surname.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
50

customer.mobilePhone  Telephone Number = OPTIONAL

The payer's mobile phone or cell phone number in ITU-T E123 format, for example +1 607 1234 5678

The number consists of:
  • ‘+’
  • country code (1, 2 or 3 digits)
  • ‘space’
  • national number ( which may embed single spaces characters for readability).
Existence
OPTIONAL
Fixed value
Validation Rules
Data consists of '+', country code (1, 2 or 3 digits), 'space', and national number (which may embed single space characters for readability)
JSON type
String
mandatory country code
true
maximum total digits
15

customer.phone  Telephone Number = OPTIONAL

The payer's phone number in ITU-T E123 format, for example +1 607 1234 456

The number consists of:
  • ‘+’
  • country code (1, 2 or 3 digits)
  • ‘space’
  • national number ( which may embed single spaces characters for readability).
Existence
OPTIONAL
Fixed value
Validation Rules
Data consists of '+', country code (1, 2 or 3 digits), 'space', and national number (which may embed single space characters for readability)
JSON type
String
mandatory country code
true
maximum total digits
15

customer.taxRegistrationId  String = OPTIONAL

The tax registration identifier of the customer.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
30

device   = OPTIONAL

Information about the device used by the payer for this transaction.
Fixed value

device.ani  String = OPTIONAL

The telephone number captured by ANI (Automatic Number Identification) when the customer calls to place the order.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
10

device.aniCallType  String = OPTIONAL

The 2 digit ANI information identifier provided by the telephone company to indicate the call type, for example, cellular (61-63), toll free (24,25), etc.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
2

device.browser  String = OPTIONAL

The User-Agent header of the browser the customer used to place the order.For example, MOZILLA/4.0 (COMPATIBLE; MSIE 5.0; WINDOWS 95)

You must provide a value in this field if you are performing 3-D Secure authentication of the payer and set authentication.channel = PAYER_BROWSER.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
255

device.browserDetails   = OPTIONAL

Detailed information about the payer's browser.
If you are using 3-D Secure authentication to authenticate the payer, then this information is used by the issuer's Access Control Server (ACS) to identify the capabilities of the payers browser so that it can render content appropriately when authenticating the payer.

You must provide values for fields in this parameter group if you are performing 3-D Secure authentication of the payer and set authentication.channel = PAYER_BROWSER.
Fixed value

device.browserDetails.3DSecureChallengeWindowSize  Enumeration = OPTIONAL

Dimensions of the challenge window (in width x height in pixels) displayed to the payer during 3D-Secure authentication.
This must be provided for authentication operations where authentication.channel is PAYER_BROWSER.
Existence
OPTIONAL
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
250_X_400
390_X_400
500_X_600
600_X_400
FULL_SCREEN

device.browserDetails.acceptHeaders  String = OPTIONAL

The content of the Accept request-header field as sent from the payer's browser.
This is used to determine which content types are supported by the browser.

This must be provided for authentication operations where authentication.channel is PAYER_BROWSER.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
2048

device.browserDetails.colorDepth  Integer = OPTIONAL

The bit depth (in bits per pixel) of the color palette for displaying images.
You obtain this value from the screen.colorDepth property of the payer's browser.

This must be provided for authentication operations where authentication.channel is PAYER_BROWSER.
Existence
OPTIONAL
Fixed value
Validation Rules
JSON number data type, restricted to being positive or zero. In addition, the represented number may have no fractional part.
JSON type
Number
minimum value
1
maximum value
48

device.browserDetails.javaEnabled  Boolean = OPTIONAL

Indicates whether or not the payer's browser supports Java.
You obtain this value from the navigator.javaEnabled property of the payer's browser

This must be provided for authentication operations where authentication.channel is PAYER_BROWSER.
Existence
OPTIONAL
Fixed value
Validation Rules
JSON boolean values 'true' or 'false'.
JSON type
Boolean

device.browserDetails.javaScriptEnabled  Boolean = OPTIONAL

Indicates whether or not the payer's browser supports JavaScript.
You can determine this by setting the relevant value in a form to false, and then attempting to update it to true using JavaScript.
Existence
OPTIONAL
Fixed value
Validation Rules
JSON boolean values 'true' or 'false'.
JSON type
Boolean

device.browserDetails.language  String = OPTIONAL

The language supported for the payer's browser as defined in IETF BCP47.
You obtain this value from the navigator.language property of the payer's browser.

This must be provided for authentication operations where authentication.channel is PAYER_BROWSER.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
8

device.browserDetails.screenHeight  Integer = OPTIONAL

The total height of the payer's browser screen in pixels.
You obtain this value from the screen.height property of the payer's browser

This must be provided for authentication operations where authentication.channel is PAYER_BROWSER.
Existence
OPTIONAL
Fixed value
Validation Rules
JSON number data type, restricted to being positive or zero. In addition, the represented number may have no fractional part.
JSON type
Number
minimum value
1
maximum value
999999

device.browserDetails.screenWidth  Integer = OPTIONAL

The total width of the payer's browser screen in pixels.
You obtain this value from the screen.width property of the payer's browser

This must be provided for authentication operations where authentication.channel is PAYER_BROWSER.
Existence
OPTIONAL
Fixed value
Validation Rules
JSON number data type, restricted to being positive or zero. In addition, the represented number may have no fractional part.
JSON type
Number
minimum value
1
maximum value
999999

device.browserDetails.timeZone  Browser Time Zone Offset = OPTIONAL

Time difference between UTC time and the Cardholder browser local time, in minutes.
The time zone offset is the difference, in minutes, between UTC and local time. Note that this means that the offset is positive if the local time zone is behind UTC and negative if it is ahead. For example, for time zone UTC+10:00 (Australian Eastern Standard Time, Vladivostok Time, Chamorro Standard Time), -600 would be presented.

This must be provided for authentication operations where authentication.channel is PAYER_BROWSER.
Existence
OPTIONAL
Fixed value
Validation Rules
Browser time zone offset between -840 to +840.
JSON type
String

device.fingerprint  String = OPTIONAL

Information collected about a remote computing device for the purpose of providing a unique identifier for the device.
For example, session ID, blackbox ID.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
4000

device.hostname  String = OPTIONAL

The name of the server to which the customer is connected.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
60

device.ipAddress  String = OPTIONAL

The IP address of the device used by the payer, in nnn.nnn.nnn.nnn format.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
7
maximum length
15

device.mobilePhoneModel  String = OPTIONAL

The mobile phone manufacturer's identifier for the model of the mobile device used to initiate the payment.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
255

order   = COMPULSORY

Information about the order associated with this transaction.
Fixed value

order.acceptPartialAmount  Boolean = OPTIONAL

Indicates whether you will accept a payment less than order.amount, e.g. when using a gift card.
If not set or set to FALSE, and the full amount is not available, the transaction will be rejected.
Unless you have been advised by your payment service provider that the gateway supports partial approvals for your acquirer, you can ignore this field.
If the gateway supports partial approvals for your acquirer you must set this field to TRUE else the transaction is rejected by the gateway.
Existence
OPTIONAL
Fixed value
Validation Rules
JSON boolean values 'true' or 'false'.
JSON type
Boolean

order.amount  Decimal = OPTIONAL

The total amount for the order.  This is the net amount plus any merchant charge amounts.If you provide any sub-total amounts, then the sum of these amounts (order.itemAmount, order.taxAmount, order.shippingAndHandlingAmount, order.cashbackAmount, order.gratuityAmount, order.merchantCharge.amount and order.dutyAmount), minus the order.discountAmount must equal the net amount.
The value of this field in the response is zero if payer funds are not transferred.
Existence
OPTIONAL
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9 and '.' and represents a valid decimal number.
JSON type
String
minimum length
1
maximum length
14

order.certainty  Enumeration = OPTIONAL

Indicates if you expect to capture the full order amount for which you are requesting authorization.
If you do not provide a value for order.certainty the default configured for you by your payment service provider will be used. The value provided in the response shows the value the gateway sent to the acquirer
Existence
OPTIONAL
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
ESTIMATED
The amount authorized is an estimate of the amount that will be captured. It is possible that the amount captured will be less, or might not be captured at all.
FINAL
The full authorized amount is expected to be captured within the mandated time. The order will only be cancelled in exceptional circumstances (for example, the payer cancelled their purchase).

order.currency  Upper case alphabetic text = COMPULSORY

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

order.custom  String = OPTIONAL

Information about this order that is of interest to you.
For example order.custom.X, where 'X' is defined by you and must be less than 100 characters from the set A-Z, a-z, 0-9. For example, order.custom.salesRegion. You can specify up to 50 such fields. They are not sent to acquirers.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
250

order.customerNote  String = OPTIONAL

A note from the payer about this order.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
250

order.customerOrderDate  Date = OPTIONAL

The date the payer placed the order.
Data must comply with ISO 8601 extended date format, yyyy-mm-dd.
Existence
OPTIONAL
Fixed value
Validation Rules
Data must comply with ISO 8601 extended date format, yyyy-mm-dd
JSON type
String

order.customerReference  ASCII Text = OPTIONAL

The payer's own reference for the order.
This reference may assist the payer to identify the order in their system. For example, a purchase order number, project identifier, or cost center.
Existence
OPTIONAL
Fixed value
Validation Rules
Data consists of ASCII characters
JSON type
String
minimum length
0
maximum length
25

order.description  String = OPTIONAL

Short textual description of the contents of the order.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
127

order.discount   = OPTIONAL

Information about a price reduction you have applied to the order.
For example, you may apply discounts for trade, employees, bulk purchase, or a sales promotion.
Fixed value

order.discount.amount  Decimal = OPTIONAL

The total amount of the discount you have applied to the order.
Existence
OPTIONAL
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9 and '.' and represents a valid decimal number.
JSON type
String
minimum length
1
maximum length
14

order.discount.code  String = OPTIONAL

The code you use to identify the reason for the discount.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
40

order.discount.description  String = OPTIONAL

A description of your reason for the discount.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
127

order.dutyAmount  Decimal = OPTIONAL

The duty amount (also known as customs tax, tariff or dues) for the order.
Existence
OPTIONAL
Fixed value
Validation Rules
Data is a decimal number.
JSON type
Number
maximum value
1000000000000
minimum value
0
maximum post-decimal digits
3

order.invoiceNumber  String = OPTIONAL

The invoice number you issued for this order.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
25

order.localTaxRegistrationId  String = OPTIONAL

Your tax registration identifier provided by the Local/State/Province tax authority.
If you are a Canadian merchant, use this field to provide your Tax Registration ID for paying Provincial Sales Tax (PST).
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
25

order.marketplace   = OPTIONAL

Use this parameter group to provide additional information if you are a marketplace.You are considered a marketplace if you operate an electronic commerce website or mobile application that brings together payers and retailers and you are selling the goods or services on behalf of the retailer.In this case, the card schemes may require you to register with them as a marketplace and assign you a Marketplace ID.
You should provide this identifier to your payment service provider so that the gateway can automatically include it in all transaction messages to your acquirer.
Fixed value

order.marketplace.retailerLocation  Enumeration = OPTIONAL

Provide information about the location of the retailers for goods or services included in this order.Where a retailer is located in a country different from your country, they are considered a foreign retailer, otherwise they are considered a domestic retailer.
Existence
OPTIONAL
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
DOMESTIC_ONLY
The order only contains items from domestic retailers.
FOREIGN_AND_DOMESTIC
The order contains items from both foreign and domestic retailers.
FOREIGN_ONLY
The order only contains items from foreign retailers.

order.merchantCharge   = OPTIONAL

Information about additional fees that you are charging the payer for processing the payment for this order, for example, a surcharge.
Fixed value

order.merchantCharge.amount  Decimal = OPTIONAL

The amount of the additional fee that you are charging the payer.
If you provide a charge amount, you must include it in the total amount for the order.
Existence
OPTIONAL
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9 and '.' and represents a valid decimal number.
JSON type
String
minimum length
1
maximum length
14

order.merchantCharge.type  Enumeration = COMPULSORY

The type of the additional fee that you are charging the payer.
Existence
COMPULSORY
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
SURCHARGE
A fee that covers your cost of accepting accepting a payment method.

order.netAmount  Decimal = OPTIONAL

The amount payable for the order before merchant charge amount is applied.
If you specify a net amount the gateway will calculate the merchant charge amount for you based on the charge type (order.merchantCharge.type) provided in the request. Alternatively, you can specify the merchant charge amount (order.merchantCharge.amount) yourself.
Existence
OPTIONAL
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9 and '.' and represents a valid decimal number.
JSON type
String
minimum length
1
maximum length
14

order.owningEntity  String = OPTIONAL

Your identifier for the part of your organization that is responsible for the order.
You might provide this data when you want to track the accountability for the order. For example, store number, sales region, branch, or profit center
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
40

order.purchaseType  Enumeration = OPTIONAL

Indicates the purchase of specific types of goods or services.
You must provide a value if your Merchant Category Code (MCC) is one of the following:

6051 (Quasi Cash – Merchant or Non-Financial Institutions – Foreign Currency, Non-Fiat Currency) and this transaction is for the purchase of cryptocurrency. Set the value to CRYPTOCURRENCY.

6211 (Securities – Brokers/Dealers) and this transaction is for the purchase of high-risk securities. Set the value to HIGH_RISK_SECURITIES.

6012 (Merchandise and Services—Customer Financial Institutions) or 6051 (Non-Financial Institutions – Foreign Currency, Non-Fiat Currency) and this transaction is for debt repayment. Set the value to DEBT_REPAYMENT.

If the transaction pulls money from an account for the purpose of crediting another account you must set purchase type to ACCOUNT_FUNDING.

You may set purchase type to OTHER for any other type of payment.
Existence
OPTIONAL
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
CRYPTOCURRENCY
The transaction is for the purchase of a cryptocurrency.
DEBT_REPAYMENT
You may be required to provide additional details about the debt repayment in the debtRepayment parameter group.
HIGH_RISK_SECURITIES
The transaction is for the purchase of high-risk securities.
OTHER
Use this value if the purchase type for the transaction does not fit in any of the other categories.

order.requestorName  String = OPTIONAL

The name of the person who requested the goods or services.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
100

order.shippingAndHandlingAmount  Decimal = OPTIONAL

The total shipping and handling amount for the order, including taxes on the shipping and/or handling.
Existence
OPTIONAL
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9 and '.' and represents a valid decimal number.
JSON type
String
minimum length
1
maximum length
14

order.shippingAndHandlingTaxAmount  Decimal = OPTIONAL

The tax amount levied on the shipping and handling amount for the order.
This amount is included in the shipping and handling amount provided in field order.shippingAndHandlingAmount.
Existence
OPTIONAL
Fixed value
Validation Rules
Data is a decimal number.
JSON type
Number
maximum value
1000000000000
minimum value
0
maximum post-decimal digits
3

order.shippingAndHandlingTaxRate  Decimal = OPTIONAL

The tax rate applied to the shipping and handling amount for the order to determine the shipping and handling tax amount.
For a tax rate of 2.5% provide 0.025.
Existence
OPTIONAL
Fixed value
Validation Rules
Data is a decimal number.
JSON type
Number
maximum value
1000000000000000000
minimum value
0
maximum post-decimal digits
4

order.statementDescriptor   = OPTIONAL

Contact information provided by you for printing on payer's account statements.
Fixed value

order.statementDescriptor.address   = OPTIONAL

Descriptor address of the merchant.
Fixed value

order.statementDescriptor.address.city  String = OPTIONAL

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

order.statementDescriptor.address.company  String = OPTIONAL

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

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

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

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

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

order.statementDescriptor.address.stateProvince  String = OPTIONAL

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

order.statementDescriptor.address.street  String = OPTIONAL

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

order.statementDescriptor.address.street2  String = OPTIONAL

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

order.statementDescriptor.name  String = OPTIONAL

Descriptor name of the merchant.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
100

order.statementDescriptor.phone  String = OPTIONAL

Descriptor phone number of the merchant's business.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
20

order.supply   = OPTIONAL

Information about orders for items not yet available (pre-order) or for items previously purchased (reorder).
Fixed value

order.supply.preorder  Boolean = OPTIONAL

Indicates that the purchase includes merchandise with a future availability or release date.
Existence
OPTIONAL
Fixed value
Validation Rules
JSON boolean values 'true' or 'false'.
JSON type
Boolean

order.supply.preorderAvailabilityDate  Date = OPTIONAL

The date that preordered items are expected to be available.
Provide this field if the payer is ordering items before you have them available for purchase.
Existence
OPTIONAL
Fixed value
Validation Rules
Data must comply with ISO 8601 extended date format, yyyy-mm-dd
JSON type
String

order.supply.reorder  Boolean = OPTIONAL

Indicates that the purchase includes merchandise that the payer has previously ordered.
Existence
OPTIONAL
Fixed value
Validation Rules
JSON boolean values 'true' or 'false'.
JSON type
Boolean

order.tax[n]   = OPTIONAL

Use this parameter group to provide a breakdown of tax types, amount per tax type, and rate per tax type included in order.taxAmount.
Fixed value

order.tax[n].amount  Decimal = OPTIONAL

The tax amount included in this order for the tax type.
Existence
OPTIONAL
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9 and '.' and represents a valid decimal number.
JSON type
String
minimum length
1
maximum length
14

order.tax[n].rate  Decimal = OPTIONAL

The tax rate (percentage) used to determine the tax amount included in this order for the tax type.
Existence
OPTIONAL
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9 and '.' and represents a valid decimal number.
JSON type
String
minimum length
1
maximum length
6

order.tax[n].type  String = OPTIONAL

The type of tax included in the order amount.
The correct value as used by your acquirer may have to be provided. Contact your payment service provider for details.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
50

order.taxAmount  Decimal = OPTIONAL

The total tax amount for the order.
If you do not provide this value but provide line item data, then this amount is calculated as the sum of the item.quantity times the item.unitTaxAmount for all the line items (total tax amount).
If you provide both this value and line item data, then the order.taxAmount MUST equal the total tax amount.
Existence
OPTIONAL
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9 and '.' and represents a valid decimal number.
JSON type
String
minimum length
1
maximum length
14

order.taxRegistrationId  String = OPTIONAL

Your tax registration identifier provided by the Federal/National tax authority (for example, federal tax identification number, ABN).
If you are a Canadian merchant, use this field to provide your Tax Registration ID for paying Harmonized Sales Tax (HST) or Goods and Services Tax (GST) collected by the Canada Revenue Agency.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
30

order.taxStatus  Enumeration = OPTIONAL

Indicates your tax status for this order.
Existence
OPTIONAL
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
EXEMPT
Indicates that you are exempt from tax.
NOT_EXEMPT
Indicates that you are not exempt from tax.
NOT_PROVIDED
Indicates that you are not providing information about being exempt from tax.

order.transactionFiltering   = OPTIONAL

Information relevant for Transaction Filtering.
Fixed value

order.transactionFiltering.avsResponseCodeRules[n]   = OPTIONAL

Allows you to provide the Address Verification Service (AVS) Response Code Transaction Filtering rules to be applied to the transactions for this order.
If provided, these rules override the AVS Response Code Transaction Filtering rules you have configured in Merchant Administration.
Fixed value

order.transactionFiltering.avsResponseCodeRules[n].action  Enumeration = COMPULSORY

The action to be performed for the Address Verification Service (AVS) Response Code.
Existence
COMPULSORY
Fixed value
Validation Rules
The action to be performed for the Address Verification Service (AVS) Response Code.
JSON type
String
Value must be a member of the following list. The values are case sensitive.
NO_ACTION
No action should be taken by the gateway.
REJECT
The gateway must reject the transaction.
REVIEW
The gateway must mark this transaction as requiring a review.

order.transactionFiltering.avsResponseCodeRules[n].avsResponseCode  Enumeration = COMPULSORY

The Address Verification Service (AVS) Response Code for which you are defining the rule.
Existence
COMPULSORY
Fixed value
Validation Rules
The Address Verification Service (AVS) Response Code for which you are defining the rule.
JSON type
String
Value must be a member of the following list. The values are case sensitive.
ADDRESS_MATCH
Street address matched
ADDRESS_ZIP_MATCH
Street address and zip/postcode were matched
NAME_ADDRESS_MATCH
Card holder name and street address matched
NAME_MATCH
Card holder name matched
NAME_ZIP_MATCH
Card holder name and zip/postcode matched
NOT_AVAILABLE
No data available from issuer or AVS data not supported for transaction
NOT_REQUESTED
AVS not requested
NOT_VERIFIED
AVS could not be verified for an international transaction
NO_MATCH
No match
SERVICE_NOT_AVAILABLE_RETRY
Issuer system is unavailable. Retry can be attempted
SERVICE_NOT_SUPPORTED
Service currently not supported by acquirer or merchant
ZIP_MATCH
Zip/postcode matched. Street address not matched

order.valueTransfer   = OPTIONAL

Information about payments that transfer money to another store of value, such as a gift card or gaming chips.
Fixed value

order.valueTransfer.accountType  Enumeration = OPTIONAL

The type of value store to which money is being transferred.
The default value is NOT_A_TRANSFER.
Existence
OPTIONAL
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
NOT_A_TRANSFER
This payment is not for the purpose of transferring money to another store of value. It is a payment for goods or services.
PREPAID_LOAD
Payment to add funds to a prepaid card or gift card.
QUASI_CASH_TRANSACTION
Payment for items that are directly convertible to cash. For example, money orders, casino gaming chips, or traveller's checks.

order.valueTransfer.amount  Decimal = OPTIONAL

The amount of money being transferred, in units of order.valueTransfer.currency.
The default value is order.amount
Existence
OPTIONAL
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9 and '.' and represents a valid decimal number.
JSON type
String
minimum length
1
maximum length
14

order.valueTransfer.currency  Upper case alphabetic text = OPTIONAL

The currency of the store.
If the money is being transferred to multiple currencies, then use the currency of the highest transferred value.

The default value is order.currency.
Existence
OPTIONAL
Fixed value
Validation Rules
Data must consist of the characters A-Z
JSON type
String
minimum length
3
maximum length
3

order.valueTransfer.numberOfCards  Integer = OPTIONAL

The number of prepaid or gift card being purchased.
The default value is one when you set order.valueTransfer.accountType = PREPAID_LOAD. For all other values of order.valueTransfer.accountType the default is zero.
Existence
OPTIONAL
Fixed value
Validation Rules
JSON number data type, restricted to being positive or zero. In addition, the represented number may have no fractional part.
JSON type
Number
minimum value
0
maximum value
999

order.walletIndicator  String = OPTIONAL

The wallet indicator as returned by the wallet provider.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
3
maximum length
3

order.walletProvider  Enumeration = OPTIONAL

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

session.id  ASCII Text = OPTIONAL

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

session.version  ASCII Text = OPTIONAL

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

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

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

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

shipping   = OPTIONAL

Shipping information for this order.
Fixed value

shipping.address   = OPTIONAL

The address to which this order will be shipped.
Fixed value

shipping.address.city  String = OPTIONAL

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

shipping.address.company  String = OPTIONAL

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

shipping.address.country  Upper case alphabetic text = OPTIONAL

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

shipping.address.postcodeZip  Alphanumeric + additional characters = OPTIONAL

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

shipping.address.sameAsBilling  Enumeration = OPTIONAL

Indicates whether the shipping address provided is the same as the payer's billing address.
Provide this value if you are not providing the full shipping and billing addresses, but you can affirm that they are the same or different.

The default value for this field is:

SAME - if the shipping and billing address are supplied, and all fields are the same (ignoring non-alphanumerics).
DIFFERENT - if the shipping and billing address are supplied, and at least one field is different (ignoring non-alphanumerics).
UNKNOWN - either shipping address or billing address is absent.
Existence
OPTIONAL
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
DIFFERENT
The shipping and billing addresses are different.
SAME
The shipping and billing addresses are the same.
UNKNOWN
It is not known if the shipping and billing addresses are the same.

shipping.address.source  Enumeration = OPTIONAL

How you obtained the shipping address.
Existence
OPTIONAL
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
ADDRESS_ON_FILE
Order shipped to an address that you have on file.
NEW_ADDRESS
Order shipped to an address provided by the payer for this transaction.

shipping.address.stateProvince  String = OPTIONAL

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

shipping.address.stateProvinceCode  String = OPTIONAL

The three character ISO 3166-2 country subdivision code for the state or province of the address.
Providing this field might improve your payer experience for 3-D Secure payer authentication.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
3

shipping.address.street  String = OPTIONAL

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

shipping.address.street2  String = OPTIONAL

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

shipping.contact   = OPTIONAL

Details of the contact person at the address the goods will be shipped to.
Fixed value

shipping.contact.email  Email = OPTIONAL

The contact person's email address.
The field format restriction ensures that the email address is longer than 3 characters and adheres to a generous subset of valid RFC 2822 email addresses.
Existence
OPTIONAL
Fixed value
Validation Rules
Ensures that the email address is longer than 3 characters and adheres to a generous subset of valid RFC 2822 email addresses
JSON type
String

shipping.contact.firstName  String = OPTIONAL

The first name of the person to whom the order is being shipped.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
50

shipping.contact.lastName  String = OPTIONAL

The last name or surname of the person to whom the order is being shipped.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
50

shipping.contact.mobilePhone  Telephone Number = OPTIONAL

The contact person's mobile phone or cell phone number in ITU-T E123 format, for example +1 607 1234 5678

The number consists of:
  • ‘+’
  • country code (1, 2 or 3 digits)
  • ‘space’
  • national number ( which may embed single spaces characters for readability).
Existence
OPTIONAL
Fixed value
Validation Rules
Data consists of '+', country code (1, 2 or 3 digits), 'space', and national number (which may embed single space characters for readability)
JSON type
String
mandatory country code
true
maximum total digits
15

shipping.contact.phone  Telephone Number = OPTIONAL

The contact person's phone number in ITU-T E123 format, for example +1 607 1234 456

The number consists of:
  • ‘+’
  • country code (1, 2 or 3 digits)
  • ‘space’
  • national number ( which may embed single spaces characters for readability).
Existence
OPTIONAL
Fixed value
Validation Rules
Data consists of '+', country code (1, 2 or 3 digits), 'space', and national number (which may embed single space characters for readability)
JSON type
String
mandatory country code
true
maximum total digits
15

shipping.contact.sameAsBilling  Enumeration = OPTIONAL

Indicates whether the supplied name for the recipient of shipping matches the cardholder name.
Provide this value if you are not providing the full name or cardholder name, but you can affirm that they are the same or different.

Default value is UNKNOWN
Existence
OPTIONAL
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
DIFFERENT
The shipping and billing addresses are different.
SAME
The shipping and billing addresses are the same.
UNKNOWN
It is not known if the shipping and billing addresses are the same.

shipping.method  Enumeration = OPTIONAL

The shipping method used for delivery of this order.
Existence
OPTIONAL
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
ELECTRONIC
Electronic delivery.
GROUND
Ground (4 or more days).
NOT_SHIPPED
Order for goods that are not shipped (for example, travel and event tickets)
OVERNIGHT
Overnight (next day).
PICKUP
Shipped to a local store for pick up.
PRIORITY
Priority (2-3 days).
SAME_DAY
Same day.

shipping.origin.postcodeZip  Alphanumeric + additional characters = OPTIONAL

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

sourceOfFunds   = OPTIONAL

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

sourceOfFunds.provided   = OPTIONAL

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

sourceOfFunds.provided.card   = OPTIONAL

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

sourceOfFunds.provided.card.devicePayment   = OPTIONAL

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

sourceOfFunds.provided.card.devicePayment.3DSecure   = OPTIONAL

Details used to process a digital payment where the payment data keys for the online payment cryptogram are provided using the 3-D Secure format.
Use this parameter group for:
  • • Device payments: if you decrypt the payment token yourself. In this case, you source these fields directly from the decrypted payment token.
    You do not need to use this parameter group if you provide the payment token in sourceOfFunds.provided.card.devicePayment.paymentToken.
  • • Card scheme tokens: if you decrypt the transaction credentials yourself.
Fixed value

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

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

This field is not applicable for payments using digital wallets or card scheme tokens.
Existence
OPTIONAL
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9.
JSON type
String
minimum length
1
maximum length
2

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

A cryptogram used to authenticate the transaction.Use this field for:
  • • Device payments: source this field directly from the decrypted payment token.
  • • Card scheme tokens: source this field directly from the decrypted transaction credentials.
Existence
OPTIONAL
Fixed value
Validation Rules
Data is Base64 encoded
JSON type
String
minimum length
1
maximum length
128

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

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

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

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

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

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

For Google - this is PaymentMethodToken.getToken().

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

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

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

sourceOfFunds.provided.card.expiry   = OPTIONAL

Expiry date, as shown on the card.
Fixed value

sourceOfFunds.provided.card.expiry.month  Digits = COMPULSORY

Month, as shown on the card.
If using a scheme token this is the token expiry month.
Months are numbered January=1, through to December=12.
Existence
COMPULSORY
Fixed value
Validation Rules
Data is a number between 1 and 12 represented as a string.
JSON type
String

sourceOfFunds.provided.card.expiry.year  Digits = COMPULSORY

Year, as shown on the card.
If using a scheme token this is the token expiry year.
The Common Era year is 2000 plus this value.
Existence
COMPULSORY
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9.
JSON type
String
minimum length
2
maximum length
2

sourceOfFunds.provided.card.nameOnCard  String = OPTIONAL

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

sourceOfFunds.provided.card.number  Digits = OPTIONAL

Credit card number as printed on the card.
Existence
OPTIONAL
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9.
JSON type
String
minimum length
9
maximum length
19

sourceOfFunds.provided.card.securityCode  Digits = OPTIONAL

Card verification code, as printed on the back or front of the card or as provided for a card scheme token.
Existence
OPTIONAL
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9.
JSON type
String
minimum length
3
maximum length
4

sourceOfFunds.token  Alphanumeric = OPTIONAL

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

{merchantId}  Alphanumeric + additional characters COMPULSORY

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

{orderid}  String COMPULSORY

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

{transactionid}  String COMPULSORY

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

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

Response Parameters

merchant  Alphanumeric + additional characters = Always Provided

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

order   = Always Provided

Information about the order associated with this transaction.
Fixed value

order.amount  Decimal = Always Provided

The total amount for the order.  This is the net amount plus any merchant charge amounts.If you provide any sub-total amounts, then the sum of these amounts (order.itemAmount, order.taxAmount, order.shippingAndHandlingAmount, order.cashbackAmount, order.gratuityAmount, order.merchantCharge.amount and order.dutyAmount), minus the order.discountAmount must equal the net amount.
The value of this field in the response is zero if payer funds are not transferred.
Existence
Always Provided
Fixed value
Validation Rules
Data is a decimal number.
JSON type
Number
maximum value
1000000000000
minimum value
0
maximum post-decimal digits
3

order.creationTime  DateTime = Always Provided

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

order.currency  Upper case alphabetic text = Always Provided

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

order.id  String = Always Provided

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

order.lastUpdatedTime  DateTime = Always Provided

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

order.totalAuthorizedAmount  Decimal = Always Provided

The amount that has been successfully authorized for this order.
Existence
Always Provided
Fixed value
Validation Rules
Data is a decimal number.
JSON type
Number
maximum value
1000000000000
minimum value
0
maximum post-decimal digits
3

order.totalCapturedAmount  Decimal = Always Provided

The amount that has been successfully captured for this order.
Existence
Always Provided
Fixed value
Validation Rules
Data is a decimal number.
JSON type
Number
maximum value
1000000000000
minimum value
0
maximum post-decimal digits
3

order.totalRefundedAmount  Decimal = Always Provided

The amount that has been successfully refunded for this order.
Existence
Always Provided
Fixed value
Validation Rules
Data is a decimal number.
JSON type
Number
maximum value
1000000000000
minimum value
0
maximum post-decimal digits
3

response   = Always Provided

Fixed value

response.gatewayCode  Enumeration = Always Provided

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

result  Enumeration = Always Provided

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

transaction   = Always Provided

Information about this transaction.
Fixed value

transaction.amount  Decimal = Always Provided

The total amount for the transaction.
Existence
Always Provided
Fixed value
Validation Rules
Data is a decimal number.
JSON type
Number
maximum value
1000000000000
minimum value
0
maximum post-decimal digits
3

transaction.currency  Upper case alphabetic text = Always Provided

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

transaction.id  String = Always Provided

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

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

transaction.type  Enumeration = Always Provided

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

accountFunding   = CONDITIONAL

Additional details for account funding transactions (order.purchaseType=ACCOUNT_FUNDING).
Account funding transactions are transactions that pull money from the sender's card account for the purpose of funding another account, the recipient's account. Depending on the type of account funding transaction you may be required to provide some or all the details in this parameter group.
Fixed value

accountFunding.purpose  Enumeration = CONDITIONAL

Defines the purpose of the account funding payment.If not provided the value is defaulted to OTHER.
Existence
CONDITIONAL
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
CRYPTOCURRENCY_PURCHASE
The funds from this account funding transaction will be used to purchase cryptocurrency.
MERCHANT_SETTLEMENT
The funds from this account funding transaction will be used to settle the proceeds of processing card transactions.
OTHER
The funds from this account funding transaction will be used for any other purpose, e.g. transferring funds from a person to a person or transferring funds into a staged wallet.This is the default value.
PAYROLL
The funds from this account funding transaction will be used to pay salaries.

accountFunding.recipient   = CONDITIONAL

Details about the recipient who will subsequently receive the funds that you are debiting from the sender in this transaction.
Fixed value

accountFunding.recipient.country  Upper case alphabetic text = CONDITIONAL

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

accountFunding.recipient.dateOfBirth  Date = CONDITIONAL

The date of birth of the recipient in yyyy-mm-dd format.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data must comply with ISO 8601 extended date format, yyyy-mm-dd
JSON type
String

accountFunding.recipient.firstName  String = CONDITIONAL

First name of the recipient.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
50

accountFunding.recipient.lastName  String = CONDITIONAL

Last name of the recipient.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
50

accountFunding.recipient.postCodeZip  String = CONDITIONAL

The post code or zip code of the recipient.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
10

accountFunding.recipient.stateProvinceCode  String = CONDITIONAL

The state or province code of the recipient.
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.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
3

accountFunding.senderIsRecipient  Boolean = CONDITIONAL

Defines if the sender and recipient of the account funding payment are the same or not.
If not provided the value is defaulted to FALSE.
Existence
CONDITIONAL
Fixed value
Validation Rules
JSON boolean values 'true' or 'false'.
JSON type
Boolean

accountFunding.senderType  Enumeration = CONDITIONAL

Defines if the sender is a person, a commercial organization, a non-profit organization or a government
Existence
CONDITIONAL
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
COMMERCIAL_ORGANIZATION
The sender is a commercial organization. Examples include account to account transfers initiated by a commercial organization for the purpose of transferring funds to one of their accounts, business to business payments, and disbursements for insurance claims, payroll, investment dividends, merchant rebates.
GOVERNMENT
The sender is a government or government agency. Examples include government agencies paying salaries, pensions, social benefits or tax credits.
NON_PROFIT_ORGANIZATION
The sender is a non-profit organization. Examples include non-profit organizations delivering emergency aid payments.
PERSON
The sender is a person. Examples include account to account transfers initiated by a person to their own account or a different person's account and adding funds to a staged wallet.

agreement   = CONDITIONAL

A series of related orders that execute one commercial agreement.
For example, linking the orders for a series of recurring payments (a mobile phone subscription), split tenders (one payment using two cards), or when the merchant offers to take payments by a series of installments (hire purchase).
Fixed value

agreement.amountVariability  Enumeration = CONDITIONAL

Indicates if all the payments within the agreement use the same amount or if the amount differs between the payments.
The field must be provided for recurring payment agreements.
Existence
CONDITIONAL
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
FIXED
All payments in the recurring payment agreement have the same amount. Examples include magazine subscriptions or gym memberships.
VARIABLE
The amount for the payments within the recurring payment agreement differs between payments. Examples include usage-based charges like utility or phone bills.

agreement.expiryDate  Date = CONDITIONAL

Date at which your agreement with the payer to process payments expires.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data must comply with ISO 8601 extended date format, yyyy-mm-dd
JSON type
String

agreement.id  String = CONDITIONAL

Your identifier for the agreement you have with the payer to process payments.
When you collect cards from your payers and store them for later use, you must provide an agreement ID when you use the stored values for:

  • Recurring payments: you have an agreement with the payer that authorizes you to automatically debit their account at agreed intervals for fixed or variable amounts. For example, gym membership, phone bills, or magazine subscriptions.
  • Installment payments: you have an agreement with the payer that authorizes you to process multiple payments over an agreed period of time for a single purchase. For example, the payer purchases an item for $1000 and pays for it in four monthly installments.
  • Unscheduled: you have an agreement with the payer that authorizes you to process future payments when required. For example, the payer authorizes you to process an account top-up transaction for a transit card when the account balance drops below a certain threshold.
  • Industry Practice: you have an agreement with the payer that authorizes you to initiate additional transactions to fulfil a standard business practice related to an original payment initiated by the payer. For example, a delayed charge for use of the hotel mini bar after the payer has checked out or a no show penalty charge when the payer fails to show for a booking.
When you first establish an agreement with the payer you should also specify the type of agreement in agreement.type.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
100

agreement.maximumAmountPerPayment  Decimal = CONDITIONAL

The maximum amount for a single payment in the series as agreed with the payer under your agreement with them.
The amount must be provided in the currency of the order.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data is a decimal number.
JSON type
Number
maximum value
99999999999999
minimum value
0
maximum post-decimal digits
3

agreement.minimumDaysBetweenPayments  Integer = CONDITIONAL

The minimum number of days between payments agreed with the payer under your agreement with them.
Existence
CONDITIONAL
Fixed value
Validation Rules
JSON number data type, restricted to being positive or zero. In addition, the represented number may have no fractional part.
JSON type
Number
minimum value
1
maximum value
9999

agreement.numberOfPayments  Integer = CONDITIONAL

The number of merchant-initiated payments within the recurring payment agreement.
Existence
CONDITIONAL
Fixed value
Validation Rules
JSON number data type, restricted to being positive or zero. In addition, the represented number may have no fractional part.
JSON type
Number
minimum value
1
maximum value
999

agreement.paymentFrequency  Enumeration = CONDITIONAL

The frequency of the payments within the series as agreed with the payer under your agreement with them.
Existence
CONDITIONAL
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
AD_HOC
The agreement if for payments on an ah-hoc basis.
DAILY
The agreement if for a daily payment.
FORTNIGHTLY
The agreement if for a fortnightly payment.
MONTHLY
The agreement if for a monthly payment.
OTHER
The agreement is for payments according to a schedule other than the ones listed in the other enumeration values for this field.
QUARTERLY
The agreement if for a quarterly payment.
TWICE_YEARLY
The agreement if for a payment twice a year.
WEEKLY
The agreement if for a weekly payment.
YEARLY
The agreement if for a yearly payment.

agreement.type  Enumeration = CONDITIONAL

The type of commercial agreement that the payer has with you.
Specify the agreement type when you have provided a value for agreement.id and this payment is the first in a series of payments. The default value is OTHER.

The gateway will use the value you specify for subsequent payments in the series.
Existence
CONDITIONAL
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
INDUSTRY_PRACTICE
An agreement where the payer authorizes you to initiate additional transactions to fulfil a standard business practice related to an original payment initiated by the payer. These additional payments are triggered by an event not known at the time of the payer's initial agreement. For example, a delayed charge for use of the hotel mini bar after the payer has checked out or a no show charge when the payer fails to show for a booking.
INSTALLMENT
An agreement where the payer authorizes the payment for a single purchase to be split into a number of payments processed at agreed intervals. For example, pay for a purchase in six monthly installments.
OTHER
An agreement where you want to link related payments for any purpose other than processing recurring, installment, or unscheduled payments. For example, split tender payments.
RECURRING
An agreement where the payer authorizes you to process repeat payments for bills or invoices at agreed intervals (for example, weekly, monthly). The amount might be fixed or variable.
UNSCHEDULED
An agreement where the payer authorizes you to automatically deduct funds for a payment for an agreed purchase when required (unscheduled). For example, auto top-ups when the account value falls below a threshold.

authentication   = CONDITIONAL

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

authentication.3ds   = CONDITIONAL

Information about payer authentication using 3-D Secure authentication.
Parameters in this group apply to both 3-D Secure authentication version 1 and 3-D Secure Authentication version 2.

Depending on the 3-D Secure authentication version applicable you will also need additional parameters:
  • 3-D Secure authentication version 1: see the authentication.3ds1 parameter group.
  • 3-D Secure authentication version 2: see the authentication.3ds2 parameter group.
Fixed value

authentication.3ds.acsEci  Alphanumeric = CONDITIONAL

Indicates the security level of the transaction.
This is the Electronic Commerce Indicator (ECI) value provided by the issuer's Access Control Server (ACS) to indicate the results of the attempt to authenticate the payer.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data may consist of the characters 0-9, a-z, A-Z
JSON type
String
minimum length
1
maximum length
2

authentication.3ds.authenticationToken  Base64 = CONDITIONAL

The base64 encoded value generated by the issuer.
The authentication token Included in subsequent transaction request messages and used by the card scheme to verify that the authentication occurred and the values provided are valid. The token should be used unaltered. For 3DS version 1, this field corresponds to the Cardholder Authentication Verification Value (CAVV) for Visa, the Accountholder Authentication Value (AAV) for MasterCard and JCB, or the American Express Verification Value (AEVV) for American Express.

For 3DS version 2, this field corresponds to the Authentication Value.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data is Base64 encoded
JSON type
String
allowable lengths
28 or 32

authentication.3ds.transactionId  String = CONDITIONAL

A unique identifier for the 3-D Secure authentication transaction.
For 3DS version 1, this field corresponds to the XID. The XID is an identifier generated by the gateway on behalf of the merchant.

For 3DS version 2, this field corresponds to the identifier assigned by the scheme directory server.

This identifier should be used in subsequent operation requests unaltered.

An XID submitted in this field must be in base64 format.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
50

authentication.3ds1   = CONDITIONAL

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

authentication.3ds1.paResStatus  Alpha = CONDITIONAL

Indicates the result of payer authentication with the issuer.
This is the value returned in the transaction status field of the Payer Authentication Response (PARes) message from the card Issuer's Access Control Server (ACS). For example, Y, N, A, or U. Refer to the relevant documentation for Mastercard SecureCode™, Verified by Visa™, JCB J/Secure™, American Express SafeKey™, or Diners Club ProtectBuy™.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data may consist of the characters a-z, A-Z
JSON type
String
minimum length
1
maximum length
1

authentication.3ds1.veResEnrolled  Alpha = Always Provided

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

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

authentication.3ds2   = CONDITIONAL

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

authentication.3ds2.3dsServerTransactionId  String = CONDITIONAL

You can ignore this field unless you want to build your own mobile SDK for EMV 3DS using the gateway's API.
The field contains the unique identifier assigned by the 3DS Server for this authentication. This is referred to in the EMVCo specification for 3-D Secure as threeDSServerTransID.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
50

authentication.3ds2.acsTransactionId  String = CONDITIONAL

A unique transaction identifier assigned by the Access Control Server to identify the 3DS transaction.
The ACS transaction id should be used in subsequent operation requests unaltered.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
36
maximum length
36

authentication.3ds2.custom  JSON Text = CONDITIONAL

Additional information returned by the scheme or issuer in the authentication response that must be included (together with the standard authentication details) when submitting the transaction for processing by the acquirer.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data is valid Json Format
JSON type
String
minimum length
1
maximum length
4000

authentication.3ds2.directoryServerId  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).
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
10
maximum length
10

authentication.3ds2.dsTransactionId  String = CONDITIONAL

A unique transaction identifier assigned by the scheme Directory Server to identify the 3DS transaction.
The DS transaction id should be used in subsequent operation requests unaltered.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
50

authentication.3ds2.methodCompleted  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.
Existence
Always Provided
Fixed value
Validation Rules
JSON boolean values 'true' or 'false'.
JSON type
Boolean

authentication.3ds2.methodSupported  Enumeration = Always Provided

Indicates if the issuer's Access Control Server (ACS) support the method call.
Existence
Always Provided
Fixed value
Validation Rules
Indicates if the issuer's Access Control Server (ACS) support the method call.
JSON type
String
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  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.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data may consist of the characters 0-9, a-z, A-Z, '.'
JSON type
String
minimum length
1
maximum length
20

authentication.3ds2.requestorId  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.
Existence
Always Provided
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
35

authentication.3ds2.requestorName  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.
Existence
Always Provided
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
40

authentication.3ds2.sdk   = CONDITIONAL

Information provided by the 3-D Secure Software Development Kit (SDK) that is used by an app on the payer's device to enable 3-D Secure authentication of the payer to be performed in-app.
You must populate the fields in this parameter group when you authenticate the payer in-app using 3-D Secure authentication version 2.
Fixed value

authentication.3ds2.sdk.challengeCompletionCallbackUrl  Url = CONDITIONAL

This value is only returned when you authenticate the payer in-app using 3-D Secure authentication version 2 and a challenge is required (authentication.channel = PAYER_APP and authentication.3ds2.transactionStatus = C).
You must call this URL after the challenge has been completed; for example, when the ACS has confirmed the challenge completion.
This allows the gateway to retrieve the authentication result after the challenge has been completed.
Existence
CONDITIONAL
Fixed value
Validation Rules
Ensure that the URL begins with 'https' and is longer than 11 characters.
JSON type
String

authentication.3ds2.sdk.interface  Enumeration = CONDITIONAL

The User Interface (UI) formats that the payer's device supports.
These are the formats that can be used to render the screens presented to the payer during an authentication challenge.

You only need to provide this value if you only support one of these formats.

This field corresponds to EMVCo data element sdkInterface in the field deviceRenderOptions.
Existence
CONDITIONAL
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
HTML
The device supports HTML format.
NATIVE
The device supports the UI format native to the payer's device.

authentication.3ds2.sdk.timeout  Integer = CONDITIONAL

The duration (in seconds) available to the payer to authenticate.
Will default to 900 if not provided. Note: The value will be rounded up to the nearest minute.

This field corresponds to EMVCo field sdkMaxTimeout
Existence
CONDITIONAL
Fixed value
Validation Rules
JSON number data type, restricted to being positive or zero. In addition, the represented number may have no fractional part.
JSON type
Number
minimum value
300
maximum value
900

authentication.3ds2.sdk.uiType  Comma separated enumeration = CONDITIONAL

Indicates the UI types which the SDK supports for displaying authentication challenges within the app.
A comma separated list of the payer authentication methods that you will accept for this payment.

You only need to provide this value if all of these values are not supported.

Note: OTHER_HTML is only supported when authentication.3ds2.sdk.interface allows a HTML UI format.

This field corresponds to EMVCo data element sdkUiType in the field deviceRenderOptions.
Existence
CONDITIONAL
Fixed value
Validation Rules
Indicates the UI types which the SDK supports for displaying authentication challenges within the app.
JSON type
String
Value must be one or more comma separated members of the following list. The values are case sensitive.
TEXT
The payer is asked to enter text into a field displayed on the UI. For example, ask the payer to enter a One Time Password sent to their registered mobile phone number.
SINGLE_SELECT
The payer is asked to select a single option from a number of presented options. For example, ask the payer if they want a One Time Password to be sent to either their email address or mobile phone number registered with their issuer.
MULTI_SELECT
The payer is asked to select multiple options from a number of presented options. For example, ask the payer to select valid responses to a question.
OUT_OF_BAND
The payer is presented with screens rendered by an out-of-band service during an authentication challenge, For example, the payer is asked to confirm the payment from their banking app.
OTHER_HTML
The payer is presented with an authentication challenge using other mechanisms supported in HTML but not in the native UI format. For example, the payer is asked to confirm an image presented on the screen.

authentication.3ds2.statusReasonCode  String = CONDITIONAL

A code indicating the reason for the transaction status returned in authentication.3ds2.transactionStatus.
Refer to the EMVCo specification for 3-D Secure.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
2
maximum length
2

authentication.3ds2.transactionStatus  Alpha = CONDITIONAL

Indicates the result of payer authentication with the issuer.
This is the value returned in the transaction status field from the issuer's Access Control Server (ACS). For example, Y, N, U, A, R

Refer to the EMVCo specification for 3-D Secure.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data may consist of the characters a-z, A-Z
JSON type
String
minimum length
1
maximum length
1

authentication.3ds2.acsReference  String = CONDITIONAL

Unique identifier assigned to the issuer's Access Control Server (ACS) by the EMVCo.
This field corresponds to EMVCo field acsRefNumber.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
0
maximum length
32

authentication.3ds2.challenge   = CONDITIONAL

Information provided by the issuer's Access Control Server (ACS) that is used to render the screens presented to the payer during an authentication challenge.
Fixed value

authentication.3ds2.challenge.signedContent  String = CONDITIONAL

A JSON Web Signature (JWS) object returned by the issuer's Access Control Server (ACS).
Use this field to validate the integrity of the information returned.

The body of the object contains the following data:

  • ACS URL: URL of the issuer's ACS
  • SDK public key: A public key generated by the 3-D Secure SDK (see authentication.3ds2.sdk.ephemeralPublicKey)
  • ACS public key: A public key generated by the issuer's ACS.

When using the REST/JSON gateway API, this is returned as a JSON string (ie the embedded quotes will be escaped).

This field corresponds to EMVCo field acsSignedContent.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
0
maximum length
16384

authentication.amount  Decimal = CONDITIONAL

The amount for which the payer authentication has been performed.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data is a decimal number.
JSON type
Number
maximum value
1000000000000
minimum value
0
maximum post-decimal digits
3

authentication.method  Enumeration = CONDITIONAL

The method that the issuer will use to authenticate the payer.
Existence
CONDITIONAL
Fixed value
Validation Rules
JSON type
String
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.payerInteraction  Enumeration = Always Provided

Indicates if payer interaction was used to complete the authentication process.
Existence
Always Provided
Fixed value
Validation Rules
Indicates if payer interaction was used to complete the authentication process.
JSON type
String
Value must be a member of the following list. The values are case sensitive.
NOT_POSSIBLE
Payer interaction was either not possible or not applicable to completing the authentication process. For example, there was a technical problem, or the authentication method is not supported for this payment method.
NOT_REQUIRED
No payer interaction was required to complete the authentication process. The issuer was able to make a decision based on the data provided.
REQUIRED
Payer interaction was required to complete the authentication process. For example, the payer was presented with a challenge to verify their identity.

authentication.psd2   = CONDITIONAL

This parameter group is only applicable if you are subject to the Regulatory Technical Standards (RTS) requirements for Strong Customer Authentication (SCA) under the Payment Services Directive 2 (PSD2) regulations in the European Economic Area.
It provides details about SCA exemptions under PSD2.
Fixed value

authentication.psd2.exemption  Enumeration = CONDITIONAL

Indicates if you believe this payment to be exempt or excluded from the Strong Customer Authentication (SCA) requirement.
Note:
  • For recurring payments, provide the MERCHANT_INITIATED_TRANSACTION value only if the amount is the same. If the amount is variable, provide RECURRING_PAYMENT instead.
Existence
CONDITIONAL
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
AUTO
If either a LOW_RISK or LOW_VALUE_PAYMENT exemption applies to the transaction, it is automatically claimed by the gateway on behalf of the merchant.
LOW_RISK
Exemption is claimed because the acquirer has a low fraud rate.
LOW_VALUE_PAYMENT
Exemption is claimed as the amount is below 30 Euro.
MERCHANT_INITIATED_TRANSACTION
The transaction is excluded as it was initiated by the merchant based on an agreement with the payer. For example, a recurring payment (for a fixed amount), installment payment, or account top-up. In these cases, the payer is not present and cannot participate in an authentication interaction. Merchant initiated transactions are only applicable to subsequent transactions on the order and are out of scope of the PSD2 RTS on Strong Customer Authentication (SCA). The payer must be authenticated during the first transaction that established the agreement.
NONE
An exemption is not claimed for this transaction. The merchant requires Strong Customer Authentication (SCA) be performed.
RECURRING_PAYMENT
The transaction is exempt as it was initiated by the merchant based on an agreement with the payer for a recurring payment for a variable amount. This value is only applicable to subsequent transactions on the order. In this case, the payer is not present and cannot participate in an authentication interaction. The payer must be authenticated during the first transaction that established the agreement.
SECURE_CORPORATE_PAYMENT
The transaction is exempt as it is a corporate or Business-to-Business (B2B) payment performed using dedicated payment processes and protocols that are not available to consumers and offer at least equivalent security levels.
WHITELISTED_MERCHANT
The transaction is exempt because the payer has added you to the list of their trusted merchants (as maintained by the issuer).

authentication.psd2.whitelistStatus  Enumeration = CONDITIONAL

Indicates if the payer has whitelisted you with the issuer and has opted-out of Strong Customer Authentication (SCA).
Existence
CONDITIONAL
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
NOT_WHITELISTED
The payer has not whitelisted the merchant with the issuer or the merchant's whitelist status is unknown.
WHITELISTED
The payer has whitelisted the merchant with the issuer.

authentication.redirect   = CONDITIONAL

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

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

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

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

authentication.redirect.customizedHtml   = CONDITIONAL

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

authentication.redirect.customizedHtml.3ds2   = CONDITIONAL

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

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

The URL of the issuer's Access Control Server (ACS) to be used for the challenge flow.
This information will only be provided by the gateway if the payer's browser is present (authentication.channel=PAYER_BROWSER) and the challenge flow is required.
Existence
CONDITIONAL
Fixed value
Validation Rules
Ensure that the URL begins with 'https' and is longer than 11 characters.
JSON type
String

authentication.redirect.customizedHtml.3ds2.cReq  ASCII Text = CONDITIONAL

The Base64 URL encoded CReq message to be used for the challenge flow.
This information will only be provided by the gateway if the payer's browser is present (authentication.channel=PAYER_BROWSER) and the challenge flow is required.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data consists of ASCII characters
JSON type
String
minimum length
0
maximum length
4000

authentication.redirect.html  String = CONDITIONAL

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

authentication.redirect.domainName  String = CONDITIONAL

The domain name of the site where payer authentication was performed.
For example, the domain-name of the issuer's Access Control Server (ACS) used for payer authentication using 3-D Secure authentication.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
253

authentication.time  DateTime = CONDITIONAL

Date and time of the payer authentication being performed.
Existence
CONDITIONAL
Fixed value
Validation Rules
An instant in time expressed in ISO8601 date + time format - "YYYY-MM-DDThh:mm:ss.SSSZ"
JSON type
String

authentication.version  Enumeration = CONDITIONAL

If online authentication of the payer is available, then this field shows the type.
If no such authentication is available, the value is NONE.
Existence
CONDITIONAL
Fixed value
Validation Rules
If online authentication of the payer is available, then this field shows the type. If no such authentication is available, the value is NONE.
JSON type
String
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.

billing   = CONDITIONAL

Information on the billing address including the contact details of the payer.
Fixed value

billing.address   = CONDITIONAL

The payer's billing address.
This data may be used to qualify for better interchange rates on corporate purchase card transactions.
Fixed value

billing.address.city  String = CONDITIONAL

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

billing.address.company  String = CONDITIONAL

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

billing.address.country  Upper case alphabetic text = CONDITIONAL

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

billing.address.postcodeZip  Alphanumeric + additional characters = CONDITIONAL

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

billing.address.stateProvince  String = CONDITIONAL

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

billing.address.stateProvinceCode  String = CONDITIONAL

The three character ISO 3166-2 country subdivision code for the state or province of the address.
Providing this field might improve your payer experience for 3-D Secure payer authentication.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
3

billing.address.street  String = CONDITIONAL

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

billing.address.street2  String = CONDITIONAL

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

correlationId  String = CONDITIONAL

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

customer   = CONDITIONAL

Information about the customer, including their contact details.
Fixed value

customer.email  Email = CONDITIONAL

The email address of the customer.
The field format restriction ensures that the email address is longer than 3 characters and adheres to a generous subset of valid RFC 2822 email addresses.
Existence
CONDITIONAL
Fixed value
Validation Rules
Ensures that the email address is longer than 3 characters and adheres to a generous subset of valid RFC 2822 email addresses
JSON type
String

customer.firstName  String = CONDITIONAL

The payer's first name.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
50

customer.lastName  String = CONDITIONAL

The payer's last or surname.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
50

customer.mobilePhone  String = CONDITIONAL

The contact person's mobile phone or cell phone number.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
20

customer.phone  String = CONDITIONAL

The phone number of the person to whom the order is being billed.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
20

customer.taxRegistrationId  String = CONDITIONAL

The tax registration identifier of the customer.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
30

device   = CONDITIONAL

Information about the device used by the payer for this transaction.
Fixed value

device.ani  String = CONDITIONAL

The telephone number captured by ANI (Automatic Number Identification) when the customer calls to place the order.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
10

device.aniCallType  String = CONDITIONAL

The 2 digit ANI information identifier provided by the telephone company to indicate the call type, for example, cellular (61-63), toll free (24,25), etc.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
2

device.browser  String = CONDITIONAL

The User-Agent header of the browser the customer used to place the order.For example, MOZILLA/4.0 (COMPATIBLE; MSIE 5.0; WINDOWS 95)

You must provide a value in this field if you are performing 3-D Secure authentication of the payer and set authentication.channel = PAYER_BROWSER.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
255

device.hostname  String = CONDITIONAL

The name of the server to which the customer is connected.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
60

device.ipAddress  String = CONDITIONAL

The IP address of the device used by the payer, in nnn.nnn.nnn.nnn format.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
7
maximum length
15

device.mobilePhoneModel  String = CONDITIONAL

The mobile phone manufacturer's identifier for the model of the mobile device used to initiate the payment.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
255

encryptedData   = CONDITIONAL

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

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

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

encryptedData.ciphertext  String = Always Provided

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

encryptedData.nonce  String = Always Provided

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

encryptedData.tag  String = Always Provided

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

lineOfBusiness  String = CONDITIONAL

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

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

merchant  Alphanumeric + additional characters = Always Provided

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

order   = Always Provided

Information about the order associated with this transaction.
Fixed value

order.acceptPartialAmount  Boolean = CONDITIONAL

Indicates whether you will accept a payment less than order.amount, e.g. when using a gift card.
If not set or set to FALSE, and the full amount is not available, the transaction will be rejected.
Unless you have been advised by your payment service provider that the gateway supports partial approvals for your acquirer, you can ignore this field.
If the gateway supports partial approvals for your acquirer you must set this field to TRUE else the transaction is rejected by the gateway.
Existence
CONDITIONAL
Fixed value
Validation Rules
JSON boolean values 'true' or 'false'.
JSON type
Boolean

order.amount  Decimal = Always Provided

The total amount for the order.  This is the net amount plus any merchant charge amounts.If you provide any sub-total amounts, then the sum of these amounts (order.itemAmount, order.taxAmount, order.shippingAndHandlingAmount, order.cashbackAmount, order.gratuityAmount, order.merchantCharge.amount and order.dutyAmount), minus the order.discountAmount must equal the net amount.
The value of this field in the response is zero if payer funds are not transferred.
Existence
Always Provided
Fixed value
Validation Rules
Data is a decimal number.
JSON type
Number
maximum value
1000000000000
minimum value
0
maximum post-decimal digits
3

order.authenticationStatus  Enumeration = CONDITIONAL

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

order.certainty  Enumeration = CONDITIONAL

Indicates if you expect to capture the full order amount for which you are requesting authorization.
If you do not provide a value for order.certainty the default configured for you by your payment service provider will be used. The value provided in the response shows the value the gateway sent to the acquirer
Existence
CONDITIONAL
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
ESTIMATED
The amount authorized is an estimate of the amount that will be captured. It is possible that the amount captured will be less, or might not be captured at all.
FINAL
The full authorized amount is expected to be captured within the mandated time. The order will only be cancelled in exceptional circumstances (for example, the payer cancelled their purchase).

order.creationTime  DateTime = Always Provided

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

order.currency  Upper case alphabetic text = Always Provided

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

order.custom  String = CONDITIONAL

A field you provide to capture additional information about this order that is only of interest to you.
The gateway does not send this information to the acquirer. A maximum of 50 such fields may be added to the order.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
250

order.customerNote  String = CONDITIONAL

A note from the payer about this order.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
250

order.customerOrderDate  Date = CONDITIONAL

The date the payer placed the order.
Data must comply with ISO 8601 extended date format, yyyy-mm-dd.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data must comply with ISO 8601 extended date format, yyyy-mm-dd
JSON type
String

order.customerReference  ASCII Text = CONDITIONAL

The payer's own reference for the order.
This reference may assist the payer to identify the order in their system. For example, a purchase order number, project identifier, or cost center.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data consists of ASCII characters
JSON type
String
minimum length
0
maximum length
25

order.description  String = CONDITIONAL

Short textual description of the contents of the order.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
127

order.discount   = CONDITIONAL

Information about a price reduction you have applied to the order.
For example, you may apply discounts for trade, employees, bulk purchase, or a sales promotion.
Fixed value

order.discount.amount  Decimal = CONDITIONAL

The total amount of the discount you have applied to the order.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data is a decimal number.
JSON type
Number
maximum value
1000000000000
minimum value
0
maximum post-decimal digits
3

order.discount.code  String = CONDITIONAL

The code you use to identify the reason for the discount.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
40

order.discount.description  String = CONDITIONAL

A description of your reason for the discount.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
127

order.dutyAmount  Decimal = CONDITIONAL

The duty amount (also known as customs tax, tariff or dues) for the order.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data is a decimal number.
JSON type
Number
maximum value
1000000000000
minimum value
0
maximum post-decimal digits
3

order.id  String = Always Provided

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

order.invoiceNumber  String = CONDITIONAL

The invoice number you issued for this order.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
25

order.lastUpdatedTime  DateTime = Always Provided

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

order.localTaxRegistrationId  String = CONDITIONAL

Your tax registration identifier provided by the Local/State/Province tax authority.
If you are a Canadian merchant, use this field to provide your Tax Registration ID for paying Provincial Sales Tax (PST).
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
25

order.marketplace   = CONDITIONAL

Use this parameter group to provide additional information if you are a marketplace.You are considered a marketplace if you operate an electronic commerce website or mobile application that brings together payers and retailers and you are selling the goods or services on behalf of the retailer.In this case, the card schemes may require you to register with them as a marketplace and assign you a Marketplace ID.
You should provide this identifier to your payment service provider so that the gateway can automatically include it in all transaction messages to your acquirer.
Fixed value

order.marketplace.retailerLocation  Enumeration = CONDITIONAL

Provide information about the location of the retailers for goods or services included in this order.Where a retailer is located in a country different from your country, they are considered a foreign retailer, otherwise they are considered a domestic retailer.
Existence
CONDITIONAL
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
DOMESTIC_ONLY
The order only contains items from domestic retailers.
FOREIGN_AND_DOMESTIC
The order contains items from both foreign and domestic retailers.
FOREIGN_ONLY
The order only contains items from foreign retailers.

order.merchantCategoryCode  Digits = CONDITIONAL

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

order.merchantCharge   = CONDITIONAL

Information about additional fees that you are charging the payer for processing the payment for this order, for example, a surcharge.
Fixed value

order.merchantCharge.amount  Decimal = Always Provided

The amount of the additional fee that you are charging the payer.
If you provide a charge amount, you must include it in the total amount for the order.
Existence
Always Provided
Fixed value
Validation Rules
Data is a decimal number.
JSON type
Number
maximum value
1000000000000
minimum value
0
maximum post-decimal digits
3

order.merchantCharge.calculatedBy  Enumeration = Always Provided

Indicates who calculated the charge amount.
Existence
Always Provided
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
CLIENT
The charge amount was included in the transaction request.
GATEWAY
The gateway calculated the charge amount based on the net amount included in the transaction request and the configured charge rules.

order.merchantCharge.ruleName  String = CONDITIONAL

Where the gateway has generated the charge amount based on the configured charge rules, this field contains the name of the rule.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
50

order.merchantCharge.type  Enumeration = Always Provided

The type of the additional fee that you are charging the payer.
Existence
Always Provided
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
SURCHARGE
A fee that covers your cost of accepting accepting a payment method.

order.netAmount  Decimal = CONDITIONAL

The amount payable for the order before merchant charge amount is applied.
If you specify a net amount the gateway will calculate the merchant charge amount for you based on the charge type (order.merchantCharge.type) provided in the request. Alternatively, you can specify the merchant charge amount (order.merchantCharge.amount) yourself.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data is a decimal number.
JSON type
Number
maximum value
1000000000000
minimum value
0
maximum post-decimal digits
3

order.notificationUrl  Url = CONDITIONAL

The URL to which the gateway will send Webhook notifications when an order is created or updated.
To receive notifications at this URL, you must enable Webhook notifications in Merchant Administration. Ensure the URL is HTTPS
Existence
CONDITIONAL
Fixed value
Validation Rules
Ensure that the URL begins with 'https' and is longer than 11 characters.
JSON type
String

order.owningEntity  String = CONDITIONAL

Your identifier for the part of your organization that is responsible for the order.
You might provide this data when you want to track the accountability for the order. For example, store number, sales region, branch, or profit center
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
40

order.reference  String = CONDITIONAL

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

order.requestorName  String = CONDITIONAL

The name of the person who requested the goods or services.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
100

order.shippingAndHandlingAmount  Decimal = CONDITIONAL

The total shipping and handling amount for the order, including taxes on the shipping and/or handling.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data is a decimal number.
JSON type
Number
maximum value
1000000000000
minimum value
0
maximum post-decimal digits
3

order.shippingAndHandlingTaxAmount  Decimal = CONDITIONAL

The tax amount levied on the shipping and handling amount for the order.
This amount is included in the shipping and handling amount provided in field order.shippingAndHandlingAmount.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data is a decimal number.
JSON type
Number
maximum value
1000000000000
minimum value
0
maximum post-decimal digits
3

order.shippingAndHandlingTaxRate  Decimal = CONDITIONAL

The tax rate applied to the shipping and handling amount for the order to determine the shipping and handling tax amount.
For a tax rate of 2.5% provide 0.025.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data is a decimal number.
JSON type
Number
maximum value
1000000000000000000
minimum value
0
maximum post-decimal digits
4

order.statementDescriptor   = CONDITIONAL

Contact information provided by you for printing on payer's account statements.
Fixed value

order.statementDescriptor.address   = CONDITIONAL

Descriptor address of the merchant.
Fixed value

order.statementDescriptor.address.city  String = CONDITIONAL

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

order.statementDescriptor.address.company  String = CONDITIONAL

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

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

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

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

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

order.statementDescriptor.address.stateProvince  String = CONDITIONAL

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

order.statementDescriptor.address.street  String = CONDITIONAL

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

order.statementDescriptor.address.street2  String = CONDITIONAL

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

order.statementDescriptor.name  String = CONDITIONAL

Descriptor name of the merchant.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
100

order.statementDescriptor.phone  String = CONDITIONAL

Descriptor phone number of the merchant's business.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
20

order.status  Enumeration = CONDITIONAL

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

order.subMerchant   = CONDITIONAL

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

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

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

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

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

order.subMerchant.address   = CONDITIONAL

The sub-merchant's address.
Fixed value

order.subMerchant.address.city  String = CONDITIONAL

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

order.subMerchant.address.company  String = CONDITIONAL

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

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

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

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

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

order.subMerchant.address.stateProvince  String = CONDITIONAL

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

order.subMerchant.address.street  String = CONDITIONAL

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

order.subMerchant.address.street2  String = CONDITIONAL

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

order.subMerchant.authentication[n]   = CONDITIONAL

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

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

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

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

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

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

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

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

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

order.subMerchant.bankIndustryCode  Digits = CONDITIONAL

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

order.subMerchant.disputeContactPhone  Telephone Number = CONDITIONAL

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

order.subMerchant.email  Email = CONDITIONAL

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

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

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

order.subMerchant.phone  String = CONDITIONAL

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

order.subMerchant.registeredName  String = CONDITIONAL

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

order.subMerchant.tradingName  String = Always Provided

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

order.subMerchant.websiteUrl  Url = CONDITIONAL

The URL of the sub-merchant's website.
Existence
CONDITIONAL
Fixed value
Validation Rules
Ensure that the URL begins with 'https' and is longer than 11 characters.
JSON type
String

order.supply   = CONDITIONAL

Information about orders for items not yet available (pre-order) or for items previously purchased (reorder).
Fixed value

order.supply.preorder  Boolean = CONDITIONAL

Indicates that the purchase includes merchandise with a future availability or release date.
Existence
CONDITIONAL
Fixed value
Validation Rules
JSON boolean values 'true' or 'false'.
JSON type
Boolean

order.supply.preorderAvailabilityDate  Date = CONDITIONAL

The date that preordered items are expected to be available.
Provide this field if the payer is ordering items before you have them available for purchase.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data must comply with ISO 8601 extended date format, yyyy-mm-dd
JSON type
String

order.supply.reorder  Boolean = CONDITIONAL

Indicates that the purchase includes merchandise that the payer has previously ordered.
Existence
CONDITIONAL
Fixed value
Validation Rules
JSON boolean values 'true' or 'false'.
JSON type
Boolean

order.surchargeAmount  Decimal = CONDITIONAL

A fee charged by you to cover the cost of accepting a payment method.
This is an additional amount charged by you for accepting one payment method (e.g. a credit card) instead of another (e.g. cash).
If you provide a surcharge amount, you should include it in the total amount for the order.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data is a decimal number.
JSON type
Number
maximum value
1000000000000
minimum value
0
maximum post-decimal digits
3

order.surchargeSource  Enumeration = CONDITIONAL

Indicates how the surcharge amount was determined for an order.
Existence
CONDITIONAL
Fixed value
Validation Rules
Indicates how the surcharge amount was determined for an order.
JSON type
String
Value must be a member of the following list. The values are case sensitive.
CLIENT
The surcharge amount was provided by the merchant.
GATEWAY
The surcharge amount was calculated by the gateway based on surcharging rules configured by the merchant.

order.tax[n]   = CONDITIONAL

Use this parameter group to provide a breakdown of tax types, amount per tax type, and rate per tax type included in order.taxAmount.
Fixed value

order.tax[n].amount  Decimal = CONDITIONAL

The tax amount included in this order for the tax type.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9 and '.' and represents a valid decimal number.
JSON type
String
minimum length
1
maximum length
14

order.tax[n].rate  Decimal = CONDITIONAL

The tax rate (percentage) used to determine the tax amount included in this order for the tax type.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9 and '.' and represents a valid decimal number.
JSON type
String
minimum length
1
maximum length
6

order.tax[n].type  String = CONDITIONAL

The type of tax included in the order amount.
The correct value as used by your acquirer may have to be provided. Contact your payment service provider for details.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
50

order.taxAmount  Decimal = CONDITIONAL

The total tax amount for the order.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data is a decimal number.
JSON type
Number
maximum value
1000000000000
minimum value
0
maximum post-decimal digits
3

order.taxRegistrationId  String = CONDITIONAL

Your tax registration identifier provided by the Federal/National tax authority (for example, federal tax identification number, ABN).
If you are a Canadian merchant, use this field to provide your Tax Registration ID for paying Harmonized Sales Tax (HST) or Goods and Services Tax (GST) collected by the Canada Revenue Agency.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
30

order.taxStatus  String = CONDITIONAL

Indicates your tax status for this order.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
5
maximum length
20

order.totalAuthorizedAmount  Decimal = Always Provided

The amount that has been successfully authorized for this order.
Existence
Always Provided
Fixed value
Validation Rules
Data is a decimal number.
JSON type
Number
maximum value
1000000000000
minimum value
0
maximum post-decimal digits
3

order.totalCapturedAmount  Decimal = Always Provided

The amount that has been successfully captured for this order.
Existence
Always Provided
Fixed value
Validation Rules
Data is a decimal number.
JSON type
Number
maximum value
1000000000000
minimum value
0
maximum post-decimal digits
3

order.totalRefundedAmount  Decimal = Always Provided

The amount that has been successfully refunded for this order.
Existence
Always Provided
Fixed value
Validation Rules
Data is a decimal number.
JSON type
Number
maximum value
1000000000000
minimum value
0
maximum post-decimal digits
3

order.transactionFiltering   = CONDITIONAL

Information relevant for Transaction Filtering.