Initiate Authentication

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

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

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

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

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

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

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

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

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

URL https://na.gateway.mastercard.com/api/rest/version/57/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 =INITIATE_AUTHENTICATION FIXED

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

order.currency  Upper case alphabetic text = COMPULSORY

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

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

apiOperation  String =INITIATE_AUTHENTICATION FIXED

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

authentication   = OPTIONAL

For example, using 3-D Secure authentication.

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

correlationId  String = OPTIONAL

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

order   = OPTIONAL

Information about the order associated with this transaction.
Fixed value

order.reference  String = OPTIONAL

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

order.subMerchant   = OPTIONAL

These merchants are referred to as your sub-merchants.

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

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

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

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

order.subMerchant.address   = OPTIONAL

The sub-merchant's address.
Fixed value

order.subMerchant.address.city  String = OPTIONAL

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

order.subMerchant.address.company  String = OPTIONAL

Existence
OPTIONAL
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 = OPTIONAL

Existence
OPTIONAL
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 = OPTIONAL

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.subMerchant.address.stateProvince  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
20

order.subMerchant.address.street  String = OPTIONAL

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.subMerchant.address.street2  String = OPTIONAL

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

order.subMerchant.authentication[n]   = OPTIONAL

For example, using 3-D Secure authentication.
Fixed value

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

These details are used to identify the sub-merchant to the card scheme's directory server.
Fixed value

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

Do not provide this value for Mastercard SecureCode or Verified by Visa. For these authentication schemes, it will be generated by the gateway.
Existence
OPTIONAL
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 = OPTIONAL

Do not provide this value for Mastercard SecureCode or Verified by Visa. For these authentication schemes, it will be generated by the gateway.
Existence
OPTIONAL
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 = COMPULSORY

Existence
COMPULSORY
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
AMEX_SAFEKEY
DINERS_PROTECTBUY
JCB_JSECURE
VERIFIED_BY_VISA

order.subMerchant.bankIndustryCode  Digits = OPTIONAL

You must provide a value if you want the gateway to perform 3-D Secure Version 2 authentication of the payer.
Existence
OPTIONAL
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9.
JSON type
String
minimum length
4
maximum length
4

order.subMerchant.email  Email = OPTIONAL

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

order.subMerchant.identifier  String = COMPULSORY

You can use this identifier in searches and reports in the gateway.
Existence
COMPULSORY
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
100

order.subMerchant.phone  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
20

order.subMerchant.registeredName  String = OPTIONAL

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

order.subMerchant.tradingName  String = COMPULSORY

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

order.subMerchant.websiteUrl  Url = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Ensure that the URL begins with 'https' and is longer than 11 characters.
JSON type
String

order.walletProvider  Enumeration = OPTIONAL

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.

order.currency  Upper case alphabetic text = COMPULSORY

Existence
COMPULSORY
Fixed value
Validation Rules
Data must consist of the characters A-Z
JSON type
String
minimum length
3
maximum length
3

order.merchantCategoryCode  Digits = OPTIONAL

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

order.notificationUrl  Url = OPTIONAL

To receive notifications at this URL, you must enable Webhook notifications in Merchant Administration. Ensure the URL is HTTPS
Existence
OPTIONAL
Fixed value
Validation Rules
Ensure that the URL begins with 'https' and is longer than 11 characters.
JSON type
String

partnerSolutionId  String = OPTIONAL

If your payment service provider has not provided you with a solution ID, you should ignore this field.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
40

session.id  ASCII Text = OPTIONAL

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

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

sourceOfFunds   = OPTIONAL

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

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

sourceOfFunds.provided.card   = OPTIONAL

Details as shown on the card.
Fixed value

sourceOfFunds.provided.card.devicePayment   = OPTIONAL

Use this parameter group when accepting payments using device payment methods such as Apple Pay, Android Pay or Samsung Pay.
Fixed value

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

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

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

You source this field directly from the decrypted payment token.

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

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

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

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

Existence
OPTIONAL
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
3DSECURE
The payment data keys for the online payment cryptogram are provided using the 3-D Secure format.
EMV
The payment data keys for the online payment cryptogram are provided using the EMV format.

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

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.number  Digits = OPTIONAL

On requests, provide the number in the form that you receive it (as explained below). On responses, the gateway populates it with a form that the payer would recognize (also explained in more detail below).

  • Request

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

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

sourceOfFunds.token  Alphanumeric = OPTIONAL

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

sourceOfFunds.type  Enumeration = OPTIONAL

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

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

subgatewayMerchant   = OPTIONAL

This group only applies if you:

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

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

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

Fixed value

subgatewayMerchant.acquirer[n]   = COMPULSORY

A merchant might have one or more acquirers.

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

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

subgatewayMerchant.acquirer[n].3DS1   = OPTIONAL

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

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

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

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

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
24

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

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

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

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
24

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

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

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

Existence
OPTIONAL
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 = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
8

subgatewayMerchant.acquirer[n].acquirerMerchantId  String = COMPULSORY

Existence
COMPULSORY
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
0
maximum length
40

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

Existence
OPTIONAL
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 = OPTIONAL

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
99999

subgatewayMerchant.acquirer[n].id  String = COMPULSORY

Your payment service provider will supply the acquirer names that apply to you.
Existence
COMPULSORY
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
0
maximum length
40

subgatewayMerchant.acquirer[n].merchantCategoryCode  Digits = OPTIONAL

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

subgatewayMerchant.address   = OPTIONAL

The address of this merchant.
Fixed value

subgatewayMerchant.address.city  String = COMPULSORY

Existence
COMPULSORY
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 = COMPULSORY

The value must be a three-letter country code according to ISO 3166-1 alpha-3.
Existence
COMPULSORY
Fixed value
Validation Rules
Data must consist of the characters A-Z
JSON type
String
minimum length
3
maximum length
3

subgatewayMerchant.address.postcodeZip  String = COMPULSORY

Existence
COMPULSORY
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
16

subgatewayMerchant.address.state  String = COMPULSORY

Existence
COMPULSORY
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
30

subgatewayMerchant.address.street1  String = COMPULSORY

Existence
COMPULSORY
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
40

subgatewayMerchant.address.street2  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
40

subgatewayMerchant.authentication[n]   = OPTIONAL

For example, using 3-D Secure authentication.
Fixed value

subgatewayMerchant.authentication[n].3DS2   = OPTIONAL

These details are used to identify the merchant to the card schemes directory server.

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

Fixed value

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

Do not provide this value for Mastercard SecureCode or Verified by Visa, For these authentication schemes, it will be generated by the gateway.
Existence
OPTIONAL
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 = OPTIONAL

Do not provide this value for Mastercard SecureCode or Verified by Visa, For these authentication schemes, it will be generated by the gateway.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
40

subgatewayMerchant.authentication[n].acquirerBIN  Digits = OPTIONAL

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

subgatewayMerchant.authentication[n].protocol  Enumeration = COMPULSORY

Existence
COMPULSORY
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
AMEX_SAFEKEY
DINERS_PROTECTBUY
JCB_JSECURE
MASTERCARD_SECURECODE
RUPAY
VERIFIED_BY_VISA

subgatewayMerchant.id  Alphanumeric + additional characters = COMPULSORY

Existence
COMPULSORY
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 = COMPULSORY

Existence
COMPULSORY
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
100

subgatewayMerchant.websiteUrl  Url = COMPULSORY

You must provide a value if you want the gateway to perform 3-D Secure authentication of the payer.
Existence
COMPULSORY
Fixed value
Validation Rules
Ensure that the URL begins with 'https' and is longer than 11 characters.
JSON type
String

transaction   = OPTIONAL

Information about this transaction.
Fixed value

transaction.reference  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
40

{merchantId}  Alphanumeric + additional characters COMPULSORY

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

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

{transactionid}  String COMPULSORY

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

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.creationTime  DateTime = Always Provided

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

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

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

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

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

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

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

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

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

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

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

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

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
FUNDING
The transaction transfers money to or from the merchant, without the involvement of a payer. For example, recording monthly merchant service fees from your payment service provider.
PAYMENT
Payment (Purchase)
REFUND
Refund
REFUND_REQUEST
Refund Request
VERIFICATION
Verification
VOID_AUTHORIZATION
Void Authorization
VOID_CAPTURE
Void Capture
VOID_PAYMENT
Void Payment
VOID_REFUND
Void Refund

authentication   = CONDITIONAL

For example, using 3-D Secure authentication.
This parameter group include payer authentication options available to you, parameters you need to perform payer authentication for an available method, and the results of payer authentication.
Fixed value

authentication.3ds1   = CONDITIONAL

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

authentication.3ds1.veResEnrolled  Alpha = Always Provided

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

An example of a payer authentication UI is the redirection of the payer's browser to the issuer's Access Control Server (ACS) for 3-D Secure authentication. The gateway supports two models:
  • SIMPLE: The gateway gives you content (HTML and JavaScript) to put on your payment page, and that automatically triggers the authentication user experience.
  • CUSTOMIZED: The gateway gives you the raw parameters for the authentication method, and you create the required user experience yourself.

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

authentication.redirect.customized   = CONDITIONAL

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

authentication.redirect.customized.3DS   = CONDITIONAL

The raw parameters for 3-D Secure authentication.
Fixed value

authentication.redirect.customized.3DS.methodPostData  Base64 = Always Provided

This is used by the issuer's Access Control Server (ACS) to obtain additional information about the payer's browser to assist their risk assessment process. See EMVCo specification for details.
Existence
Always Provided
Fixed value
Validation Rules
Data is Base64 encoded
JSON type
String
minimum length
3
maximum length
1000

authentication.redirect.customized.3DS.methodUrl  Url = CONDITIONAL

See EMVCo specification for details.

Note: To simplify your integration, the gateway will always provide a methodURL that supports the EMVCo specification (even if the issuer's Access Control Server (ACS) does not provide a real one).
Existence
CONDITIONAL
Fixed value
Validation Rules
Ensure that the URL begins with 'https' and is longer than 11 characters.
JSON type
String

authentication.redirectHtml  String = CONDITIONAL

Write this content into an empty <DIV> element being the last element in the <BODY> of your payment page.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
0
maximum length
40960

correlationId  String = CONDITIONAL

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

encryptedData   = CONDITIONAL

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

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

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

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

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

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.authenticationStatus  Enumeration = CONDITIONAL

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.creationTime  DateTime = Always Provided

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

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

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

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.merchantCategoryCode  Digits = CONDITIONAL

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.notificationUrl  Url = CONDITIONAL

To receive notifications at this URL, you must enable Webhook notifications in Merchant Administration. Ensure the URL is HTTPS
Existence
CONDITIONAL
Fixed value
Validation Rules
Ensure that the URL begins with 'https' and is longer than 11 characters.
JSON type
String

order.reference  String = CONDITIONAL

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.status  Enumeration = CONDITIONAL

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

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

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

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

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

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

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

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

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

For example, using 3-D Secure authentication.
Fixed value

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

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

Do not provide this value for Mastercard SecureCode or Verified by Visa. For these authentication schemes, 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

Do not provide this value for Mastercard SecureCode or Verified by Visa. For these authentication schemes, 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

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
DINERS_PROTECTBUY
JCB_JSECURE
VERIFIED_BY_VISA

order.subMerchant.bankIndustryCode  Digits = CONDITIONAL

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.email  Email = CONDITIONAL

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

You can use this identifier in searches and reports in the gateway.
Existence
Always Provided
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
100

order.subMerchant.phone  String = CONDITIONAL

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

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

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

Existence
CONDITIONAL
Fixed value
Validation Rules
Ensure that the URL begins with 'https' and is longer than 11 characters.
JSON type
String

order.totalAuthorizedAmount  Decimal = Always Provided

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

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

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.walletProvider  Enumeration = CONDITIONAL

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.
CHASE_PAY
Chase Pay wallet provider.
GOOGLE_PAY
Google Pay mobile wallet provider.
MASTERPASS_ONLINE
MasterPass Online wallet provider.
SAMSUNG_PAY
Samsung Pay mobile wallet provider.
VISA_CHECKOUT
Visa Checkout wallet provider.

partnerSolutionId  String = CONDITIONAL

If 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

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

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

This field is only present if your gateway configuration supports optional payment features.
Existence
CONDITIONAL
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
ATTEMPT_WITH_AUTHENTICATION
This response will be presented if the gateway fails the request, but you might achieve a different result if you provide payer authentication data.
DO_NOT_PROCEED
Do not proceed using this card. This will be presented if the gateway fails the request, but there is no apparent way for this transaction to succeed.
PROCEED
Proceed with the next step in processing this payment by either: Authenticating the payer using the Authenticate Payer operation or Submitting the payment request as the payer is sufficiently authenticated, or updating card details.

result  Enumeration = Always Provided

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

sourceOfFunds   = CONDITIONAL

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

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

  • 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

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

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

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

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

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

sourceOfFunds.provided.boletoBancario.actionType  Enumeration = CONDITIONAL

Existence
CONDITIONAL
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
WRITE_OFF
Write off the Boleto.

sourceOfFunds.provided.boletoBancario.bankAccountHolder  String = Always Provided

Existence
Always Provided
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
255

sourceOfFunds.provided.boletoBancario.customerType  Enumeration = CONDITIONAL

If the value is not provided it will be defaulted to INDIVIDUAL.
Existence
CONDITIONAL
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
COMPANY
Customer is an organization.
INDIVIDUAL
Customer is an individual.

sourceOfFunds.provided.boletoBancario.daysBeforeAction  Digits = CONDITIONAL

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
2

sourceOfFunds.provided.boletoBancario.dueDate  Date = CONDITIONAL

Existence
CONDITIONAL
Fixed value
Validation Rules
Data must comply with ISO 8601 extended date format, yyyy-mm-dd
JSON type
String

sourceOfFunds.provided.boletoBancario.slipUrl  Url = CONDITIONAL

Existence
CONDITIONAL
Fixed value
Validation Rules
Ensure that the URL begins with 'https' and is longer than 11 characters.
JSON type
String

sourceOfFunds.provided.card   = CONDITIONAL

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

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

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

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

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

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

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

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

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

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

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

This field corresponds to EMV tag 5F24
Fixed value

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

sourceOfFunds.provided.giftCard.brand  Enumeration = Always Provided

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

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

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

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

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

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

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

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

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

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

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

Existence
Always Provided
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
256

sourceOfFunds.provided.oxxo   = CONDITIONAL

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

sourceOfFunds.provided.oxxo.bankAccountHolder  String = Always Provided

Existence
Always Provided
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
255

sourceOfFunds.provided.oxxo.dueDate  Date = CONDITIONAL

Do not provide a due date for USD currency transactions.
Existence
CONDITIONAL
Fixed value
Validation Rules
Data must comply with ISO 8601 extended date format, yyyy-mm-dd
JSON type
String

sourceOfFunds.provided.paypal   = CONDITIONAL

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The format of the bank account details differs per country.
Fixed value

sourceOfFunds.provided.sofort.bankAccountHolder  String = CONDITIONAL

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

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

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

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

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

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

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

sourceOfFunds.provided.weChatPay.accountHolder  String = Always Provided

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

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

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

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.
ALIPAY
The payer selected the payment method Alipay.
BOLETO_BANCARIO
The payer selected the payment method Boleto Bancario.
CARD
Use this value for authentications using the card number.
EBT_CARD
Use this value for Electronic Benefits Transfer (EBT) card payments. The additional EBT data must also be provided in the sourceOfFunds.provided.ebt parameter group.
ENETS
The payer selected the payment method eNETS.
GIFT_CARD
Use this value for gift cards.
GIROPAY
The payer selected the payment method giropay.
IDEAL
The payer selected the payment method iDEAL.
KLARNA
The payer selected the payment method Klarna.
NONE
The transaction transfers money to or from the merchant, without the involvement of a payer. For example, recording monthly merchant service fees from your payment service provider.
OXXO
The payer selected the payment method OXXO.
PAYPAL
The payer selected the payment method PayPal.
POLI
The payer selected the payment method POLi.
SCHEME_TOKEN
Use this value for authentications using scheme tokens.
SEPA
The payer selected the payment method SEPA.
SOFORT
The payer selected the payment method Sofortbanking.
UNION_PAY
The payer selected the payment method UnionPay.
WECHAT_PAY
The payer selected the payment method WeChatPay.

subgatewayMerchant   = CONDITIONAL

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

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

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

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

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

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

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

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

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].countryCode  Upper case alphabetic text = CONDITIONAL

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

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

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

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

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

Existence
Always Provided
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
16

subgatewayMerchant.address.state  String = Always Provided

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

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

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

For example, using 3-D Secure authentication.
Fixed value

subgatewayMerchant.authentication[n].3DS2   = CONDITIONAL

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

Do not provide this value for Mastercard SecureCode or Verified by Visa, For these authentication schemes, 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

Do not provide this value for Mastercard SecureCode or Verified by Visa, For these authentication schemes, 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

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

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
DINERS_PROTECTBUY
JCB_JSECURE
MASTERCARD_SECURECODE
RUPAY
VERIFIED_BY_VISA

subgatewayMerchant.id  Alphanumeric + additional characters = Always Provided

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

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

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 the URL begins with 'https' and is longer than 11 characters.
JSON type
String

timeOfLastUpdate  DateTime = CONDITIONAL

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

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.amount  Decimal = Always Provided

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

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

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

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

Existence
CONDITIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
40

transaction.type  Enumeration = Always Provided

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

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

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

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

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

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

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

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 Mastercard