Authenticate Payer

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

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

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

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

Usage Note

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

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

PUT https://na.gateway.mastercard.com/api/rest/version/57 / merchant / {merchantId} / order / {orderid} / transaction / {transactionid}

Authentication Copied to clipboard

This operation requires authentication via one of the following methods:


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

Request Copied to clipboard

URL Parameters Copied to clipboard

{merchantId} Copied to clipboard Alphanumeric + additional characters REQUIRED

The unique identifier issued to you by your payment provider.


This identifier can be up to 12 characters in length.


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

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

A unique identifier for this order to distinguish it from any other order you create.


Use this identifier when referring to this order in subsequent transactions and in retrieval operations. This value must be unique for every order created by your merchant profile.


Data can consist of any characters

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

Unique identifier for this transaction to distinguish it from any other transaction on the order.


An order can have transactions representing:

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

If you attempt an operation and it fails (eg you try to PAY on a card with no funds), then you need a new id for each retry.


Data can consist of any characters

Min length: 1 Max length: 40

Fields Copied to clipboard

agreement Copied to clipboard OPTIONAL

A series of related orders that execute one commercial agreement.

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

agreement.expiryDate Copied to clipboard Date OPTIONAL

Date at which your agreement with the payer to process payments expires.

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

agreement.id Copied to clipboard String OPTIONAL

Your identifier for the agreement you have with the payer to process payments.

When you collect cards from your payers and store them for later use, you must provide an agreement ID when you use the stored values for:

  • Recurring payments: you have an agreement with the payer that authorizes you to automatically debit their account at agreed intervals for fixed or variable amounts. For example, gym membership, phone bills, or magazine subscriptions.
  • Installment payments: you have an agreement with the payer that authorizes you to process multiple payments over an agreed period of time for a single purchase. For example, the payer purchases an item for $1000 and pays for it in four monthly installments.
  • Unscheduled: you have an agreement with the payer that authorizes you to process future payments when required. For example, the payer authorizes you to process an account top-up transaction for a transit card when the account balance drops below a certain threshold.
When you first establish an agreement with the payer you should also specify the type of agreement in agreement.type.

Data can consist of any characters

Min length: 1 Max length: 100
agreement.recurring Copied to clipboard OPTIONAL

Information about agreements for recurring payments.

agreement.recurring.amountVariability Copied to clipboard Enumeration OPTIONAL

Indicates if all the payments within the agreement use the same amount or if the amount differs between the payments.

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

FIXED

All payments in the recurring payment agreement have the same amount. Examples include magazine subscriptions or gym memberships.

VARIABLE

The amount for the payments within the recurring payment agreement differs between payments. Examples include usage-based charges like utility or phone bills.

agreement.recurring.daysBetweenPayments Copied to clipboard Integer OPTIONAL

The minimum number of days between payments agreed with the payer under your agreement with them.

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

Min value: 1 Max value: 999
agreement.recurring.numberOfPayments Copied to clipboard Integer OPTIONAL

The number of merchant-initiated payments within the recurring payment agreement.

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

Min value: 1 Max value: 9999
agreement.type Copied to clipboard Enumeration OPTIONAL

The type of commercial agreement that the payer has with you.

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

The gateway will use the value you specify for subsequent payments in the series.

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

INSTALLMENT

An agreement where the payer authorizes the payment for a single purchase to be split into a number of payments processed at agreed intervals. For example, pay for a purchase in six monthly installments.

OTHER

An agreement where the merchant wants to link related payments for any purpose other than processing recurring, installment, or unscheduled payments. For example, split tender payments.

RECURRING

An agreement where the payer authorizes the merchant to process payments for recurring bills or invoices at agreed intervals (for example, weekly, monthly). The amount might be fixed or variable.

UNSCHEDULED

An agreement where the payer authorizes the merchant to automatically deduct funds for a payment for an agreed purchase when required (unscheduled). For example, auto top-ups when the account value falls below a threshold.

apiOperation Copied to clipboard String = AUTHENTICATE_PAYER FIXED

Any sequence of zero or more unicode characters.

authentication Copied to clipboard OPTIONAL

Information about how the payer's identity is verified.

For example, using 3-D Secure authentication.

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

authentication.3ds2 Copied to clipboard OPTIONAL

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

authentication.3ds2.sdk Copied to clipboard OPTIONAL

Information provided by the 3-D Secure Software Development Kit (SDK) that is used by an app on the payer's device to enable 3-D Secure authentication of the payer to be performed in-app.

You must populate the fields in this parameter group when you authenticate the payer in-app using 3-D Secure authentication version 2.

authentication.3ds2.sdk.appId Copied to clipboard String REQUIRED

A unique identifier for the app on the payer's device.

The 3-D Secure SDK generates this identifier each time the app is installed or updated.

This field corresponds to EMVCo field sdkAppID

Data can consist of any characters

Min length: 36 Max length: 36
authentication.3ds2.sdk.encryptedData Copied to clipboard String REQUIRED

Information about the payer's device collected and encrypted by the 3-D Secure SDK.

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

This field corresponds to EMVCo field sdkEncData

Data can consist of any characters

Min length: 0 Max length: 64000
authentication.3ds2.sdk.ephemeralPublicKey Copied to clipboard JSON Text REQUIRED

A public key generated by the 3-D Secure SDK.

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

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

This field corresponds to EMVCo field sdkEphemPubKey

Data is valid Json Format

Min length: 0 Max length: 256
authentication.3ds2.sdk.interface Copied to clipboard Enumeration OPTIONAL

The User Interface (UI) formats that the payer's device supports.

These are the formats that can be used to render the screens presented to the payer during an authentication challenge.

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

This field corresponds to EMVCo data element sdkInterface in the field deviceRenderOptions.

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

HTML

The device supports HTML format.

NATIVE

The device supports the UI format native to the payer's device.

authentication.3ds2.sdk.referenceNumber Copied to clipboard String REQUIRED

An identifier of the vendor and version of the 3-D Secure SDK assigned by EMVCo.

This field corresponds to EMVCo field sdkReferenceNumber

Data can consist of any characters

Min length: 1 Max length: 32
authentication.3ds2.sdk.timeout Copied to clipboard Integer OPTIONAL

The duration (in seconds) available to the payer to authenticate.

Will default to 900 if not provided. Note: The value will be rounded up to the nearest minute.

This field corresponds to EMVCo field sdkMaxTimeout

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

Min value: 300 Max value: 900
authentication.3ds2.sdk.transactionId Copied to clipboard String REQUIRED

A unique identifier assigned by the 3-D Secure SDK for the transaction.

This field corresponds to EMVCo field sdkTransID

Data can consist of any characters

Min length: 36 Max length: 36
authentication.3ds2.sdk.uiType Copied to clipboard Comma separated enumeration OPTIONAL

Indicates the UI types which the SDK supports for displaying authentication challenges within the app.

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

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

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

This field corresponds to EMVCo data element sdkUiType in the field deviceRenderOptions.

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

TEXT

The payer is asked to enter text into a field displayed on the UI. For example, ask the payer to enter a One Time Password sent to their registered mobile phone number.

SINGLE_SELECT

The payer is asked to select a single option from a number of presented options. For example, ask the payer if they want a One Time Password to be sent to either their email address or mobile phone number registered with their issuer.

MULTI_SELECT

The payer is asked to select multiple options from a number of presented options. For example, ask the payer to select valid responses to a question.

OUT_OF_BAND

The payer is presented with screens rendered by an out-of-band service during an authentication challenge, For example, the payer is asked to confirm the payment from their banking app.

OTHER_HTML

The payer is presented with an authentication challenge using other mechanisms supported in HTML but not in the native UI format. For example, the payer is asked to confirm an image presented on the screen.

authentication.challengePreference Copied to clipboard Enumeration OPTIONAL

Indicates if you want the payer to be presented with an authentication challenge for this transaction.

You can use this to support local mandates or your risk tolerance. For example, you may prefer that a challenge is always performed when you store card details on file.

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

Note: 'challenge' means requiring the payer to take action to identify themselves, for example, entering a password.

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

CHALLENGE_MANDATED

The merchant requires that the payer is presented with an authentication challenge.

CHALLENGE_PREFERRED

The merchant prefers that the payer is presented with an authentication challenge.

NO_CHALLENGE

The merchant prefers that the payer is not presented with an authentication challenge.

NO_PREFERENCE

The issuer determines whether or not the payer should be presented with an authentication challenge. The merchant does not have a preference.

REQUEST_WHITELISTING

Tells the issuer that you prefer them to present the payer with a challenge and that you want them to invite the payer to add you to their list of trusted merchants. If the payer whitelists you, they can skip authentication for any future payments. You will be able to tell whether the payer has added you to their list of trusted merchants by looking at authentication.psd2.whitelistStatus in the authentication response following the completion of the challenge.

authentication.goodsDescription Copied to clipboard String OPTIONAL

Description of the goods being purchased.

If supported, this description will be displayed on the authentication UI presented to the payer.

Data can consist of any characters

Min length: 0 Max length: 30
authentication.psd2 Copied to clipboard OPTIONAL

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

It provides details about SCA exemptions under PSD2.

authentication.psd2.exemption Copied to clipboard Enumeration OPTIONAL

Indicates why this payment qualifies for exemption from Strong Customer Authentication (SCA) under the Payment Services Directive 2 (PSD2).

Note:

  • For recurring payments provide the RECURRING_PAYMENT value only if the amount is the same. If the amount varies, provide MERCHANT_INITIATED_TRANSACTION instead.

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

LOW_RISK

Exemption is claimed because the acquirer has a low fraud rate.

LOW_VALUE_PAYMENT

Exemption is claimed as the amount is below 30 Euro.

MERCHANT_INITIATED_TRANSACTION

The transaction is excluded as it was initiated by the merchant based on an agreement with the payer. For example, a recurring payment (for a varied or fixed amount), installment payment, or account top-up. In these cases, the payer is not present and cannot participate in an authentication interaction. Merchant initiated transactions are only applicable to subsequent transactions on the order and are out of scope of the PSD2 RTS on Strong Customer Authentication (SCA). The payer must be authenticated during the first transaction that established the agreement.

NONE

An exemption is not claimed for this transaction. The merchant requires Strong Customer Authentication (SCA) be performed.

RECURRING_PAYMENT

The transaction is exempt as it was initiated by the merchant based on an agreement with the payer for a recurring payment for a fixed amount. This value is only applicable to subsequent transactions on the order. In this case, the payer is not present and cannot participate in an authentication interaction. The payer must be authenticated during the first transaction that established the agreement.

SECURE_CORPORATE_PAYMENT

The transaction is exempt as it is a corporate or Business-to-Business (B2B) payment performed using dedicated payment processes and protocols that are not available to consumers and offer at least equivalent security levels.

WHITELISTED_MERCHANT

The transaction is exempt because the payer has added you to the list of their trusted merchants (as maintained by the issuer).

authentication.redirectResponseUrl Copied to clipboard Url OPTIONAL

The URL to which you want to redirect the payer after completing the payer authentication process.

This will be a URL on your website, with the URL encoded as defined in RFC3986. This means special characters such spaces, hyphens, etc must be encoded.

You must provide this URL, unless you are certain that there will be no interaction with the payer.

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

billing Copied to clipboard OPTIONAL

Details of the payer's billing address.

billing.address Copied to clipboard OPTIONAL

The payer's billing address.

This data may be used to qualify for better interchange rates on corporate purchase card transactions.

billing.address.city Copied to clipboard String OPTIONAL

The city portion of the address.

Data can consist of any characters

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

The name of the company associated with this address.

Data can consist of any characters

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

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

Data must consist of the characters A-Z

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

The post code or zip code of the address.

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

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

The state or province of the address.

Data can consist of any characters

Min length: 1 Max length: 20
billing.address.stateProvinceCode Copied to clipboard String OPTIONAL

The three character ISO 3166-2 country subdivision code for the state or province of the address.

Providing this field might improve your payer experience for 3-D Secure payer authentication.

Data can consist of any characters

Min length: 1 Max length: 3
billing.address.street Copied to clipboard String OPTIONAL

The first line of the address.

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

Data can consist of any characters

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

The second line of the address (if provided).

Data can consist of any characters

Min length: 1 Max length: 100
correlationId Copied to clipboard String OPTIONAL

A transient identifier for the request, that can be used to match the response to the request.

The value provided is not validated, does not persist in the gateway, and is returned as provided in the response to the request.

Data can consist of any characters

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

Information associated with the customer's account.

customer.email Copied to clipboard Email OPTIONAL

The email address of the customer.

The field format restriction ensures that the email address is longer than 3 characters and adheres to a generous subset of valid RFC 2822 email addresses.

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

customer.firstName Copied to clipboard String OPTIONAL

The payer's first name.

Data can consist of any characters

Min length: 1 Max length: 50
customer.lastName Copied to clipboard String OPTIONAL

The payer's last or surname.

Data can consist of any characters

Min length: 1 Max length: 50
customer.mobilePhone Copied to clipboard Telephone Number OPTIONAL

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

The number consists of:

  • '+'
  • country code (1, 2 or 3 digits)
  • 'space'
  • national number ( which may embed single spaces characters for readability).

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

Mandatory country code: true Max total digits: 15
customer.phone Copied to clipboard Telephone Number OPTIONAL

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

The number consists of:

  • '+'
  • country code (1, 2 or 3 digits)
  • 'space'
  • national number ( which may embed single spaces characters for readability).

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

Mandatory country code: true Max total digits: 15
device Copied to clipboard OPTIONAL

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

device.browser Copied to clipboard String OPTIONAL

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

You must provide a value in this field if you are performing 3-D Secure authentication of the payer and set authentication.channel = PAYER_BROWSER.

Data can consist of any characters

Min length: 1 Max length: 255
device.browserDetails Copied to clipboard OPTIONAL

Detailed information about the payer's browser.

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

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

device.browserDetails.3DSecureChallengeWindowSize Copied to clipboard Enumeration OPTIONAL

Dimensions of the challenge window (in width x height in pixels) displayed to the payer during 3D-Secure authentication.

This must be provided for authentication operations where authentication.channel is PAYER_BROWSER.

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

250_X_400
390_X_400
500_X_600
600_X_400
FULL_SCREEN
device.browserDetails.acceptHeaders Copied to clipboard String OPTIONAL

The content of the Accept request-header field as sent from the payer's browser.

This is used to determine which content types are supported by the browser.

This must be provided for authentication operations where authentication.channel is PAYER_BROWSER.

Data can consist of any characters

Min length: 1 Max length: 2048
device.browserDetails.colorDepth Copied to clipboard Integer OPTIONAL

The bit depth (in bits per pixel) of the color palette for displaying images.

You obtain this value from the screen.colorDepth property of the payer's browser.

This must be provided for authentication operations where authentication.channel is PAYER_BROWSER.

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

Min value: 1 Max value: 48
device.browserDetails.javaEnabled Copied to clipboard Boolean OPTIONAL

Indicates whether or not the payer's browser supports Java.

You obtain this value from the navigator.javaEnabled property of the payer's browser

This must be provided for authentication operations where authentication.channel is PAYER_BROWSER.

JSON boolean values 'true' or 'false'.

device.browserDetails.javaScriptEnabled Copied to clipboard Boolean OPTIONAL

Indicates whether or not the payer's browser supports JavaScript.

You can determine this by setting the relevant value in a form to false, and then attempting to update it to true using JavaScript.

JSON boolean values 'true' or 'false'.

device.browserDetails.language Copied to clipboard String OPTIONAL

The language supported for the payer's browser as defined in IETF BCP47.

You obtain this value from the navigator.language property of the payer's browser.

This must be provided for authentication operations where authentication.channel is PAYER_BROWSER.

Data can consist of any characters

Min length: 1 Max length: 8
device.browserDetails.screenHeight Copied to clipboard Integer OPTIONAL

The total height of the payer's browser screen in pixels.

You obtain this value from the screen.height property of the payer's browser

This must be provided for authentication operations where authentication.channel is PAYER_BROWSER.

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

Min value: 1 Max value: 999999
device.browserDetails.screenWidth Copied to clipboard Integer OPTIONAL

The total width of the payer's browser screen in pixels.

You obtain this value from the screen.width property of the payer's browser

This must be provided for authentication operations where authentication.channel is PAYER_BROWSER.

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

Min value: 1 Max value: 999999
device.browserDetails.timeZone Copied to clipboard Browser Time Zone Offset OPTIONAL

Time difference between UTC time and the Cardholder browser local time, in minutes.

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

This must be provided for authentication operations where authentication.channel is PAYER_BROWSER.

Browser time zone offset between -840 to +840.

device.ipAddress Copied to clipboard String OPTIONAL

The IP address of the device used by the payer, in nnn.nnn.nnn.nnn format.

Data can consist of any characters

Min length: 7 Max length: 15
order Copied to clipboard REQUIRED

Information about the order associated with this transaction.

order.amount Copied to clipboard Decimal REQUIRED

The total amount for the order. This is the net amount plus any surcharge.

If you provide any sub-total amounts, then the sum of these amounts (order.itemAmount, order.taxAmount, order.shippingAndHandlingAmount, order.cashbackAmount, order.gratuityAmount), minus the order.discountAmount must equal the net amount.

The value of this field in the response is zero if payer funds are not transferred.

Data is a string that consists of the characters 0-9 and '.' and represents a valid decimal number.

Min length: 1 Max length: 14
order.currency Copied to clipboard Upper case alphabetic text REQUIRED

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

Data must consist of the characters A-Z

Min length: 3 Max length: 3
order.supply Copied to clipboard OPTIONAL

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

order.supply.preorder Copied to clipboard Boolean OPTIONAL

Indicates that the purchase includes merchandise with a future availability or release date.

JSON boolean values 'true' or 'false'.

order.supply.preorderAvailabilityDate Copied to clipboard Date OPTIONAL

The date that preordered items are expected to be available.

Provide this field if the payer is ordering items before you have them available for purchase.

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

order.supply.reorder Copied to clipboard Boolean OPTIONAL

Indicates that the purchase includes merchandise that the payer has previously ordered.

JSON boolean values 'true' or 'false'.

order.valueTransfer Copied to clipboard OPTIONAL

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

order.valueTransfer.accountType Copied to clipboard Enumeration OPTIONAL

The type of value store to which money is being transferred.

The default value is NOT_A_TRANSFER.

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

NOT_A_TRANSFER

This payment is not for the purpose of transferring money to another store of value. It is a payment for goods or services.

PREPAID_LOAD

Payment to add funds to a prepaid card or gift card.

QUASI_CASH_TRANSACTION

Payment for items that are directly convertible to cash. For example, money orders, casino gaming chips, or traveller's checks.

order.valueTransfer.amount Copied to clipboard Decimal OPTIONAL

The amount of money being transferred, in units of order.valueTransfer.currency.

The default value is order.amount

Data is a string that consists of the characters 0-9 and '.' and represents a valid decimal number.

Min length: 1 Max length: 14
order.valueTransfer.currency Copied to clipboard Upper case alphabetic text OPTIONAL

The currency of the store.

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

The default value is order.currency.

Data must consist of the characters A-Z

Min length: 3 Max length: 3
order.valueTransfer.numberOfCards Copied to clipboard Integer OPTIONAL

The number of prepaid or gift card being purchased.

The default value is one when you set order.valueTransfer.accountType = PREPAID_LOAD. For all other values of order.valueTransfer.accountType the default is zero.

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

Min value: 0 Max value: 999
order.walletProvider Copied to clipboard Enumeration OPTIONAL

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

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

AMEX_EXPRESS_CHECKOUT

Amex Express Checkout wallet provider.

APPLE_PAY

Apple Pay mobile wallet provider.

CHASE_PAY

Chase Pay wallet provider.

GOOGLE_PAY

Google Pay mobile wallet provider.

MASTERPASS_ONLINE

MasterPass Online wallet provider.

SAMSUNG_PAY

Samsung Pay mobile wallet provider.

SECURE_REMOTE_COMMERCE

Secure Remote Commerce (SRC) wallet provider.

VISA_CHECKOUT

Visa Checkout wallet provider.

session.id Copied to clipboard ASCII Text OPTIONAL

Identifier of the payment session containing values for any of the request fields to be used in this operation.

Values provided in the request will override values contained in the session.

Data consists of ASCII characters

Min length: 31 Max length: 35
session.version Copied to clipboard ASCII Text OPTIONAL

Use this field to implement optimistic locking of the session content.

Do this if you make business decisions based on data from the session and wish to ensure that the same data is being used for the request operation.

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

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

See Making Business Decisions Based on Session Content.

Data consists of ASCII characters

Min length: 10 Max length: 10
shipping Copied to clipboard OPTIONAL

Shipping information for this order.

shipping.address Copied to clipboard OPTIONAL

The address to which this order will be shipped.

shipping.address.city Copied to clipboard String OPTIONAL

The city portion of the address.

Data can consist of any characters

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

The name of the company associated with this address.

Data can consist of any characters

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

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

Data must consist of the characters A-Z

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

The post code or zip code of the address.

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

Min length: 1 Max length: 10
shipping.address.sameAsBilling Copied to clipboard Enumeration OPTIONAL

Indicates whether the shipping address provided is the same as the payer's billing address.

Provide this value if you are not providing the full shipping and billing addresses, but you can affirm that they are the same or different.

The default value for this field is:

SAME - if the shipping and billing address are supplied, and all fields are the same (ignoring non-alphanumerics).
DIFFERENT - if the shipping and billing address are supplied, and at least one field is different (ignoring non-alphanumerics).
UNKNOWN - either shipping address or billing address is absent.

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

DIFFERENT

The shipping and billing addresses are different.

SAME

The shipping and billing addresses are the same.

UNKNOWN

It is not known if the shipping and billing addresses are the same.

shipping.address.source Copied to clipboard Enumeration OPTIONAL

How you obtained the shipping address.

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

ADDRESS_ON_FILE

Order shipped to an address that you have on file.

NEW_ADDRESS

Order shipped to an address provided by the payer for this transaction.

shipping.address.stateProvince Copied to clipboard String OPTIONAL

The state or province of the address.

Data can consist of any characters

Min length: 1 Max length: 20
shipping.address.stateProvinceCode Copied to clipboard String OPTIONAL

The three character ISO 3166-2 country subdivision code for the state or province of the address.

Providing this field might improve your payer experience for 3-D Secure payer authentication.

Data can consist of any characters

Min length: 1 Max length: 3
shipping.address.street Copied to clipboard String OPTIONAL

The first line of the address.

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

Data can consist of any characters

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

The second line of the address (if provided).

Data can consist of any characters

Min length: 1 Max length: 100
shipping.contact Copied to clipboard OPTIONAL

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

shipping.contact.email Copied to clipboard Email OPTIONAL

The contact person's email address.

The field format restriction ensures that the email address is longer than 3 characters and adheres to a generous subset of valid RFC 2822 email addresses.

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

shipping.contact.firstName Copied to clipboard String OPTIONAL

The first name of the person to whom the order is being shipped.

Data can consist of any characters

Min length: 1 Max length: 50
shipping.contact.lastName Copied to clipboard String OPTIONAL

The last name or surname of the person to whom the order is being shipped.

Data can consist of any characters

Min length: 1 Max length: 50
shipping.contact.mobilePhone Copied to clipboard Telephone Number OPTIONAL

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

The number consists of:

  • '+'
  • country code (1, 2 or 3 digits)
  • 'space'
  • national number ( which may embed single spaces characters for readability).

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

Mandatory country code: true Max total digits: 15
shipping.contact.phone Copied to clipboard Telephone Number OPTIONAL

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

The number consists of:

  • '+'
  • country code (1, 2 or 3 digits)
  • 'space'
  • national number ( which may embed single spaces characters for readability).

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

Mandatory country code: true Max total digits: 15
shipping.contact.sameAsBilling Copied to clipboard Enumeration OPTIONAL

Indicates whether the supplied name for the recipient of shipping matches the cardholder name.

Provide this value if you are not providing the full name or cardholder name, but you can affirm that they are the same or different.

Default value is UNKNOWN

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

DIFFERENT

The shipping and billing addresses are different.

SAME

The shipping and billing addresses are the same.

UNKNOWN

It is not known if the shipping and billing addresses are the same.

shipping.method Copied to clipboard Enumeration OPTIONAL

The shipping method used for delivery of this order.

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

ELECTRONIC

Electronic delivery.

GROUND

Ground (4 or more days).

NOT_SHIPPED

Order for goods that are not shipped (for example, travel and event tickets)

OVERNIGHT

Overnight (next day).

PICKUP

Shipped to a local store for pick up.

PRIORITY

Priority (2-3 days).

SAME_DAY

Same day.

shipping.origin.postcodeZip Copied to clipboard Alphanumeric + additional characters OPTIONAL

The post code or zip code of the address the order is shipped from.

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

Min length: 1 Max length: 10
sourceOfFunds Copied to clipboard OPTIONAL

The details describing the source of the funds to be used.

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

sourceOfFunds.provided Copied to clipboard OPTIONAL

Information about the source of funds when it is directly provided (as opposed to via a token or session).

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

sourceOfFunds.provided.card Copied to clipboard OPTIONAL

Details about the card.

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

sourceOfFunds.provided.card.devicePayment Copied to clipboard OPTIONAL

If the payer chose to pay using a device you must provide payment details in this parameter group.

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

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

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

Use this parameter group for:

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

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

The Electronic Commerce Indicator generated for payments made using a device payment method.

You source this field directly from the decrypted payment token.

This field is not applicable for payments using digital wallets or card scheme tokens.

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

Min length: 1 Max length: 2
sourceOfFunds.provided.card.devicePayment.3DSecure.onlinePaymentCryptogram Copied to clipboard Base64 OPTIONAL

A cryptogram used to authenticate the transaction.Use this field for:

  • • Device payments: source this field directly from the decrypted payment token.
  • • Card scheme tokens: source this field directly from the decrypted transaction credentials.

Data is Base64 encoded

Min length: 1 Max length: 128
sourceOfFunds.provided.card.devicePayment.cryptogramFormat Copied to clipboard Enumeration OPTIONAL

The format of the cryptogram provided for the digital payment.Use this field for:

  • • Device payments: provide the cryptogram format when you decrypt the payment token and provide the payment details (including the online payment cryptogram) in the transaction request.

This field does not apply to Card Scheme token payments.

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

3DSECURE

The payment data keys for the online payment cryptogram are provided using the 3-D Secure format.

EMV

The payment data keys for the online payment cryptogram are provided using the EMV format.

sourceOfFunds.provided.card.devicePayment.paymentToken Copied to clipboard String OPTIONAL

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

For example:

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

For Google - this is PaymentMethodToken.getToken().

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

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

Note 2: The gateway will ignore the currency and amount information in the payment token, and will instead use the values passed on the amount and currency fields. For normal usage, you should populate those fields with the exact same values as you got from the SDK.

Data can consist of any characters

Min length: 1 Max length: 16384
sourceOfFunds.provided.card.expiry Copied to clipboard OPTIONAL

Expiry date, as shown on the card.

sourceOfFunds.provided.card.expiry.month Copied to clipboard Digits REQUIRED

Month, as shown on the card.

If using a scheme token this is the token expiry month.
Months are numbered January=1, through to December=12.

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

sourceOfFunds.provided.card.expiry.year Copied to clipboard Digits REQUIRED

Year, as shown on the card.

If using a scheme token this is the token expiry year.
The Common Era year is 2000 plus this value.

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

Min length: 2 Max length: 2
sourceOfFunds.provided.card.number Copied to clipboard Digits OPTIONAL

Credit card number as printed on the card.

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

Min length: 9 Max length: 19
sourceOfFunds.provided.card.securityCode Copied to clipboard Digits OPTIONAL

Card verification code, as printed on the back or front of the card or as provided for a card scheme token.

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

Min length: 3 Max length: 4
sourceOfFunds.token Copied to clipboard Alphanumeric OPTIONAL

Gateway token that uniquely identifies a card and associated details.

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

Min length: 1 Max length: 40

Response Copied to clipboard

Fields Copied to clipboard

agreement Copied to clipboard CONDITIONAL

A series of related orders that execute one commercial agreement.

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

agreement.expiryDate Copied to clipboard Date CONDITIONAL

Date at which your agreement with the payer to process payments expires.

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

agreement.id Copied to clipboard String CONDITIONAL

Your identifier for the agreement you have with the payer to process payments.

When you collect cards from your payers and store them for later use, you must provide an agreement ID when you use the stored values for:

  • Recurring payments: you have an agreement with the payer that authorizes you to automatically debit their account at agreed intervals for fixed or variable amounts. For example, gym membership, phone bills, or magazine subscriptions.
  • Installment payments: you have an agreement with the payer that authorizes you to process multiple payments over an agreed period of time for a single purchase. For example, the payer purchases an item for $1000 and pays for it in four monthly installments.
  • Unscheduled: you have an agreement with the payer that authorizes you to process future payments when required. For example, the payer authorizes you to process an account top-up transaction for a transit card when the account balance drops below a certain threshold.
When you first establish an agreement with the payer you should also specify the type of agreement in agreement.type.

Data can consist of any characters

Min length: 1 Max length: 100
agreement.recurring Copied to clipboard CONDITIONAL

Information about agreements for recurring payments.

agreement.recurring.amountVariability Copied to clipboard Enumeration CONDITIONAL

Indicates if all the payments within the agreement use the same amount or if the amount differs between the payments.

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

FIXED

All payments in the recurring payment agreement have the same amount. Examples include magazine subscriptions or gym memberships.

VARIABLE

The amount for the payments within the recurring payment agreement differs between payments. Examples include usage-based charges like utility or phone bills.

agreement.recurring.daysBetweenPayments Copied to clipboard Integer CONDITIONAL

The minimum number of days between payments agreed with the payer under your agreement with them.

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

Min value: 1 Max value: 999
agreement.recurring.numberOfPayments Copied to clipboard Integer CONDITIONAL

The number of merchant-initiated payments within the recurring payment agreement.

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

Min value: 1 Max value: 9999
agreement.type Copied to clipboard Enumeration CONDITIONAL

The type of commercial agreement that the payer has with you.

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

The gateway will use the value you specify for subsequent payments in the series.

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

INSTALLMENT

An agreement where the payer authorizes the payment for a single purchase to be split into a number of payments processed at agreed intervals. For example, pay for a purchase in six monthly installments.

OTHER

An agreement where the merchant wants to link related payments for any purpose other than processing recurring, installment, or unscheduled payments. For example, split tender payments.

RECURRING

An agreement where the payer authorizes the merchant to process payments for recurring bills or invoices at agreed intervals (for example, weekly, monthly). The amount might be fixed or variable.

UNSCHEDULED

An agreement where the payer authorizes the merchant to automatically deduct funds for a payment for an agreed purchase when required (unscheduled). For example, auto top-ups when the account value falls below a threshold.

authentication Copied to clipboard CONDITIONAL

Information about how the payer's identity is verified.

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

authentication.3ds Copied to clipboard CONDITIONAL

Information about payer authentication using 3-D Secure authentication.

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

Depending on the 3-D Secure authentication version applicable you will also need additional parameters:

  • 3-D Secure authentication version 1: see the authentication.3ds1 parameter group.
  • 3-D Secure authentication version 2: see the authentication.3ds2 parameter group.

authentication.3ds.acsEci Copied to clipboard Alphanumeric CONDITIONAL

Indicates the security level of the transaction.

This is the Electronic Commerce Indicator (ECI) value provided by the issuer's Access Control Server (ACS) to indicate the results of the attempt to authenticate the payer.

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

Min length: 1 Max length: 2
authentication.3ds.authenticationToken Copied to clipboard Base64 CONDITIONAL

The base64 encoded value generated by the issuer.

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

For 3DS version 2, this field corresponds to the Authentication Value.

Data is Base64 encoded

allowable lengths 28 or 32
authentication.3ds.transactionId Copied to clipboard String CONDITIONAL

A unique identifier for the 3-D Secure authentication transaction.

For 3DS version 1, this field corresponds to the XID. The XID is an identifier generated by the gateway on behalf of the merchant.

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


This identifier should be used in subsequent operation requests unaltered.

An XID submitted in this field must be in base64 format.

Data can consist of any characters

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

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

authentication.3ds1.paResStatus Copied to clipboard Alpha CONDITIONAL

Indicates the result of payer authentication with the issuer.

This is the value returned in the transaction status field of the Payer Authentication Response (PARes) message from the card Issuer's Access Control Server (ACS). For example, Y, N, A, or U. Refer to the relevant documentation for Mastercard SecureCode™, Verified by Visa™, JCB J/Secure™, American Express SafeKey™, or Diners Club ProtectBuy™.

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

Min length: 1 Max length: 1
authentication.3ds1.veResEnrolled Copied to clipboard Alpha ALWAYS PROVIDED

Indicates whether or not payer authentication is available for the card number you provided.

This is for experts only - most users should use the response.gatewayRecommendation field.

This is the value returned in the 'enrolled' field of the Verify Enrollment Response (VERes) message from the card scheme's Directory Server. For example, Y, N, or U. Refer to the relevant documentation for Mastercard SecureCode™, Verified by Visa™, JCB J/Secure™, American Express SafeKey™, or Diners Club ProtectBuy™.

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

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

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

authentication.3ds2.acsTransactionId Copied to clipboard String CONDITIONAL

A unique transaction identifier assigned by the Access Control Server to identify the 3DS transaction.

The ACS transaction id should be used in subsequent operation requests unaltered.

Data can consist of any characters

Min length: 36 Max length: 36
authentication.3ds2.directoryServerId Copied to clipboard String CONDITIONAL

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

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

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

Data can consist of any characters

Min length: 10 Max length: 10
authentication.3ds2.dsTransactionId Copied to clipboard String CONDITIONAL

A unique transaction identifier assigned by the scheme Directory Server to identify the 3DS transaction.

The DS transaction id should be used in subsequent operation requests unaltered.

Data can consist of any characters

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

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

JSON boolean values 'true' or 'false'.

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

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

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

NOT_SUPPORTED

The ACS does not support the method call protocol.

SUPPORTED

The ACS supports the method call protocol.

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

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

For example, 2.1.0.

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

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

The unique identifier assigned to the merchant by the card scheme directory server when the merchant registered to use 3-D Secure authentication version 2 with their acquirer.

Do not provide this value for Mastercard SecureCode or Verified by Visa, For these authentication schemes, it will be generated by the gateway.

Data can consist of any characters

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

The unique name assigned to the merchant by the card scheme directory server when the merchant registered to use 3-D Secure authentication version 2 with their acquirer.

Do not provide this value for Mastercard SecureCode or Verified by Visa, For these authentication schemes, it will be generated by the gateway.

Data can consist of any characters

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

Information provided by the 3-D Secure Software Development Kit (SDK) that is used by an app on the payer's device to enable 3-D Secure authentication of the payer to be performed in-app.

You must populate the fields in this parameter group when you authenticate the payer in-app using 3-D Secure authentication version 2.

authentication.3ds2.sdk.challengeCompletionCallbackUrl Copied to clipboard Url CONDITIONAL

This value is only returned when you authenticate the payer in-app using 3-D Secure authentication version 2 and a challenge is required (authentication.channel = PAYER_APP and authentication.3ds2.transactionStatus = C).

You must call this URL after the challenge has been completed; for example, when the ACS has confirmed the challenge completion.
This allows the gateway to retrieve the authentication result after the challenge has been completed.

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

authentication.3ds2.sdk.interface Copied to clipboard Enumeration CONDITIONAL

The User Interface (UI) formats that the payer's device supports.

These are the formats that can be used to render the screens presented to the payer during an authentication challenge.

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

This field corresponds to EMVCo data element sdkInterface in the field deviceRenderOptions.

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

HTML

The device supports HTML format.

NATIVE

The device supports the UI format native to the payer's device.

authentication.3ds2.sdk.timeout Copied to clipboard Integer CONDITIONAL

The duration (in seconds) available to the payer to authenticate.

Will default to 900 if not provided. Note: The value will be rounded up to the nearest minute.

This field corresponds to EMVCo field sdkMaxTimeout

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

Min value: 300 Max value: 900
authentication.3ds2.sdk.uiType Copied to clipboard Comma separated enumeration CONDITIONAL

Indicates the UI types which the SDK supports for displaying authentication challenges within the app.

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

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

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

This field corresponds to EMVCo data element sdkUiType in the field deviceRenderOptions.

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

TEXT

The payer is asked to enter text into a field displayed on the UI. For example, ask the payer to enter a One Time Password sent to their registered mobile phone number.

SINGLE_SELECT

The payer is asked to select a single option from a number of presented options. For example, ask the payer if they want a One Time Password to be sent to either their email address or mobile phone number registered with their issuer.

MULTI_SELECT

The payer is asked to select multiple options from a number of presented options. For example, ask the payer to select valid responses to a question.

OUT_OF_BAND

The payer is presented with screens rendered by an out-of-band service during an authentication challenge, For example, the payer is asked to confirm the payment from their banking app.

OTHER_HTML

The payer is presented with an authentication challenge using other mechanisms supported in HTML but not in the native UI format. For example, the payer is asked to confirm an image presented on the screen.

authentication.3ds2.statusReasonCode Copied to clipboard String CONDITIONAL

A code indicating the reason for the transaction status returned in authentication.3ds2.transactionStatus.

Refer to the EMVCo specification for 3-D Secure.

Data can consist of any characters

Min length: 2 Max length: 2
authentication.3ds2.transactionStatus Copied to clipboard Alpha CONDITIONAL

Indicates the result of payer authentication with the issuer.

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

Refer to the EMVCo specification for 3-D Secure.

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

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

Unique identifier assigned to the issuer's Access Control Server (ACS) by the EMVCo.

This field corresponds to EMVCo field acsRefNumber.

Data can consist of any characters

Min length: 0 Max length: 32
authentication.3ds2.challenge Copied to clipboard CONDITIONAL

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

authentication.3ds2.challenge.signedContent Copied to clipboard String CONDITIONAL

A JSON Web Signature (JWS) object returned by the issuer's Access Control Server (ACS).

Use this field to validate the integrity of the information returned.

The body of the object contains the following data:

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

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

This field corresponds to EMVCo field acsSignedContent.

Data can consist of any characters

Min length: 0 Max length: 16384
authentication.method Copied to clipboard Enumeration CONDITIONAL

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

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

DYNAMIC

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

OUT_OF_BAND

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

STATIC

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

authentication.payerInteraction Copied to clipboard Enumeration ALWAYS PROVIDED

Indicates if payer interaction was used to complete the authentication process.

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

NOT_POSSIBLE

Payer interaction was either not possible or not applicable to completing the authentication process. For example, there was a technical problem, or the authentication method is not supported for this payment method.

NOT_REQUIRED

No payer interaction was required to complete the authentication process. The issuer was able to make a decision based on the data provided.

REQUIRED

Payer interaction was required to complete the authentication process. For example, the payer was presented with a challenge to verify their identity.

authentication.psd2 Copied to clipboard CONDITIONAL

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

It provides details about SCA exemptions under PSD2.

authentication.psd2.exemption Copied to clipboard Enumeration CONDITIONAL

Indicates why this payment qualifies for exemption from Strong Customer Authentication (SCA) under the Payment Services Directive 2 (PSD2).

Note:

  • For recurring payments provide the RECURRING_PAYMENT value only if the amount is the same. If the amount varies, provide MERCHANT_INITIATED_TRANSACTION instead.

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

LOW_RISK

Exemption is claimed because the acquirer has a low fraud rate.

LOW_VALUE_PAYMENT

Exemption is claimed as the amount is below 30 Euro.

MERCHANT_INITIATED_TRANSACTION

The transaction is excluded as it was initiated by the merchant based on an agreement with the payer. For example, a recurring payment (for a varied or fixed amount), installment payment, or account top-up. In these cases, the payer is not present and cannot participate in an authentication interaction. Merchant initiated transactions are only applicable to subsequent transactions on the order and are out of scope of the PSD2 RTS on Strong Customer Authentication (SCA). The payer must be authenticated during the first transaction that established the agreement.

NONE

An exemption is not claimed for this transaction. The merchant requires Strong Customer Authentication (SCA) be performed.

RECURRING_PAYMENT

The transaction is exempt as it was initiated by the merchant based on an agreement with the payer for a recurring payment for a fixed amount. This value is only applicable to subsequent transactions on the order. In this case, the payer is not present and cannot participate in an authentication interaction. The payer must be authenticated during the first transaction that established the agreement.

SECURE_CORPORATE_PAYMENT

The transaction is exempt as it is a corporate or Business-to-Business (B2B) payment performed using dedicated payment processes and protocols that are not available to consumers and offer at least equivalent security levels.

WHITELISTED_MERCHANT

The transaction is exempt because the payer has added you to the list of their trusted merchants (as maintained by the issuer).

authentication.psd2.whitelistStatus Copied to clipboard Enumeration CONDITIONAL

Indicates if the payer has whitelisted you with the issuer and has opted-out of Strong Customer Authentication (SCA).

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

NOT_WHITELISTED

The payer has not whitelisted the merchant with the issuer or the merchant's whitelist status is unknown.

WHITELISTED

The payer has whitelisted the merchant with the issuer.

authentication.redirect Copied to clipboard CONDITIONAL

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

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

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

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

authentication.redirect.customized Copied to clipboard CONDITIONAL

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

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

The raw parameters for 3-D Secure authentication.

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

The URL of the issuer's Access Control Server (ACS) where payer authentication is performed.

Applicable: 3DS version 1 and 3DS version 2

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

authentication.redirect.customized.3DS.cReq Copied to clipboard ASCII Text CONDITIONAL

Base64 URL encoded CReq message, only returned for challenge transactions during browser flow.

Applicable: 3DS version 2

Data consists of ASCII characters

Min length: 0 Max length: 4000
authentication.redirect.domainName Copied to clipboard String CONDITIONAL

The domain name of the site where payer authentication was performed.

For example, the domain-name of the issuer's Access Control Server (ACS) used for payer authentication using 3-D Secure authentication.

Data can consist of any characters

Min length: 1 Max length: 253
authentication.redirectHtml Copied to clipboard String CONDITIONAL

Code to create the authentication UI.

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

Data can consist of any characters

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

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

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

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

3DS1

3-D Secure Version 1 authentication is available.

3DS2

3-D Secure Version 2 authentication is available.

RUPAY

RuPay authentication is available.

NONE

No authentication is available.

billing Copied to clipboard CONDITIONAL

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

billing.address Copied to clipboard CONDITIONAL

The payer's billing address.

This data may be used to qualify for better interchange rates on corporate purchase card transactions.

billing.address.city Copied to clipboard String CONDITIONAL

The city portion of the address.

Data can consist of any characters

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

The name of the company associated with this address.

Data can consist of any characters

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

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

Data must consist of the characters A-Z

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

The post code or zip code of the address.

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

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

The state or province of the address.

Data can consist of any characters

Min length: 1 Max length: 20
billing.address.stateProvinceCode Copied to clipboard String CONDITIONAL

The three character ISO 3166-2 country subdivision code for the state or province of the address.

Providing this field might improve your payer experience for 3-D Secure payer authentication.

Data can consist of any characters

Min length: 1 Max length: 3
billing.address.street Copied to clipboard String CONDITIONAL

The first line of the address.

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

Data can consist of any characters

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

The second line of the address (if provided).

Data can consist of any characters

Min length: 1 Max length: 100
correlationId Copied to clipboard String CONDITIONAL

A transient identifier for the request, that can be used to match the response to the request.

The value provided is not validated, does not persist in the gateway, and is returned as provided in the response to the request.

Data can consist of any characters

Min length: 1 Max length: 100
customer Copied to clipboard CONDITIONAL

Information about the customer, including their contact details.

customer.email Copied to clipboard Email CONDITIONAL

The email address of the customer.

The field format restriction ensures that the email address is longer than 3 characters and adheres to a generous subset of valid RFC 2822 email addresses.

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

customer.firstName Copied to clipboard String CONDITIONAL

The payer's first name.

Data can consist of any characters

Min length: 1 Max length: 50
customer.lastName Copied to clipboard String CONDITIONAL

The payer's last or surname.

Data can consist of any characters

Min length: 1 Max length: 50
customer.mobilePhone Copied to clipboard String CONDITIONAL

The contact person's mobile phone or cell phone number.

Data can consist of any characters

Min length: 1 Max length: 20
customer.phone Copied to clipboard String CONDITIONAL

The phone number of the person to whom the order is being billed.

Data can consist of any characters

Min length: 1 Max length: 20
device Copied to clipboard CONDITIONAL

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

device.browser Copied to clipboard String CONDITIONAL

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

You must provide a value in this field if you are performing 3-D Secure authentication of the payer and set authentication.channel = PAYER_BROWSER.

Data can consist of any characters

Min length: 1 Max length: 255
device.ipAddress Copied to clipboard String CONDITIONAL

The IP address of the device used by the payer, in nnn.nnn.nnn.nnn format.

Data can consist of any characters

Min length: 7 Max length: 15
encryptedData Copied to clipboard CONDITIONAL

This group is an encrypted JSON object containing authentication data obtained during the authentication process.

You can ignore this group if you are making a subsequent payment or Verify operation with the gateway, instead just rely on the response.gatewayRecommendation field.

However this group is applicable if:

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

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

encryptedData.ciphertext Copied to clipboard String ALWAYS PROVIDED

Base64 encoded ciphertext.

Data can consist of any characters

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

Base64 encoded GCM nonce.

Data can consist of any characters

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

Base64 encoded GCM tag.

Data can consist of any characters

Min length: 24 Max length: 24
lineOfBusiness Copied to clipboard String CONDITIONAL

Your payment service provider might have configured your merchant profile to support several lines of business.

Each line of business can have different payment parameters, such as bank account, supported cards or such.

For example, lineOfBusiness = TICKET_SALES can have a different bank account from lineOfBusiness = MERCHANDISING. One line of business on your profile might be "null". To use that, do not provide the lineOfBusiness field.

Data can consist of any characters except space

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

The unique identifier issued to you by your payment provider.

This identifier can be up to 12 characters in length.

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

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

Information about the order associated with this transaction.

order.amount Copied to clipboard Decimal ALWAYS PROVIDED

The total amount for the order. This is the net amount plus any surcharge.

If you provide any sub-total amounts, then the sum of these amounts (order.itemAmount, order.taxAmount, order.shippingAndHandlingAmount, order.cashbackAmount, order.gratuityAmount), minus the order.discountAmount must equal the net amount.

The value of this field in the response is zero if payer funds are not transferred.

Data is a decimal number.

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

Indicates the result of payer authentication.

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

AUTHENTICATION_ATTEMPTED

Payer authentication was attempted and a proof of authentication attempt was obtained.

AUTHENTICATION_AVAILABLE

Payer authentication is available for the payment method provided.

AUTHENTICATION_EXEMPT

Exemption from the Regulatory Technical Standards (RTS) requirements for Strong Customer Authentication (SCA) under the Payment Services Directive 2 (PSD2) regulations in the European Economic Area has been claimed or granted.

AUTHENTICATION_FAILED

The payer was not authenticated. You should not proceed with this transaction.

AUTHENTICATION_NOT_IN_EFFECT

There is no authentication information associated with this transaction.

AUTHENTICATION_NOT_SUPPORTED

The requested authentication method is not supported for this payment method.

AUTHENTICATION_PENDING

Payer authentication is pending completion of a challenge process.

AUTHENTICATION_REJECTED

The issuer rejected the authentication request and requested that you do not attempt authorization of a payment.

AUTHENTICATION_REQUIRED

Payer authentication is required for this payment, but was not provided.

AUTHENTICATION_SUCCESSFUL

The payer was successfully authenticated.

AUTHENTICATION_UNAVAILABLE

The payer was not able to be authenticated due to a technical or other issue.

order.creationTime Copied to clipboard DateTime ALWAYS PROVIDED

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

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

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

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

Data must consist of the characters A-Z

Min length: 3 Max length: 3
order.id Copied to clipboard String ALWAYS PROVIDED

A unique identifier for this order to distinguish it from any other order you create.

Use this identifier when referring to this order in subsequent transactions and in retrieval operations. This value must be unique for every order created by your merchant profile.

Data can consist of any characters

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

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

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

order.merchantCategoryCode Copied to clipboard Digits CONDITIONAL

A 4-digit code used to classify your business by the type of goods or services it offers.This is also known as the Merchant Category Code (MCC).

You only need to provide the MCC if you want to override the default value configured for your acquirer link.The value you provide must match one of those configured by your payment service provider.

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

Min length: 4 Max length: 4
order.notificationUrl Copied to clipboard Url CONDITIONAL

The URL to which the gateway will send Webhook notifications when an order is created or updated.

To receive notifications at this URL, you must enable Webhook notifications in Merchant Administration. Ensure the URL is HTTPS

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

order.reference Copied to clipboard String CONDITIONAL

An optional identifier for the order.

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

Data can consist of any characters

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

The current progression of this order through the payment process.

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

AUTHENTICATED

The payer was successfully authenticated.

AUTHENTICATION_INITIATED

Payer authentication has been initiated but not completed.

AUTHENTICATION_NOT_NEEDED

Payer authentication was not performed as it was not needed.

AUTHENTICATION_UNSUCCESSFUL

Payer authentication was not able to be successfully completed.

AUTHORIZED

The payment has been authorized successfully but the authorized amount has not yet been captured, in part, full, or excess.

CANCELLED

The initial transaction for this order has been voided successfully.

CAPTURED

The authorized amount for this order, in full or excess, has been captured successfully.

CHARGEBACK_PROCESSED

A Chargeback has been processed against this order.

DISPUTED

The payment has been disputed and is under investigation. A request for information has been received or a chargeback is pending.

EXCESSIVELY_REFUNDED

The payment has been captured in part, full, or excess, but the captured amount in excess has been refunded successfully.

FAILED

The payment has not been successful.

FUNDING

The order transfers money to or from the merchant, without the involvement of a payer. For example, recording monthly merchant service fees from your payment service provider.

INITIATED

A browser payment that has successfully been initiated for this order. No payment has yet been made.

PARTIALLY_CAPTURED

The authorized amount for this order, in part, has been captured successfully.

PARTIALLY_REFUNDED

The payment has been captured in part, full, or excess, but the captured amount in part has been refunded successfully.

REFUNDED

The payment has been captured in part, full, or excess, but the captured amount in full has been refunded successfully.

REFUND_REQUESTED

A refund against captured amounts on this order has been requested but not executed. Requires further action to approve the refund.

VERIFIED

The card details for this order have successfully been verified. No payment has yet been initiated or made.

order.subMerchant Copied to clipboard CONDITIONAL

Provide these parameters if you are a payment aggregator or facilitator and process payments on behalf of other merchants.

These merchants are referred to as your sub-merchants.

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

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

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

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

order.subMerchant.address Copied to clipboard CONDITIONAL

The sub-merchant's address.

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

The city portion of the address.

Data can consist of any characters

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

The name of the company associated with this address.

Data can consist of any characters

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

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

Data must consist of the characters A-Z

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

The post code or zip code of the address.

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

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

The state or province of the address.

Data can consist of any characters

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

The first line of the address.

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

Data can consist of any characters

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

The second line of the address (if provided).

Data can consist of any characters

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

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

For example, using 3-D Secure authentication.

order.subMerchant.authentication[n].3DS2 Copied to clipboard CONDITIONAL

Information about the sub-merchant's registration to use 3-D Secure authentication version 2.

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

order.subMerchant.authentication[n].3DS2.requestorId Copied to clipboard String CONDITIONAL

The unique identifier assigned to the merchant by the card scheme directory server when the merchant registered to use 3-D Secure authentication version 2 with their acquirer.

Do not provide this value for Mastercard SecureCode or Verified by Visa. For these authentication schemes, it will be generated by the gateway.

Data can consist of any characters

Min length: 1 Max length: 35
order.subMerchant.authentication[n].3DS2.requestorName Copied to clipboard String CONDITIONAL