Suncorp Gateway API Reference: Operations -
Version 78,
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://suncorp.gateway.mastercard.com/api/rest/version/78/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 exclusively 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.middleName  String = OPTIONAL

Middle 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.customData  String = OPTIONAL

Additional information requested for the agreement which cannot be passed using other available data fields.
This field must not contain sensitive data.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters, but sensitive data will be rejected
JSON type
String
minimum length
1
maximum length
2048

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.minimumAmountPerPayment  Decimal = OPTIONAL

The minimum 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.retailer   = OPTIONAL

For an installment agreement where the payer purchased goods and/or services from a retailer but entered an installment agreement to pay for this purchase with you, you must provide details about the retailer.
Fixed value

agreement.retailer.abbreviatedTradingName  String = OPTIONAL

Provide an abbreviation of the retailer's trading name that can be used by the issuer to indicate the retailer on the payer's statement.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
10

agreement.retailer.merchantCategoryCode  String = OPTIONAL

A 4-digit code used to classify the retailer's business by the type of goods or services it offers.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
4

agreement.retailer.tradingName  String = OPTIONAL

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

agreement.startDate  Date = OPTIONAL

This is the effective start date for the payment agreement.
Cannot be in the past.
Existence
OPTIONAL
Fixed value
Validation Rules
Data must comply with ISO 8601 extended date format, yyyy-mm-dd
JSON type
String

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.
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
You require that the payer is presented with a challenge.
CHALLENGE_PREFERRED
You prefer that the payer is presented with a challenge.
NO_CHALLENGE
You prefer that the payer is not presented with a challenge.
NO_PREFERENCE
You do not have a preference. The issuer may present the payer with a challenge.
REQUEST_TRUSTED_MERCHANT_LISTING
You want the issuer to present the payer with a challenge and invite the payer to add you to the list of trusted merchant for this card. If the payer agrees, the response will contain authentication.psd2.trustedMerchantStatus=ON_LIST. This will allow you to request a trusted merchant exemption the next time you authenticate the payer for a payment with this card.

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

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

externalTokenProvider   = OPTIONAL

Additional information about the external token repository you are configured with.
These fields are MANDATORY for MerchantLink merchants and must not contain sensitive data.
Fixed value

externalTokenProvider.customData  String = OPTIONAL

Provide the site code required to save card details against a token.
For example: '{"siteCode":"BNE"}'.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
4000

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.gratuityAmount  Decimal = OPTIONAL

The amount the payer has chosen to provide as a gratuity or tip in addition to the amount they are paying for the goods or services they are purchasing from you.
The gratuity amount is included in the total amount of the order you provide in 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.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.item[n]   = OPTIONAL

Information about the items the payer purchases with the order.
Fixed value

order.item[n].brand  String = OPTIONAL

The brand of the item.
For example, Dell.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
127

order.item[n].category  String = OPTIONAL

Your category for the item.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
127

order.item[n].description  String = OPTIONAL

Description for the item with information such as size, color, etc.
For example, 'Color:Red, Size:M'
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
127

order.item[n].detail   = OPTIONAL

Only use this parameter group to provide additional line item details required for a better interchange rate for Purchasing Cards, Business and/or Corporate Cards (Level 3).
Check with your payment service provider if Level 3 data is supported for your acquirer.
Fixed value

order.item[n].detail.acquirerCustom  JSON Text = OPTIONAL

Use this field to provide line item details that your acquirer requires you to provide.
Data must be provided in JSON format using the record name and field name (separated by a comma) to identify the value provided. Contact your payment service provider for details about the supported fields including the field definitions.
Existence
OPTIONAL
Fixed value
Validation Rules
Data is valid Json Format
JSON type
String
minimum length
1
maximum length
4000

order.item[n].detail.commodityCode  Digits = OPTIONAL

A code describing a commodity or a group of commodities pertaining to goods classification.
Existence
OPTIONAL
Fixed value
Validation Rules
Data is a number between 1 and 9999999999999999 represented as a string.
JSON type
String

order.item[n].detail.tax[n]   = OPTIONAL

Information about the taxes per line item.
Fixed value

order.item[n].detail.tax[n].amount  Decimal = OPTIONAL

The tax amount for the tax type defined in order.item[n].detail.tax[m].type for the item.
Note that the tax amount provided must reflect the tax amount applied before a discount was applied.
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.item[n].detail.tax[n].rate  Decimal = OPTIONAL

The tax rate (percentage) applied to the item for the tax type defined in order.item[n].detail.tax[m].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.item[n].detail.tax[n].type  String = OPTIONAL

The tax type for which the amount specified under order.item[n].detail.tax[m].amount has been paid for this item.
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
127

order.item[n].detail.unitDiscountRate  Decimal = OPTIONAL

The discount rate (percentage) applied to this item.
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.item[n].detail.unitTaxRate  Decimal = OPTIONAL

The tax rate (percentage) of the tax charged for this item.
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.item[n].detail.unitTaxType  String = OPTIONAL

The type of tax charged for this item.
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
10

order.item[n].detail.unspsc  Digits = OPTIONAL

The United Nations Standard Products and Services Code (UNSPSC) for the item.
Existence
OPTIONAL
Fixed value
Validation Rules
Data is a number between 1 and 9999999999999999 represented as a string.
JSON type
String

order.item[n].detail.upc  Digits = OPTIONAL

The Universal Product Code (UPC) for the item.
Existence
OPTIONAL
Fixed value
Validation Rules
Data is a number between 1 and 9999999999999999 represented as a string.
JSON type
String

order.item[n].image  URI = OPTIONAL

The URL of the item image for display to the payer during the payment interaction.For best results, use images in JPEG or PNG formats.The recommended size is 144 pixels width and 144 pixels height.
The image will be cropped at this height and width.
Existence
OPTIONAL
Fixed value
Validation Rules
Data must be an absolute URI conforming to the URI syntax published by IETF RFC 2396. The URI must be one of the following schemes : https
JSON type
String

order.item[n].industryCategory  Enumeration = OPTIONAL

Provide the industry category to send this line item to your acquirer for specialized processing as industry data.
Such processing might have legal obligations, which are your responsibility. Do not provide an industry category, unless you are certain it applies to you, and is accepted by your acquirer.

We support the following industry standard processing:

US health care processing using the IIAS standard.

The supported values for this field are:

HEALTHCARE_VISION, HEALTHCARE_DENTAL, HEALTHCARE_PRESCRIPTION, HEALTHCARE_OTHER

We formulate an IIAS message by summing the amounts of all the line items with the same industry category. The amount of a line item is computed as:

(order.item.unitPrice + order.item.tax) * order.item.quantity
Existence
OPTIONAL
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
HEALTHCARE_DENTAL
HEALTHCARE_OTHER
HEALTHCARE_PRESCRIPTION
HEALTHCARE_VISION

order.item[n].name  String = COMPULSORY

A short name describing the item.
Existence
COMPULSORY
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
127

order.item[n].quantity  Decimal = COMPULSORY

The quantity of the item.
Existence
COMPULSORY
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9 and '.' and represents a valid decimal number greater than zero.
JSON type
String
minimum length
0
maximum length
30

order.item[n].sku  String = OPTIONAL

The SKU (Stock Keeping Unit) or the item identifier for this item.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
127

order.item[n].unitDiscountAmount  Decimal = OPTIONAL

The discount amount applied to this item.
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.item[n].unitOfMeasure  String = OPTIONAL

The unit of measure used for the item quantity.
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
10

order.item[n].unitPrice  Decimal = COMPULSORY

The cost price for the item.
This amount is multiplied with the item quantity (item.quantity) to determine the total amount for this item (item.amount). This amount does not include the tax amount and/or discount amount applicable to this item.
Existence
COMPULSORY
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.item[n].unitTaxAmount  Decimal = OPTIONAL

The tax amount for the item.
This amount is multiplied with the item quantity (item.quantity) to determine the total tax amount for this item.
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.itemAmount  Decimal = OPTIONAL

The total item 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.unitPrice for all the line items (total item amount).
If you provide both this value and line item data, then the order.itemAmount MUST equal the total item 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.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.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.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.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.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

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

transaction   = OPTIONAL

Information about this transaction.
Fixed value

transaction.merchantNote  String = OPTIONAL

Your note about this transaction.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
250

{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 you create using 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 exclusively 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.middleName  String = CONDITIONAL

Middle 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.customData  String = CONDITIONAL

Additional information requested for the agreement which cannot be passed using other available data fields.
This field must not contain sensitive data.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters, but sensitive data will be rejected
JSON type
String
minimum length
1
maximum length
2048

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.minimumAmountPerPayment  Decimal = CONDITIONAL

The minimum 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.retailer   = CONDITIONAL

For an installment agreement where the payer purchased goods and/or services from a retailer but entered an installment agreement to pay for this purchase with you, you must provide details about the retailer.
Fixed value

agreement.retailer.abbreviatedTradingName  String = CONDITIONAL

Provide an abbreviation of the retailer's trading name that can be used by the issuer to indicate the retailer on the payer's statement.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
10

agreement.retailer.merchantCategoryCode  String = CONDITIONAL

A 4-digit code used to classify the retailer's business by the type of goods or services it offers.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
4

agreement.retailer.tradingName  String = CONDITIONAL

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

agreement.startDate  Date = CONDITIONAL

This is the effective start date for the payment agreement.
Cannot be in the past.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data must comply with ISO 8601 extended date format, yyyy-mm-dd
JSON type
String

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.
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.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
36
maximum length
36

authentication.3ds2.authenticationScheme  String = CONDITIONAL

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

For example, for externally authenticated Mada co-branded transactions, you must provide either MADA, MASTERCARD or VISA to specify the 3DS directory server.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
2
maximum length
50

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.dsReference  String = CONDITIONAL

Reference number assigned to the Directory Server (DS) by EMV Co upon approval of the DS.
This field corresponds to EMVCo field dsReferenceNumber.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
0
maximum length
32

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, JCB JSecure, Discover ProtectBuy 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, JCB JSecure, Discover ProtectBuy 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 this is a valid URL according to RFC 1738.
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

Reference number assigned to the issuer's Access Control Server (ACS) by EMV Co upon approval of the ACS.
This field corresponds to EMVCo field acsReferenceNumber.
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 or TRUSTED_MERCHANT 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.
TRUSTED_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.trustedMerchantStatus  Enumeration = CONDITIONAL

Indicates if the payer has added you to their list of trusted merchants for this card.
The next time you authenticate the payer for a payment with this card you can request the trusted merchant exemption by setting authentication.psd2.exemption to either AUTO or TRUSTED_MERCHANT.
If the issuer grants the exemption the payer will not be presented with a challenge, for example, they may have to enter a one-time password.
Existence
CONDITIONAL
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
NOT_ON_LIST
The payer has not added you to their list of trusted merchants for this card.
ON_LIST
The payer has added you to their list of trusted merchants for this card.

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

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.item[n]   = CONDITIONAL

Information about the items the payer purchases with the order.
Fixed value

order.item[n].brand  String = CONDITIONAL

The brand of the item.
For example, Dell.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
127

order.item[n].category  String = CONDITIONAL

Your category for the item.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
127

order.item[n].description  String = CONDITIONAL

Description for the item with information such as size, color, etc.
For example, 'Color:Red, Size:M'
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
127

order.item[n].detail   = CONDITIONAL

Only use this parameter group to provide additional line item details required for a better interchange rate for Purchasing Cards, Business and/or Corporate Cards (Level 3).
Check with your payment service provider if Level 3 data is supported for your acquirer.
Fixed value

order.item[n].detail.acquirerCustom  JSON Text = CONDITIONAL

Use this field to provide line item details that your acquirer requires you to provide.
Data must be provided in JSON format using the record name and field name (separated by a comma) to identify the value provided. Contact your payment service provider for details about the supported fields including the field definitions.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data is valid Json Format
JSON type
String
minimum length
1
maximum length
4000

order.item[n].detail.commodityCode  Integer = CONDITIONAL

A code describing a commodity or a group of commodities pertaining to goods classification.
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
9999999999999999

order.item[n].detail.tax[n]   = CONDITIONAL

Information about the taxes per line item.
Fixed value

order.item[n].detail.tax[n].amount  Decimal = CONDITIONAL

The tax amount for the tax type defined in order.item[n].detail.tax[m].type for the item.
Note that the tax amount provided must reflect the tax amount applied before a discount was applied.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data is a decimal number.
JSON type
Number
maximum value
1000000000000
minimum value
-1000000000000
maximum post-decimal digits
3

order.item[n].detail.tax[n].rate  Decimal = CONDITIONAL

The tax rate (percentage) applied to the item for the tax type defined in order.item[n].detail.tax[m].type.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data is a decimal number.
JSON type
Number
maximum value
1000000000000
minimum value
-1000000000000
maximum post-decimal digits
3

order.item[n].detail.tax[n].type  String = CONDITIONAL

The tax type for which the amount specified under order.item[n].detail.tax[m].amount has been paid for this item.
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
127

order.item[n].detail.unitDiscountRate  Decimal = CONDITIONAL

The discount rate (percentage) applied to this item.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data is a decimal number.
JSON type
Number
maximum value
999999
minimum value
0
maximum post-decimal digits
5

order.item[n].detail.unitTaxRate  Decimal = CONDITIONAL

The tax rate (percentage) of the tax charged for this item.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data is a decimal number.
JSON type
Number
maximum value
999999
minimum value
0
maximum post-decimal digits
5

order.item[n].detail.unitTaxType  String = CONDITIONAL

The type of tax charged for this item.
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
10

order.item[n].detail.unspsc  Integer = CONDITIONAL

The United Nations Standard Products and Services Code (UNSPSC) for the item.
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
9999999999999999

order.item[n].detail.upc  Integer = CONDITIONAL

The Universal Product Code (UPC) for the item.
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
9999999999999999

order.item[n].industryCategory  Enumeration = CONDITIONAL

Provide the industryCategory to send this line item to your acquirer for specialized processing as industry data.
Such processing might have legal obligations, which are your responsibility. Do not provide an industryCategory, unless you are certain it applies to you, and is accepted by your acquirer.

We support the following industry standard processing:

US health care processing using the IIAS standard.

The supported values for industryCategory are:

HEALTHCARE_VISION, HEALTHCARE_DENTAL, HEALTHCARE_PRESCRIPTION, HEALTHCARE_OTHER

We formulate an IIAS message by summing the amounts of all the line items having the same industryCategory. The amount of a line item is:

(order.item.unitPrice + order.item.tax) * order.item.quantity
Existence
CONDITIONAL
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
HEALTHCARE_DENTAL
HEALTHCARE_OTHER
HEALTHCARE_PRESCRIPTION
HEALTHCARE_VISION

order.item[n].name  String = Always Provided

A short name describing the item.
Existence
Always Provided
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
127

order.item[n].quantity  Decimal = Always Provided

The quantity of the item.
Existence
Always Provided
Fixed value
Validation Rules
Data is a decimal number.
JSON type
Number
maximum value
1000000000000
minimum value
0

order.item[n].sku  String = CONDITIONAL

The SKU (Stock Keeping Unit) or the item identifier for this item.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
127

order.item[n].unitDiscountAmount  Decimal = CONDITIONAL

The discount amount applied to this item.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data is a decimal number.
JSON type
Number
maximum value
1000000000000
minimum value
-1000000000000
maximum post-decimal digits
3

order.item[n].unitOfMeasure  String = CONDITIONAL

The unit of measure used for the item quantity.
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
10

order.item[n].unitPrice  Decimal = Always Provided

The cost price for the item.
This amount is multiplied with the item quantity (item.quantity) to determine the total amount for this item (item.amount). This amount does not include the tax amount and/or discount amount applicable to this item.
Existence
Always Provided
Fixed value
Validation Rules
Data is a decimal number.
JSON type
Number
maximum value
1000000000000
minimum value
-1000000000000
maximum post-decimal digits
3

order.item[n].unitTaxAmount  Decimal = CONDITIONAL

The tax amount for the item.
This amount is multiplied with the item quantity (item.quantity) to determine the total tax amount for this item.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data is a decimal number.
JSON type
Number
maximum value
1000000000000
minimum value
-1000000000000
maximum post-decimal digits
3

order.itemAmount  Decimal = CONDITIONAL

The total item 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.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 this is a valid URL according to RFC 1738.
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 this is a valid URL according to RFC 1738.
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.
Fixed value

order.transactionFiltering.avsResponseCodeRules[n]   = CONDITIONAL

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 = Always Provided

The action to be performed for the Address Verification Service (AVS) Response Code.
Existence
Always Provided
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 = Always Provided

The Address Verification Service (AVS) Response Code for which you are defining the rule.
Existence
Always Provided
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   = CONDITIONAL

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 = CONDITIONAL

The type of value store to which money is being transferred.
The default value is NOT_A_TRANSFER.
Existence
CONDITIONAL
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 = CONDITIONAL

The amount of money being transferred, in units of order.valueTransfer.currency.
The default value is order.amount
Existence
CONDITIONAL
Fixed value
Validation Rules
Data is a decimal number.
JSON type
Number
maximum value
1000000000000000000
minimum value
0
maximum post-decimal digits
12

order.valueTransfer.currency  Upper case alphabetic text = CONDITIONAL

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
CONDITIONAL
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 = CONDITIONAL

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
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
0
maximum value
999

order.walletIndicator  String = CONDITIONAL

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

order.walletProvider  Enumeration = CONDITIONAL

The wallet provider used to collect the customer's payment details used for this transaction.
Existence
CONDITIONAL
Fixed value
Validation Rules
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.
GOOGLE_PAY
Google Pay mobile wallet provider.
MASTERPASS_ONLINE
MasterPass Online wallet provider.
SAMSUNG_PAY
Samsung Pay mobile wallet provider.
VISA_CHECKOUT
Visa Checkout wallet provider.

partnerSolutionId  String = CONDITIONAL

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

response   = Always Provided

Fixed value

response.debugInformation  String = CONDITIONAL

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

response.gatewayCode  Enumeration = Always Provided

Summary of the success or otherwise of the operation.
Existence
Always Provided
Fixed value
Validation Rules
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

response.gatewayRecommendation  Enumeration = CONDITIONAL

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

result  Enumeration = Always Provided

A system-generated high level overall result of the operation.
Existence
Always Provided
Fixed value
Validation Rules
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

shipping   = CONDITIONAL

Shipping information for this order.
Fixed value

shipping.address   = CONDITIONAL

The address to which the goods contained in this order are being shipped.
This data may be used to qualify for better interchange rates on corporate purchase card transactions.
Fixed value

shipping.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

shipping.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

shipping.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

shipping.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

shipping.address.source  Enumeration = CONDITIONAL

How you obtained the shipping address.
Existence
CONDITIONAL
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 = 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

shipping.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

shipping.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

shipping.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

shipping.address.sameAsBilling  Enumeration = CONDITIONAL

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
CONDITIONAL
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.contact   = CONDITIONAL

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

shipping.contact.email  Email = CONDITIONAL

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
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

shipping.contact.firstName  String = CONDITIONAL

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

shipping.contact.lastName  String = CONDITIONAL

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

shipping.contact.mobilePhone  Telephone Number = CONDITIONAL

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
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

shipping.contact.phone  Telephone Number = CONDITIONAL

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
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

shipping.contact.sameAsBilling  Enumeration = CONDITIONAL

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
CONDITIONAL
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 = CONDITIONAL

The shipping method used for delivery of this order
Existence
CONDITIONAL
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 = CONDITIONAL

The post code or zip code of the address the order is shipped from.
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

sourceOfFunds   = CONDITIONAL

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

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

sourceOfFunds.provided   = CONDITIONAL

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

sourceOfFunds.provided.ach   = CONDITIONAL

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

sourceOfFunds.provided.ach.accountType  Enumeration = CONDITIONAL

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

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

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

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

sourceOfFunds.provided.ach.bankAccountHolder  String = CONDITIONAL

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

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

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

sourceOfFunds.provided.ach.routingNumber  Digits = CONDITIONAL

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

Retrieve this information from the payer.

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

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

sourceOfFunds.provided.ach.secCode  Enumeration = CONDITIONAL

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

sourceOfFunds.provided.bancontact   = CONDITIONAL

Additional details related to a Bancontact payment.
Fixed value

sourceOfFunds.provided.bancontact.bankAccountHolder  String = Always Provided

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

sourceOfFunds.provided.blik   = CONDITIONAL

Additional details related to a BLIK browser payment.
Fixed value

sourceOfFunds.provided.blik.bankAccountHolder  String = Always Provided

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

sourceOfFunds.provided.card   = CONDITIONAL

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

sourceOfFunds.provided.card.accountType  Enumeration = CONDITIONAL

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

sourceOfFunds.provided.card.brand  Enumeration = Always Provided

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

sourceOfFunds.provided.card.devicePayment   = CONDITIONAL

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

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

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

You do not need to provide the cryptogram format if you provide the payment token in sourceOfFunds.provided.card.devicePayment.paymentToken
Existence
CONDITIONAL
Fixed value
Validation Rules
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.deviceSpecificExpiry   = CONDITIONAL

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

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

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

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

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

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

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

sourceOfFunds.provided.card.emvRequest  String = CONDITIONAL

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

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

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

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

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

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

sourceOfFunds.provided.card.emvResponse  String = CONDITIONAL

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

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

sourceOfFunds.provided.card.encryption  Enumeration = CONDITIONAL

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

sourceOfFunds.provided.card.expiry   = CONDITIONAL

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

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

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

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

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
Always Provided
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.fundingMethod  Enumeration = Always Provided

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

sourceOfFunds.provided.card.issuer  String = CONDITIONAL

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

sourceOfFunds.provided.card.localBrand  String = CONDITIONAL

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

sourceOfFunds.provided.card.nameOnCard  String = CONDITIONAL

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

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

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

  • Request

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

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

sourceOfFunds.provided.card.pin   = CONDITIONAL

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

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

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

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

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

sourceOfFunds.provided.card.scheme  Enumeration = Always Provided

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

sourceOfFunds.provided.card.sequenceNumber  Digits = CONDITIONAL

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

sourceOfFunds.provided.card.storedOnFile  Enumeration = CONDITIONAL

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

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

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

sourceOfFunds.provided.card.tags  String = CONDITIONAL

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

sourceOfFunds.provided.card.trackDataProvided  Boolean = CONDITIONAL

Indicates whether card track data is provided.
Existence
CONDITIONAL
Fixed value
Validation Rules
JSON boolean values 'true' or 'false'.
JSON type
Boolean

sourceOfFunds.provided.ebt   = CONDITIONAL

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

sourceOfFunds.provided.ebt.accountType  Enumeration = CONDITIONAL

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

sourceOfFunds.provided.ebt.manualAuthorizationCode  Digits = CONDITIONAL

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

sourceOfFunds.provided.ebt.merchantFns  Digits = CONDITIONAL

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

sourceOfFunds.provided.ebt.voucherNumber  Digits = CONDITIONAL

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

sourceOfFunds.provided.enets   = CONDITIONAL

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

sourceOfFunds.provided.enets.bankAccountHolder  String = Always Provided

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

sourceOfFunds.provided.giftCard   = CONDITIONAL

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

sourceOfFunds.provided.giftCard.brand  Enumeration = Always Provided

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

sourceOfFunds.provided.giftCard.localBrand  String = Always Provided

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

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

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

sourceOfFunds.provided.giftCard.pin  Masked digits = CONDITIONAL

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

sourceOfFunds.provided.giftCard.scheme  Enumeration = Always Provided

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

sourceOfFunds.provided.giropay   = CONDITIONAL

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

sourceOfFunds.provided.giropay.bankIdentifier  Digits = CONDITIONAL

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

sourceOfFunds.provided.giropay.bic  Alphanumeric = CONDITIONAL

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

sourceOfFunds.provided.giropay.iban  String = CONDITIONAL

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

sourceOfFunds.provided.grabPay   = CONDITIONAL

Additional details related to GrabPay browser payment.
Fixed value

sourceOfFunds.provided.grabPay.accountHolder  String = Always Provided

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

sourceOfFunds.provided.ideal   = CONDITIONAL

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

sourceOfFunds.provided.ideal.bankAccountHolder  String = CONDITIONAL

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

sourceOfFunds.provided.ideal.bic  Alphanumeric = CONDITIONAL

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

sourceOfFunds.provided.ideal.iban  String = CONDITIONAL

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

sourceOfFunds.provided.openBankingBankTransfer   = CONDITIONAL

Additional details related to Open Banking Bank Transfer.
Fixed value

sourceOfFunds.provided.openBankingBankTransfer.aspspId  String = Always Provided

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

sourceOfFunds.provided.paypal   = CONDITIONAL

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

sourceOfFunds.provided.paypal.accountEmail  Email = CONDITIONAL

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

sourceOfFunds.provided.paypal.accountHolder  String = CONDITIONAL

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

sourceOfFunds.provided.paypal.billingAgreement   = CONDITIONAL

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

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

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

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

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

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

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

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

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

sourceOfFunds.provided.paypal.payerId  String = CONDITIONAL

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

sourceOfFunds.provided.pbba   = CONDITIONAL

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

sourceOfFunds.provided.pbba.paymentRequestId  Digits = CONDITIONAL

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

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

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

sourceOfFunds.provided.poli   = CONDITIONAL

Additional details related to a POLi browser payment.
Fixed value

sourceOfFunds.provided.poli.bankAccountHolder  String = Always Provided

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

sourceOfFunds.provided.przelewy24   = CONDITIONAL

Additional details related to a Przelewy24 browser payment.
Fixed value

sourceOfFunds.provided.przelewy24.bankAccountHolder  String = Always Provided

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

sourceOfFunds.provided.sepa   = CONDITIONAL

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

sourceOfFunds.provided.sepa.bankAccountHolder  String = Always Provided

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

sourceOfFunds.provided.sepa.bic  Alphanumeric = CONDITIONAL

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

sourceOfFunds.provided.sepa.iban  String = Always Provided

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

sourceOfFunds.provided.sofort   = CONDITIONAL

Details about the payer's bank account used for a payment made using Sofortbanking.
The format of the bank account details differs per country.
Fixed value

sourceOfFunds.provided.sofort.bankAccountHolder  String = CONDITIONAL

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

sourceOfFunds.provided.sofort.bankAccountNumber  String = CONDITIONAL

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

sourceOfFunds.provided.sofort.bankIdentifier  String = CONDITIONAL

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

sourceOfFunds.provided.sofort.bic  String = CONDITIONAL

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

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

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

sourceOfFunds.provided.sofort.iban  String = CONDITIONAL

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

sourceOfFunds.provided.trustly   = CONDITIONAL

Additional details related to a Trustly.
Fixed value

sourceOfFunds.provided.trustly.bankAccountHolder  String = Always Provided

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

sourceOfFunds.provided.weChatPay   = CONDITIONAL

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

sourceOfFunds.provided.weChatPay.accountHolder  String = Always Provided

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

sourceOfFunds.token  Alphanumeric = CONDITIONAL

A gateway token that contains account identifier details.
The account identifier details stored against this token will be used to process the request.
If account identifier details are also contained in the request, or the request contains a session with account identifier details, these take precedence over the details stored against the token.
Existence
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
40

sourceOfFunds.tokenRequestorID  Alphanumeric = CONDITIONAL

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

sourceOfFunds.type  Enumeration = CONDITIONAL

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

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

subgatewayMerchant   = CONDITIONAL

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

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

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

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

Fixed value

subgatewayMerchant.acquirer[n]   = Always Provided

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

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

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

subgatewayMerchant.acquirer[n].3DS1   = CONDITIONAL

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

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

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

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

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

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

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

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

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

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

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

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

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

subgatewayMerchant.acquirer[n].amexSafeKey   = CONDITIONAL

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

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

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

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

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

subgatewayMerchant.acquirer[n].fraudRate  Integer = CONDITIONAL

The merchant's fraud rate, as determined by the acquirer, expressed in basis points (bps).
Existence
CONDITIONAL
Fixed value
Validation Rules
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
99999

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

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

subgatewayMerchant.acquirer[n].merchantCategoryCode  Digits = CONDITIONAL

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

subgatewayMerchant.address   = CONDITIONAL

The address of this merchant.
Fixed value

subgatewayMerchant.address.city  String = Always Provided

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

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

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

subgatewayMerchant.address.postcodeZip  String = Always Provided

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

subgatewayMerchant.address.stateProvince  String = Always Provided

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

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

subgatewayMerchant.address.street1  String = Always Provided

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

subgatewayMerchant.address.street2  String = CONDITIONAL

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

subgatewayMerchant.authentication[n]   = CONDITIONAL

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

subgatewayMerchant.authentication[n].3DS2   = CONDITIONAL

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

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

Fixed value

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

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

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

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

subgatewayMerchant.authentication[n].acquirerBIN  Digits = CONDITIONAL

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

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

The protocol used for payer authentication.
Existence
Always Provided
Fixed value
Validation Rules
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
MASTERCARD_SECURECODE
Mastercard SecureCode EMV 3DS authentication
RUPAY
VERIFIED_BY_VISA
Visa Verified by Visa EMV 3DS authentication

subgatewayMerchant.id  Alphanumeric + additional characters = Always Provided

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

subgatewayMerchant.name  String = Always Provided

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

subgatewayMerchant.websiteUrl  Url = Always Provided

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

timeOfLastUpdate  DateTime = CONDITIONAL

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

timeOfRecord  DateTime = CONDITIONAL

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

transaction   = Always Provided

Information about this transaction.
Fixed value

transaction.acquirer.merchantId  String = CONDITIONAL

An identifier allocated by an acquirer to the merchant.
This may also be referred to as the Card Acceptor Identification Code (CAIC), Card Acceptor ID (CAID), or Service Establishment Number (SE Number).
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
127

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

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.merchantNote  String = CONDITIONAL

Your note about this transaction.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
250

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

version  String = CONDITIONAL

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

error   = CONDITIONAL

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

error.cause  Enumeration = CONDITIONAL

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

error.explanation  String = CONDITIONAL

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

error.field  String = CONDITIONAL

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

error.supportCode  String = CONDITIONAL

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

error.validationType  Enumeration = CONDITIONAL

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

result  Enumeration = CONDITIONAL

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

Copyright © 2023 Suncorp