Authenticate Payer
Request to authenticate a payer, i.e. verify the identity of a cardholder. You can subsequently use the resulting authentication data when submitting a financial transaction request to prove that you have performed payer authentication.
You must first invoke the Initiate Authentication operation and where the response indicates that payer authentication is available, you must then invoke the Authenticate Payer operation with the same orderId and transactionId submitted on the Initiate Authentication operation.
To increase the likelihood of the authentication being successful, provide as much information about the payer and the transaction as possible.
If the information in the request is sufficient to allow the authentication scheme to confirm the payer's identity the response will include the authentication data (frictionless flow). Alternatively (challenge flow), it may be necessary for the payer to interact with the authentication scheme to confirm their identity (e.g. by providing a one-time password sent to them by their card issuer). In this case the response will contain an HTML excerpt that you must inject into your page. This will establish the interaction between the payer and the authentication scheme. After authentication has been completed the payer will be redirected back to your website using the URL provided by you in field authentication.redirectResponseUrl in the Authenticate Payer request.
If you are authenticating the payer when establishing a payment agreement with your payer for a series of recurring, installment or unscheduled payments you must provide details about the agreement in the agreement parameter group.
Usage Note
Using the Initiate Authenticate and Authenticate Payer operations for 3-D Secure authentication requires you to manage a variety of authentication flows and understand the 3-D Secure version 2 data flows as published by EMVCo.
A more simple alternatively is to use the gateway's threeDS.js library.
URL | https://test-nbkpayment.mtf.gateway.mastercard.com/api/rest/version/81/merchant/{merchantId}/order/{orderid}/transaction/{transactionid} |
HTTP Method | PUT |
Authentication |
This operation requires authentication via one of the following methods:
|
Request Parameters
apiOperation String =AUTHENTICATE_PAYER FIXED
order = COMPULSORY
order.amount Decimal = OPTIONAL
order.currency Upper case alphabetic text = COMPULSORY
session.id ASCII Text = OPTIONAL
accountFunding = OPTIONAL
accountFunding.purpose Enumeration = OPTIONAL
accountFunding.recipient = OPTIONAL
accountFunding.recipient.account = OPTIONAL
accountFunding.recipient.account.fundingMethod Enumeration = OPTIONAL
accountFunding.recipient.account.identifier String = OPTIONAL
accountFunding.recipient.account.identifierType Enumeration = OPTIONAL
accountFunding.recipient.country Upper case alphabetic text = OPTIONAL
accountFunding.recipient.dateOfBirth Date = OPTIONAL
accountFunding.recipient.firstName String = OPTIONAL
accountFunding.recipient.lastName String = OPTIONAL
accountFunding.recipient.middleName String = OPTIONAL
accountFunding.recipient.postCodeZip String = OPTIONAL
accountFunding.recipient.stateProvinceCode String = OPTIONAL
accountFunding.senderIsRecipient Boolean = OPTIONAL
accountFunding.senderType Enumeration = OPTIONAL
agreement = OPTIONAL
Do not provide this parameter group if you are storing the payment details for subsequent payer-initiated payments only.
See Credential on File, Cardholder, and Merchant Initiated Transactions for details.
agreement.amountVariability Enumeration = OPTIONAL
agreement.customData String = OPTIONAL
agreement.expiryDate Date = OPTIONAL
agreement.id String = OPTIONAL
- Recurring payments: you have an agreement with the payer that authorizes you to automatically debit their account at agreed intervals for fixed or variable amounts. For example, gym membership, phone bills, or magazine subscriptions.
- Installment payments: you have an agreement with the payer that authorizes you to process multiple payments over an agreed period of time for a single purchase. For example, the payer purchases an item for $1000 and pays for it in four monthly installments.
- Unscheduled: you have an agreement with the payer that authorizes you to process future payments when required. For example, the payer authorizes you to process an account top-up transaction for a transit card when the account balance drops below a certain threshold.
- Industry Practice: you have an agreement with the payer that authorizes you to initiate additional transactions to fulfil a standard business practice related to an original payment initiated by the payer. For example, a delayed charge for use of the hotel mini bar after the payer has checked out or a no show penalty charge when the payer fails to show for a booking.
agreement.maximumAmountPerPayment Decimal = OPTIONAL
agreement.minimumAmountPerPayment Decimal = OPTIONAL
agreement.minimumDaysBetweenPayments Integer = OPTIONAL
agreement.numberOfPayments Integer = OPTIONAL
agreement.paymentFrequency Enumeration = OPTIONAL
agreement.retailer = OPTIONAL
agreement.retailer.abbreviatedTradingName String = OPTIONAL
agreement.retailer.merchantCategoryCode String = OPTIONAL
agreement.retailer.tradingName String = OPTIONAL
agreement.startDate Date = OPTIONAL
agreement.type Enumeration = OPTIONAL
The gateway will use the value you specify for subsequent payments in the series.
apiOperation String =AUTHENTICATE_PAYER FIXED
authentication = OPTIONAL
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 = OPTIONAL
authentication.3ds2.sdk = OPTIONAL
authentication.3ds2.sdk.appId String = COMPULSORY
This field corresponds to EMVCo field sdkAppID
authentication.3ds2.sdk.encryptedData String = COMPULSORY
This field corresponds to EMVCo field sdkEncData
authentication.3ds2.sdk.ephemeralPublicKey JSON Text = COMPULSORY
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
authentication.3ds2.sdk.interface Enumeration = OPTIONAL
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.
authentication.3ds2.sdk.referenceNumber String = COMPULSORY
authentication.3ds2.sdk.timeout Integer = OPTIONAL
This field corresponds to EMVCo field sdkMaxTimeout
authentication.3ds2.sdk.transactionId String = COMPULSORY
authentication.3ds2.sdk.uiType Comma separated enumeration = OPTIONAL
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.
authentication.challengePreference Enumeration = OPTIONAL
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.
authentication.goodsDescription String = OPTIONAL
authentication.psd2 = OPTIONAL
authentication.psd2.exemption Enumeration = OPTIONAL
- For recurring payments provide the RECURRING_PAYMENT value only if the amount is the same. If the amount varies, provide MERCHANT_INITIATED_TRANSACTION instead.
authentication.redirectResponseUrl Url = OPTIONAL
You must provide this URL, unless you are certain that there will be no interaction with the payer.
billing = OPTIONAL
billing.address = OPTIONAL
billing.address.city String = OPTIONAL
billing.address.company String = OPTIONAL
billing.address.country Upper case alphabetic text = OPTIONAL
billing.address.postcodeZip Alphanumeric + additional characters = OPTIONAL
billing.address.stateProvince String = OPTIONAL
billing.address.stateProvinceCode String = OPTIONAL
billing.address.street String = OPTIONAL
billing.address.street2 String = OPTIONAL
correlationId String = OPTIONAL
customer = OPTIONAL
customer.account = OPTIONAL
customer.account.authentication = OPTIONAL
customer.account.authentication.cardAssociation = OPTIONAL
customer.account.authentication.cardAssociation.action Enumeration = OPTIONAL
customer.account.authentication.data String = OPTIONAL
customer.account.authentication.method Enumeration = OPTIONAL
customer.account.authentication.time DateTime = OPTIONAL
customer.account.history = OPTIONAL
customer.account.history.addCardAttempts Integer = OPTIONAL
customer.account.history.annualActivity Integer = OPTIONAL
customer.account.history.creationDate Date = OPTIONAL
customer.account.history.issuerAuthentication = OPTIONAL
customer.account.history.issuerAuthentication.acsTransactionId String = OPTIONAL
customer.account.history.issuerAuthentication.authenticationToken Base64 = OPTIONAL
customer.account.history.issuerAuthentication.time DateTime = OPTIONAL
customer.account.history.issuerAuthentication.transactionId String = OPTIONAL
customer.account.history.issuerAuthentication.type Enumeration = OPTIONAL
customer.account.history.lastUpdated Date = OPTIONAL
customer.account.history.passwordLastChanged Date = OPTIONAL
customer.account.history.recentActivity Integer = OPTIONAL
customer.account.history.shippingAddressDate Date = OPTIONAL
customer.account.history.suspiciousActivity Boolean = OPTIONAL
customer.account.id String = OPTIONAL
customer.email Email = OPTIONAL
customer.firstName String = OPTIONAL
customer.lastName String = OPTIONAL
customer.mobilePhone Telephone Number = OPTIONAL
The number consists of:
- ‘+’
- country code (1, 2 or 3 digits)
- ‘space’
- national number ( which may embed single spaces characters for readability).
customer.phone Telephone Number = OPTIONAL
The number consists of:
- ‘+’
- country code (1, 2 or 3 digits)
- ‘space’
- national number ( which may embed single spaces characters for readability).
customer.taxRegistrationId String = OPTIONAL
device = OPTIONAL
device.ani String = OPTIONAL
device.aniCallType String = OPTIONAL
device.browser String = OPTIONAL
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.
device.browserDetails = OPTIONAL
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 Enumeration = OPTIONAL
device.browserDetails.acceptHeaders String = OPTIONAL
This must be provided for authentication operations where authentication.channel is PAYER_BROWSER.
device.browserDetails.colorDepth Integer = OPTIONAL
This must be provided for authentication operations where authentication.channel is PAYER_BROWSER.
device.browserDetails.javaEnabled Boolean = OPTIONAL
This must be provided for authentication operations where authentication.channel is PAYER_BROWSER.
device.browserDetails.javaScriptEnabled Boolean = OPTIONAL
device.browserDetails.language String = OPTIONAL
This must be provided for authentication operations where authentication.channel is PAYER_BROWSER.
device.browserDetails.screenHeight Integer = OPTIONAL
This must be provided for authentication operations where authentication.channel is PAYER_BROWSER.
device.browserDetails.screenWidth Integer = OPTIONAL
This must be provided for authentication operations where authentication.channel is PAYER_BROWSER.
device.browserDetails.timeZone Browser Time Zone Offset = OPTIONAL
This must be provided for authentication operations where authentication.channel is PAYER_BROWSER.
device.fingerprint String = OPTIONAL
device.hostname String = OPTIONAL
device.ipAddress String = OPTIONAL
IPv6 address will only be used in EMV 3DS authentication. Supplied IPv6 address will not be used for any other purposes.
device.mobilePhoneModel String = OPTIONAL
order = COMPULSORY
order.acceptPartialAmount Boolean = OPTIONAL
Unless you have been advised by your payment service provider that the gateway supports partial approvals for your acquirer, you can ignore this field.
If the gateway supports partial approvals for your acquirer you must set this field to TRUE else the transaction is rejected by the gateway.
order.amount Decimal = OPTIONAL
order.certainty Enumeration = OPTIONAL
order.currency Upper case alphabetic text = COMPULSORY
order.custom String = OPTIONAL
order.customerNote String = OPTIONAL
order.customerOrderDate Date = OPTIONAL
order.customerReference ASCII Text = OPTIONAL
order.description String = OPTIONAL
order.discount = OPTIONAL
order.discount.amount Decimal = OPTIONAL
order.discount.code String = OPTIONAL
order.discount.description String = OPTIONAL
order.dutyAmount Decimal = OPTIONAL
order.gratuityAmount Decimal = OPTIONAL
order.invoiceNumber String = OPTIONAL
order.localTaxRegistrationId String = OPTIONAL
order.marketplace = OPTIONAL
order.marketplace.retailerLocation Enumeration = OPTIONAL
order.merchantCharge = OPTIONAL
order.merchantCharge.amount Decimal = OPTIONAL
order.merchantCharge.type Enumeration = COMPULSORY
order.netAmount Decimal = OPTIONAL
order.owningEntity String = OPTIONAL
order.purchaseType Enumeration = OPTIONAL
6051 (Quasi Cash – Merchant or Non-Financial Institutions – Foreign Currency, Non-Fiat Currency) and this transaction is for the purchase of cryptocurrency. Set the value to CRYPTOCURRENCY.
6211 (Securities – Brokers/Dealers) and this transaction is for the purchase of high-risk securities. Set the value to HIGH_RISK_SECURITIES.
6012 (Merchandise and Services—Customer Financial Institutions) or 6051 (Non-Financial Institutions – Foreign Currency, Non-Fiat Currency) and this transaction is for debt repayment. Set the value to DEBT_REPAYMENT.
If the transaction pulls money from an account for the purpose of crediting another account you must set purchase type to ACCOUNT_FUNDING.
You may set purchase type to OTHER for any other type of payment.
order.requestorName String = OPTIONAL
order.shippingAndHandlingAmount Decimal = OPTIONAL
order.shippingAndHandlingTaxAmount Decimal = OPTIONAL
order.shippingAndHandlingTaxRate Decimal = OPTIONAL
order.statementDescriptor = OPTIONAL
order.statementDescriptor.address = OPTIONAL
order.statementDescriptor.address.city String = OPTIONAL
order.statementDescriptor.address.company String = OPTIONAL
order.statementDescriptor.address.country Upper case alphabetic text = OPTIONAL
order.statementDescriptor.address.postcodeZip Alphanumeric + additional characters = OPTIONAL
order.statementDescriptor.address.stateProvince String = OPTIONAL
order.statementDescriptor.address.street String = OPTIONAL
order.statementDescriptor.address.street2 String = OPTIONAL
order.statementDescriptor.name String = OPTIONAL
order.statementDescriptor.phone String = OPTIONAL
order.supply = OPTIONAL
order.supply.preorder Boolean = OPTIONAL
order.supply.preorderAvailabilityDate Date = OPTIONAL
order.supply.reorder Boolean = OPTIONAL
order.tax[n] = OPTIONAL
order.tax[n].amount Decimal = OPTIONAL
order.tax[n].rate Decimal = OPTIONAL
order.tax[n].type String = OPTIONAL
order.taxAmount Decimal = OPTIONAL
If you provide both this value and line item data, then the order.taxAmount MUST equal the total tax amount.
order.taxRegistrationId String = OPTIONAL
order.taxStatus Enumeration = OPTIONAL
order.transactionFiltering = OPTIONAL
order.transactionFiltering.avsResponseCodeRules[n] = OPTIONAL
order.transactionFiltering.avsResponseCodeRules[n].action Enumeration = COMPULSORY
order.transactionFiltering.avsResponseCodeRules[n].avsResponseCode Enumeration = COMPULSORY
order.valueTransfer = OPTIONAL
order.valueTransfer.accountType Enumeration = OPTIONAL
order.valueTransfer.amount Decimal = OPTIONAL
order.valueTransfer.currency Upper case alphabetic text = OPTIONAL
The default value is order.currency.
order.valueTransfer.numberOfCards Integer = OPTIONAL
order.walletIndicator String = OPTIONAL
order.walletProvider Enumeration = OPTIONAL
session.id ASCII Text = OPTIONAL
session.version ASCII Text = OPTIONAL
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.
shipping = OPTIONAL
shipping.address = OPTIONAL
shipping.address.city String = OPTIONAL
shipping.address.company String = OPTIONAL
shipping.address.country Upper case alphabetic text = OPTIONAL
shipping.address.postcodeZip Alphanumeric + additional characters = OPTIONAL
shipping.address.sameAsBilling Enumeration = OPTIONAL
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.
shipping.address.source Enumeration = OPTIONAL
shipping.address.stateProvince String = OPTIONAL
shipping.address.stateProvinceCode String = OPTIONAL
shipping.address.street String = OPTIONAL
shipping.address.street2 String = OPTIONAL
shipping.contact = OPTIONAL
shipping.contact.email Email = OPTIONAL
shipping.contact.firstName String = OPTIONAL
shipping.contact.lastName String = OPTIONAL
shipping.contact.mobilePhone Telephone Number = OPTIONAL
The number consists of:
- ‘+’
- country code (1, 2 or 3 digits)
- ‘space’
- national number ( which may embed single spaces characters for readability).
shipping.contact.phone Telephone Number = OPTIONAL
The number consists of:
- ‘+’
- country code (1, 2 or 3 digits)
- ‘space’
- national number ( which may embed single spaces characters for readability).
shipping.contact.sameAsBilling Enumeration = OPTIONAL
Default value is UNKNOWN
shipping.method Enumeration = OPTIONAL
shipping.origin.postcodeZip Alphanumeric + additional characters = OPTIONAL
sourceOfFunds = OPTIONAL
sourceOfFunds.provided = OPTIONAL
sourceOfFunds.provided.card = OPTIONAL
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 = OPTIONAL
sourceOfFunds.provided.card.devicePayment.cryptogramFormat Enumeration = OPTIONAL
- • 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.
sourceOfFunds.provided.card.devicePayment.eciIndicator Digits = OPTIONAL
This field is not applicable for payments using digital wallets or card scheme tokens.
sourceOfFunds.provided.card.devicePayment.onlinePaymentCryptogram Base64 = OPTIONAL
- • Device payments: source this field directly from the decrypted payment token.
- • Card scheme tokens: source this field directly from the decrypted transaction credentials.
sourceOfFunds.provided.card.devicePayment.paymentToken String = OPTIONAL
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.
sourceOfFunds.provided.card.expiry = OPTIONAL
sourceOfFunds.provided.card.expiry.month Digits = COMPULSORY
Months are numbered January=1, through to December=12.
sourceOfFunds.provided.card.expiry.year Digits = COMPULSORY
The Common Era year is 2000 plus this value.
sourceOfFunds.provided.card.nameOnCard String = OPTIONAL
sourceOfFunds.provided.card.number Digits = OPTIONAL
sourceOfFunds.provided.card.securityCode Digits = OPTIONAL
sourceOfFunds.token Alphanumeric = OPTIONAL
If account identifier details are also contained in the request, or the request contains a session with account identifier details, these take precedence over the details stored against the token.
transaction = OPTIONAL
transaction.merchantNote String = OPTIONAL
{merchantId} Alphanumeric + additional characters COMPULSORY
{orderid} String COMPULSORY
{transactionid} String COMPULSORY
- 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.
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.
Response Parameters
merchant Alphanumeric + additional characters = Always Provided
order = Always Provided
order.amount Decimal = Always Provided
order.creationTime DateTime = Always Provided
order.currency Upper case alphabetic text = Always Provided
order.id String = Always Provided
order.lastUpdatedTime DateTime = Always Provided
order.totalAuthorizedAmount Decimal = Always Provided
order.totalCapturedAmount Decimal = Always Provided
order.totalRefundedAmount Decimal = Always Provided
response = Always Provided
response.gatewayCode Enumeration = Always Provided
result Enumeration = Always Provided
transaction = Always Provided
transaction.amount Decimal = Always Provided
transaction.currency Upper case alphabetic text = Always Provided
transaction.id String = Always Provided
- 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.
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.
transaction.type Enumeration = Always Provided
accountFunding = CONDITIONAL
accountFunding.purpose Enumeration = CONDITIONAL
accountFunding.recipient = CONDITIONAL
accountFunding.recipient.account = CONDITIONAL
accountFunding.recipient.account.fundingMethod Enumeration = CONDITIONAL
accountFunding.recipient.account.identifier String = CONDITIONAL
accountFunding.recipient.account.identifierType Enumeration = CONDITIONAL
accountFunding.recipient.country Upper case alphabetic text = CONDITIONAL
accountFunding.recipient.dateOfBirth Date = CONDITIONAL
accountFunding.recipient.firstName String = CONDITIONAL
accountFunding.recipient.lastName String = CONDITIONAL
accountFunding.recipient.middleName String = CONDITIONAL
accountFunding.recipient.postCodeZip String = CONDITIONAL
accountFunding.recipient.stateProvinceCode String = CONDITIONAL
accountFunding.senderIsRecipient Boolean = CONDITIONAL
accountFunding.senderType Enumeration = CONDITIONAL
agreement = CONDITIONAL
agreement.amountVariability Enumeration = CONDITIONAL
agreement.customData String = CONDITIONAL
agreement.expiryDate Date = CONDITIONAL
agreement.id String = CONDITIONAL
- Recurring payments: you have an agreement with the payer that authorizes you to automatically debit their account at agreed intervals for fixed or variable amounts. For example, gym membership, phone bills, or magazine subscriptions.
- Installment payments: you have an agreement with the payer that authorizes you to process multiple payments over an agreed period of time for a single purchase. For example, the payer purchases an item for $1000 and pays for it in four monthly installments.
- Unscheduled: you have an agreement with the payer that authorizes you to process future payments when required. For example, the payer authorizes you to process an account top-up transaction for a transit card when the account balance drops below a certain threshold.
- Industry Practice: you have an agreement with the payer that authorizes you to initiate additional transactions to fulfil a standard business practice related to an original payment initiated by the payer. For example, a delayed charge for use of the hotel mini bar after the payer has checked out or a no show penalty charge when the payer fails to show for a booking.
agreement.maximumAmountPerPayment Decimal = CONDITIONAL
agreement.minimumAmountPerPayment Decimal = CONDITIONAL
agreement.minimumDaysBetweenPayments Integer = CONDITIONAL
agreement.numberOfPayments Integer = CONDITIONAL
agreement.paymentFrequency Enumeration = CONDITIONAL
agreement.retailer = CONDITIONAL
agreement.retailer.abbreviatedTradingName String = CONDITIONAL
agreement.retailer.merchantCategoryCode String = CONDITIONAL
agreement.retailer.tradingName String = CONDITIONAL
agreement.startDate Date = CONDITIONAL
agreement.type Enumeration = CONDITIONAL
The gateway will use the value you specify for subsequent payments in the series.
authentication = CONDITIONAL
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 = CONDITIONAL
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 Alphanumeric = CONDITIONAL
authentication.3ds.authenticationToken Base64 = CONDITIONAL
For 3DS version 2, this field corresponds to the Authentication Value.
authentication.3ds.transactionId String = CONDITIONAL
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.
For Rupay, this field corresponds to the authentication identifier assigned by Rupay for Guest Checkout transaction used for unregistered user transaction only.
authentication.3ds1 = CONDITIONAL
authentication.3ds1.paResStatus Alpha = CONDITIONAL
authentication.3ds1.veResEnrolled Alpha = Always Provided
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™.
authentication.3ds2 = CONDITIONAL
authentication.3ds2.3dsServerTransactionId String = CONDITIONAL
authentication.3ds2.acsTransactionId String = CONDITIONAL
authentication.3ds2.authenticationScheme String = CONDITIONAL
For example, for externally authenticated Mada co-branded transactions, you must provide either MADA, MASTERCARD or VISA to specify the 3DS directory server.
authentication.3ds2.custom JSON Text = CONDITIONAL
authentication.3ds2.directoryServerId String = CONDITIONAL
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).
authentication.3ds2.dsReference String = CONDITIONAL
authentication.3ds2.dsTransactionId String = CONDITIONAL
authentication.3ds2.methodCompleted Boolean = Always Provided
authentication.3ds2.methodSupported Enumeration = Always Provided
authentication.3ds2.protocolVersion Alphanumeric + additional characters = CONDITIONAL
authentication.3ds2.requestorId String = Always Provided
authentication.3ds2.requestorName String = Always Provided
authentication.3ds2.sdk = CONDITIONAL
authentication.3ds2.sdk.challengeCompletionCallbackUrl Url = CONDITIONAL
This allows the gateway to retrieve the authentication result after the challenge has been completed.
authentication.3ds2.sdk.interface Enumeration = CONDITIONAL
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.
authentication.3ds2.sdk.timeout Integer = CONDITIONAL
This field corresponds to EMVCo field sdkMaxTimeout
authentication.3ds2.sdk.uiType Comma separated enumeration = CONDITIONAL
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.
authentication.3ds2.statusReasonCode String = CONDITIONAL
authentication.3ds2.transactionStatus Alpha = CONDITIONAL
Refer to the EMVCo specification for 3-D Secure.
authentication.3ds2.acsReference String = CONDITIONAL
authentication.3ds2.challenge = CONDITIONAL
authentication.3ds2.challenge.signedContent String = CONDITIONAL
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.
authentication.amount Decimal = CONDITIONAL
authentication.method Enumeration = CONDITIONAL
authentication.payerInteraction Enumeration = Always Provided
authentication.psd2 = CONDITIONAL
authentication.psd2.exemption Enumeration = CONDITIONAL
- For recurring payments provide the RECURRING_PAYMENT value only if the amount is the same. If the amount varies, provide MERCHANT_INITIATED_TRANSACTION instead.
authentication.psd2.trustedMerchantStatus Enumeration = CONDITIONAL
If the issuer grants the exemption the payer will not be presented with a challenge, for example, they may have to enter a one-time password.
authentication.redirect = CONDITIONAL
- Initiate Authentication response: If supported by the issuer's Access Control Server (ACS), the HTML will submit a 3DS method call in your hidden iframe to the ACS. This call gathers additional browser information prior to the Authenticate Payer request and helps facilitate the transaction risk assessment by the issuer's ACS.
- Authenticate Payer response: If required, the HTML will redirect the payer's browser to the issuer's ACS to complete the challenge.
Alternatively, you can use the details provided in the authentication.redirect.customizedHtml parameter group to create the required payer experience yourself. In this case you must follow the EMVCo specification. If a method call is required, the Initiate Authentication response provides the URL and POST data for the method call. If a challenge is required, the Authenticate Payer response provides the ACS URL and challenge request.
authentication.redirect.customizedHtml = CONDITIONAL
authentication.redirect.customizedHtml.3ds2 = CONDITIONAL
authentication.redirect.customizedHtml.3ds2.acsUrl Url = CONDITIONAL
authentication.redirect.customizedHtml.3ds2.cReq ASCII Text = CONDITIONAL
authentication.redirect.html String = CONDITIONAL
authentication.redirect.domainName String = CONDITIONAL
authentication.time DateTime = CONDITIONAL
authentication.version Enumeration = CONDITIONAL
billing = CONDITIONAL
billing.address = CONDITIONAL
billing.address.city String = CONDITIONAL
billing.address.company String = CONDITIONAL
billing.address.country Upper case alphabetic text = CONDITIONAL
billing.address.postcodeZip Alphanumeric + additional characters = CONDITIONAL
billing.address.stateProvince String = CONDITIONAL
billing.address.stateProvinceCode String = CONDITIONAL
billing.address.street String = CONDITIONAL
billing.address.street2 String = CONDITIONAL
correlationId String = CONDITIONAL
customer = CONDITIONAL
customer.account = CONDITIONAL
customer.account.authentication = CONDITIONAL
customer.account.authentication.cardAssociation = CONDITIONAL
customer.account.authentication.cardAssociation.action Enumeration = CONDITIONAL
customer.account.authentication.cardAssociation.status Enumeration = CONDITIONAL
customer.account.authentication.method Enumeration = CONDITIONAL
customer.account.authentication.time DateTime = CONDITIONAL
customer.account.history = CONDITIONAL
customer.account.history.addCardAttempts Integer = CONDITIONAL
customer.account.history.annualActivity Integer = CONDITIONAL
customer.account.history.creationDate Date = CONDITIONAL
customer.account.history.issuerAuthentication = CONDITIONAL
customer.account.history.issuerAuthentication.acsTransactionId String = CONDITIONAL
customer.account.history.issuerAuthentication.authenticationToken Base64 = CONDITIONAL
customer.account.history.issuerAuthentication.time DateTime = CONDITIONAL
customer.account.history.issuerAuthentication.transactionId String = CONDITIONAL
customer.account.history.issuerAuthentication.type Enumeration = CONDITIONAL
customer.account.history.lastUpdated Date = CONDITIONAL
customer.account.history.passwordLastChanged Date = CONDITIONAL
customer.account.history.recentActivity Integer = CONDITIONAL
customer.account.history.shippingAddressDate Date = CONDITIONAL
customer.account.history.suspiciousActivity Boolean = CONDITIONAL
customer.account.id String = CONDITIONAL
customer.email Email = CONDITIONAL
customer.firstName String = CONDITIONAL
customer.lastName String = CONDITIONAL
customer.mobilePhone String = CONDITIONAL
customer.phone String = CONDITIONAL
customer.taxRegistrationId String = CONDITIONAL
device = CONDITIONAL
device.ani String = CONDITIONAL
device.aniCallType String = CONDITIONAL
device.browser String = CONDITIONAL
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.
device.hostname String = CONDITIONAL
device.ipAddress String = CONDITIONAL
IPv6 address will only be used in EMV 3DS authentication. Supplied IPv6 address will not be used for any other purposes.
device.mobilePhoneModel String = CONDITIONAL
encryptedData = CONDITIONAL
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 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
encryptedData.ciphertext String = Always Provided
encryptedData.nonce String = Always Provided
encryptedData.tag String = Always Provided
lineOfBusiness String = CONDITIONAL
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.
merchant Alphanumeric + additional characters = Always Provided
order = Always Provided
order.acceptPartialAmount Boolean = CONDITIONAL
Unless you have been advised by your payment service provider that the gateway supports partial approvals for your acquirer, you can ignore this field.
If the gateway supports partial approvals for your acquirer you must set this field to TRUE else the transaction is rejected by the gateway.
order.amount Decimal = Always Provided
order.authenticationStatus Enumeration = CONDITIONAL
order.certainty Enumeration = CONDITIONAL
order.creationTime DateTime = Always Provided
order.currency Upper case alphabetic text = Always Provided
order.custom String = CONDITIONAL
order.customerNote String = CONDITIONAL
order.customerOrderDate Date = CONDITIONAL
order.customerReference ASCII Text = CONDITIONAL
order.description String = CONDITIONAL
order.discount = CONDITIONAL
order.discount.amount Decimal = CONDITIONAL
order.discount.code String = CONDITIONAL
order.discount.description String = CONDITIONAL
order.dutyAmount Decimal = CONDITIONAL
order.id String = Always Provided
order.invoiceNumber String = CONDITIONAL
order.lastUpdatedTime DateTime = Always Provided
order.localTaxRegistrationId String = CONDITIONAL
order.marketplace = CONDITIONAL
order.marketplace.retailerLocation Enumeration = CONDITIONAL
order.merchantCategoryCode Digits = CONDITIONAL
order.merchantCharge = CONDITIONAL
order.merchantCharge.amount Decimal = Always Provided
order.merchantCharge.calculatedBy Enumeration = Always Provided
order.merchantCharge.ruleName String = CONDITIONAL
order.merchantCharge.type Enumeration = Always Provided
order.netAmount Decimal = CONDITIONAL
order.notificationUrl Url = CONDITIONAL
order.owningEntity String = CONDITIONAL
order.reference String = CONDITIONAL
order.requestorName String = CONDITIONAL
order.shippingAndHandlingAmount Decimal = CONDITIONAL
order.shippingAndHandlingTaxAmount Decimal = CONDITIONAL
order.shippingAndHandlingTaxRate Decimal = CONDITIONAL
order.statementDescriptor = CONDITIONAL
order.statementDescriptor.address = CONDITIONAL
order.statementDescriptor.address.city String = CONDITIONAL
order.statementDescriptor.address.company String = CONDITIONAL
order.statementDescriptor.address.country Upper case alphabetic text = CONDITIONAL
order.statementDescriptor.address.postcodeZip Alphanumeric + additional characters = CONDITIONAL
order.statementDescriptor.address.stateProvince String = CONDITIONAL
order.statementDescriptor.address.street String = CONDITIONAL
order.statementDescriptor.address.street2 String = CONDITIONAL
order.statementDescriptor.name String = CONDITIONAL
order.statementDescriptor.phone String = CONDITIONAL
order.status Enumeration = CONDITIONAL
order.subMerchant = CONDITIONAL
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 = CONDITIONAL
order.subMerchant.address.city String = CONDITIONAL
order.subMerchant.address.company String = CONDITIONAL
order.subMerchant.address.country Upper case alphabetic text = CONDITIONAL
order.subMerchant.address.postcodeZip Alphanumeric + additional characters = CONDITIONAL
order.subMerchant.address.stateProvince String = CONDITIONAL
order.subMerchant.address.street String = CONDITIONAL
order.subMerchant.address.street2 String = CONDITIONAL
order.subMerchant.authentication[n] = CONDITIONAL
order.subMerchant.authentication[n].3DS2 = CONDITIONAL
order.subMerchant.authentication[n].3DS2.requestorId String = CONDITIONAL
order.subMerchant.authentication[n].3DS2.requestorName String = CONDITIONAL
order.subMerchant.authentication[n].protocol Enumeration = Always Provided
order.subMerchant.bankIndustryCode Digits = CONDITIONAL
order.subMerchant.disputeContactPhone Telephone Number = CONDITIONAL
order.subMerchant.email Email = CONDITIONAL
order.subMerchant.identifier Alphanumeric + additional characters = Always Provided
order.subMerchant.phone String = CONDITIONAL
order.subMerchant.registeredName String = CONDITIONAL
order.subMerchant.tradingName String = Always Provided
order.subMerchant.websiteUrl Url = CONDITIONAL
order.supply = CONDITIONAL
order.supply.preorder Boolean = CONDITIONAL
order.supply.preorderAvailabilityDate Date = CONDITIONAL
order.supply.reorder Boolean = CONDITIONAL
order.surchargeAmount Decimal = CONDITIONAL
If you provide a surcharge amount, you should include it in the total amount for the order.
order.surchargeSource Enumeration = CONDITIONAL
order.tax[n] = CONDITIONAL
order.tax[n].amount Decimal = CONDITIONAL
order.tax[n].rate Decimal = CONDITIONAL
order.tax[n].type String = CONDITIONAL
order.taxAmount Decimal = CONDITIONAL
order.taxRegistrationId String = CONDITIONAL
order.taxStatus String = CONDITIONAL
order.totalAuthorizedAmount Decimal = Always Provided
order.totalCapturedAmount Decimal = Always Provided
order.totalRefundedAmount Decimal = Always Provided
order.transactionFiltering = CONDITIONAL
order.transactionFiltering.avsResponseCodeRules[n] = CONDITIONAL
order.transactionFiltering.avsResponseCodeRules[n].action Enumeration = Always Provided
order.transactionFiltering.avsResponseCodeRules[n].avsResponseCode Enumeration = Always Provided
order.valueTransfer = CONDITIONAL
order.valueTransfer.accountType Enumeration = CONDITIONAL
order.valueTransfer.amount Decimal = CONDITIONAL
order.valueTransfer.currency Upper case alphabetic text = CONDITIONAL
The default value is order.currency.
order.valueTransfer.numberOfCards Integer = CONDITIONAL
order.walletIndicator String = CONDITIONAL
order.walletProvider Enumeration = CONDITIONAL
partnerSolutionId String = CONDITIONAL
response = Always Provided
response.debugInformation String = CONDITIONAL
response.gatewayCode Enumeration = Always Provided
response.gatewayRecommendation Enumeration = CONDITIONAL
- can proceed as planned.
- must not proceed. For example, because there is suspected fraud.
- can take action to obtain a successful Authorization. For example, by authenticating the payer, or asking the payer for updated or new payment details.
- must make a review decision.
result Enumeration = Always Provided
shipping = CONDITIONAL
shipping.address = CONDITIONAL
shipping.address.city String = CONDITIONAL
shipping.address.company String = CONDITIONAL
shipping.address.country Upper case alphabetic text = CONDITIONAL
shipping.address.postcodeZip Alphanumeric + additional characters = CONDITIONAL
shipping.address.source Enumeration = CONDITIONAL
shipping.address.stateProvince String = CONDITIONAL
shipping.address.stateProvinceCode String = CONDITIONAL
shipping.address.street String = CONDITIONAL
shipping.address.street2 String = CONDITIONAL
shipping.address.sameAsBilling Enumeration = CONDITIONAL
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.
shipping.contact = CONDITIONAL
shipping.contact.email Email = CONDITIONAL
shipping.contact.firstName String = CONDITIONAL
shipping.contact.lastName String = CONDITIONAL
shipping.contact.mobilePhone Telephone Number = CONDITIONAL
The number consists of:
- ‘+’
- country code (1, 2 or 3 digits)
- ‘space’
- national number ( which may embed single spaces characters for readability).
shipping.contact.phone Telephone Number = CONDITIONAL
The number consists of:
- ‘+’
- country code (1, 2 or 3 digits)
- ‘space’
- national number ( which may embed single spaces characters for readability).
shipping.contact.sameAsBilling Enumeration = CONDITIONAL
Default value is UNKNOWN
shipping.method Enumeration = CONDITIONAL
shipping.origin.postcodeZip Alphanumeric + additional characters = CONDITIONAL
sourceOfFunds = CONDITIONAL
For card payments the source of funds information may be represented by combining one or more of the following: explicitly provided card details, a session identifier which the gateway will use to look up the card details and/or a card token. Precedence rules will be applied in that explicitly provided card details will override session card details which will override card token details. Each of these may represent partial card details, however the combination must result in a full and complete set of card details. See Using Multiple Sources of Card Details for examples.
sourceOfFunds.provided = CONDITIONAL
sourceOfFunds.provided.ach = CONDITIONAL
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).
sourceOfFunds.provided.ach.bankAccountHolder String = CONDITIONAL
sourceOfFunds.provided.ach.bankAccountNumber Alphanumeric + additional characters = CONDITIONAL
sourceOfFunds.provided.ach.routingNumber Digits = CONDITIONAL
- Routing number,
- Transit number, or
- ABA number
Retrieve this information from the payer.
See also http://en.wikipedia.org/wiki/Routing_transit_number.
sourceOfFunds.provided.ach.secCode Enumeration = CONDITIONAL
sourceOfFunds.provided.bancontact = CONDITIONAL
sourceOfFunds.provided.bancontact.bankAccountHolder String = Always Provided
sourceOfFunds.provided.blik = CONDITIONAL
sourceOfFunds.provided.blik.bankAccountHolder String = Always Provided
sourceOfFunds.provided.boletoBancario = CONDITIONAL
sourceOfFunds.provided.boletoBancario.actionType Enumeration = CONDITIONAL
sourceOfFunds.provided.boletoBancario.bankAccountHolder String = Always Provided
sourceOfFunds.provided.boletoBancario.customerType Enumeration = CONDITIONAL
sourceOfFunds.provided.boletoBancario.daysBeforeAction Digits = CONDITIONAL
sourceOfFunds.provided.boletoBancario.dueDate Date = CONDITIONAL
sourceOfFunds.provided.boletoBancario.slipUrl Url = CONDITIONAL
sourceOfFunds.provided.card = CONDITIONAL
Cards: the card details entered directly or collected using a Point of Sale (POS) terminal.
Device payment methods such as Apple Pay, Android Pay, Samsung Pay or Google Pay.
Digital wallets such as Masterpass, Visa Checkout or Amex Express Checkout.
Card scheme tokens where the card was tokenized using a card scheme tokenization service such as Mastercard Digital Enablement Service (MDES).
sourceOfFunds.provided.card.accountType Enumeration = CONDITIONAL
sourceOfFunds.provided.card.brand 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.
sourceOfFunds.provided.card.devicePayment = CONDITIONAL
sourceOfFunds.provided.card.devicePayment.cryptogramFormat Enumeration = CONDITIONAL
You do not need to provide the cryptogram format if you provide the payment token in sourceOfFunds.provided.card.devicePayment.paymentToken
sourceOfFunds.provided.card.deviceSpecificExpiry = CONDITIONAL
- • Device payments: the expiry date for the Device Primary Account Number (DPAN).
- • Digital wallets: the expiry date for the Token PAN.
- • Card scheme tokens: the expiry date for the Token PAN.
sourceOfFunds.provided.card.deviceSpecificExpiry.month Digits = Always Provided
sourceOfFunds.provided.card.deviceSpecificExpiry.year Digits = Always Provided
sourceOfFunds.provided.card.deviceSpecificNumber Masked digits = Always Provided
- • 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
sourceOfFunds.provided.card.emvRequest String = CONDITIONAL
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.
sourceOfFunds.provided.card.emvResponse String = CONDITIONAL
The card/terminal uses data returned from the issuer to make the final decision to accept or decline the transaction.
sourceOfFunds.provided.card.encryption Enumeration = CONDITIONAL
sourceOfFunds.provided.card.expiry = CONDITIONAL
sourceOfFunds.provided.card.expiry.month Digits = Always Provided
Months are numbered January=1, through to December=12.
sourceOfFunds.provided.card.expiry.year Digits = Always Provided
The Common Era year is 2000 plus this value.
sourceOfFunds.provided.card.fundingMethod Enumeration = Always Provided
sourceOfFunds.provided.card.issuer String = CONDITIONAL
sourceOfFunds.provided.card.localBrand String = CONDITIONAL
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.
sourceOfFunds.provided.card.nameOnCard String = CONDITIONAL
sourceOfFunds.provided.card.number Masked digits = Always Provided
- 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.
sourceOfFunds.provided.card.pin = CONDITIONAL
sourceOfFunds.provided.card.pin.encryptionState Enumeration = CONDITIONAL
sourceOfFunds.provided.card.pin.keySerialNumber Hex = Always Provided
sourceOfFunds.provided.card.scheme Enumeration = Always Provided
sourceOfFunds.provided.card.sequenceNumber Digits = CONDITIONAL
sourceOfFunds.provided.card.storedOnFile Enumeration = CONDITIONAL
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.
sourceOfFunds.provided.card.trackDataProvided Boolean = CONDITIONAL
sourceOfFunds.provided.ebt = CONDITIONAL
sourceOfFunds.provided.ebt.accountType Enumeration = CONDITIONAL
sourceOfFunds.provided.ebt.manualAuthorizationCode Digits = CONDITIONAL
sourceOfFunds.provided.ebt.merchantFns Digits = CONDITIONAL
sourceOfFunds.provided.ebt.voucherNumber Digits = CONDITIONAL
sourceOfFunds.provided.enets = CONDITIONAL
sourceOfFunds.provided.enets.bankAccountHolder String = Always Provided
sourceOfFunds.provided.giftCard = CONDITIONAL
sourceOfFunds.provided.giftCard.brand Enumeration = Always Provided
sourceOfFunds.provided.giftCard.localBrand String = Always Provided
sourceOfFunds.provided.giftCard.number Masked digits = Always Provided
sourceOfFunds.provided.giftCard.pin Masked digits = CONDITIONAL
sourceOfFunds.provided.giftCard.scheme Enumeration = Always Provided
sourceOfFunds.provided.giropay = CONDITIONAL
sourceOfFunds.provided.giropay.bankIdentifier Digits = CONDITIONAL
sourceOfFunds.provided.giropay.bic Alphanumeric = CONDITIONAL
sourceOfFunds.provided.giropay.iban String = CONDITIONAL
sourceOfFunds.provided.grabPay = CONDITIONAL
sourceOfFunds.provided.grabPay.accountHolder String = Always Provided
sourceOfFunds.provided.ideal = CONDITIONAL
sourceOfFunds.provided.ideal.bankAccountHolder String = CONDITIONAL
sourceOfFunds.provided.ideal.bic Alphanumeric = CONDITIONAL
sourceOfFunds.provided.ideal.iban String = CONDITIONAL
sourceOfFunds.provided.openBankingBankTransfer = CONDITIONAL
sourceOfFunds.provided.openBankingBankTransfer.aspspId String = Always Provided
sourceOfFunds.provided.oxxo = CONDITIONAL
sourceOfFunds.provided.oxxo.bankAccountHolder String = Always Provided
sourceOfFunds.provided.oxxo.dueDate Date = CONDITIONAL
sourceOfFunds.provided.paypal = CONDITIONAL
sourceOfFunds.provided.paypal.accountEmail Email = CONDITIONAL
sourceOfFunds.provided.paypal.accountHolder String = CONDITIONAL
sourceOfFunds.provided.paypal.billingAgreement = CONDITIONAL
sourceOfFunds.provided.paypal.billingAgreement.cardinality Enumeration = CONDITIONAL
sourceOfFunds.provided.paypal.billingAgreement.description String = CONDITIONAL
sourceOfFunds.provided.paypal.billingAgreement.id String = CONDITIONAL
sourceOfFunds.provided.paypal.billingAgreement.name String = CONDITIONAL
sourceOfFunds.provided.paypal.payerId String = CONDITIONAL
sourceOfFunds.provided.pbba = CONDITIONAL
sourceOfFunds.provided.pbba.paymentRequestId Digits = CONDITIONAL
sourceOfFunds.provided.pbba.paymentRequestInputCode Upper case alphabetic text = CONDITIONAL
sourceOfFunds.provided.poli = CONDITIONAL
sourceOfFunds.provided.poli.bankAccountHolder String = Always Provided
sourceOfFunds.provided.przelewy24 = CONDITIONAL
sourceOfFunds.provided.przelewy24.bankAccountHolder String = Always Provided
sourceOfFunds.provided.sepa = CONDITIONAL
sourceOfFunds.provided.sepa.bankAccountHolder String = Always Provided
sourceOfFunds.provided.sepa.bic Alphanumeric = CONDITIONAL
sourceOfFunds.provided.sepa.iban String = Always Provided
sourceOfFunds.provided.sofort = CONDITIONAL
sourceOfFunds.provided.sofort.bankAccountHolder String = CONDITIONAL
sourceOfFunds.provided.sofort.bankAccountNumber String = CONDITIONAL
sourceOfFunds.provided.sofort.bankIdentifier String = CONDITIONAL
sourceOfFunds.provided.sofort.bic String = CONDITIONAL
sourceOfFunds.provided.sofort.country Upper case alphabetic text = CONDITIONAL
sourceOfFunds.provided.sofort.iban String = CONDITIONAL
sourceOfFunds.provided.trustly = CONDITIONAL
sourceOfFunds.provided.trustly.bankAccountHolder String = Always Provided
sourceOfFunds.provided.weChatPay = CONDITIONAL
sourceOfFunds.provided.weChatPay.accountHolder String = Always Provided
sourceOfFunds.token Alphanumeric = CONDITIONAL
If account identifier details are also contained in the request, or the request contains a session with account identifier details, these take precedence over the details stored against the token.
sourceOfFunds.tokenRequestorID Alphanumeric = CONDITIONAL
sourceOfFunds.type Enumeration = CONDITIONAL
If you are making a payment with a gateway token, then you can leave this field unset, and only populate the sourceOfFund.token field.
subgatewayMerchant = CONDITIONAL
- operate a gateway, and
- you are not boarding your merchants onto the gateway, and
- you are enabled for this capability on the gateway.
If you are such a gateway, use these fields to provide information about your merchant, so that our gateway can process their transaction on your behalf.
Note: In these cases, you must also provide a value for field order.merchantCategoryCode
subgatewayMerchant.acquirer[n] = Always Provided
Each record in this group applies to one acquirer. If your gateway knows exactly which acquirer will use for this transaction, then you can provide just that acquirer's data. Alternatively, you can specify a set of acquirers, in which case the gateway will select between them based on the routing rules that configured in our gateway.
In this group, the term 'acquirer' includes banks acquiring scheme cards (such as MasterCard,or Visa), and alternative providers (such as UnionPay, or SEPA)subgatewayMerchant.acquirer[n].3DS1 = CONDITIONAL
subgatewayMerchant.acquirer[n].3DS1.mastercardSecureCode = CONDITIONAL
subgatewayMerchant.acquirer[n].3DS1.mastercardSecureCode.merchantId String = CONDITIONAL
subgatewayMerchant.acquirer[n].3DS1.verifiedByVisa = CONDITIONAL
subgatewayMerchant.acquirer[n].3DS1.verifiedByVisa.cardAcceptorId String = CONDITIONAL
subgatewayMerchant.acquirer[n].3DS1.verifiedByVisa.cardAcceptorTerminalId String = CONDITIONAL
subgatewayMerchant.acquirer[n].acquirerMerchantId String = Always Provided
subgatewayMerchant.acquirer[n].amexSafeKey = CONDITIONAL
subgatewayMerchant.acquirer[n].amexSafeKey.merchantId Regex = CONDITIONAL
subgatewayMerchant.acquirer[n].countryCode Upper case alphabetic text = CONDITIONAL
subgatewayMerchant.acquirer[n].fraudRate Integer = CONDITIONAL
subgatewayMerchant.acquirer[n].id String = Always Provided
subgatewayMerchant.acquirer[n].merchantCategoryCode Digits = CONDITIONAL
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.
subgatewayMerchant.address = CONDITIONAL
subgatewayMerchant.address.city String = Always Provided
subgatewayMerchant.address.countryCode Upper case alphabetic text = Always Provided
subgatewayMerchant.address.postcodeZip String = Always Provided
subgatewayMerchant.address.stateProvince String = Always Provided
For Canadian merchants provide the 2-letter ISO 3166-2 province code.
subgatewayMerchant.address.street1 String = Always Provided
subgatewayMerchant.address.street2 String = CONDITIONAL
subgatewayMerchant.authentication[n] = CONDITIONAL
subgatewayMerchant.authentication[n].3DS2 = CONDITIONAL
This API assumes that a merchant has only one registration for a each 3DS2 scheme across all the acquirers. If your merchant has more than one 3DS2 registration that could apply to this transaction, then you need to provide a lineOfBusiness field to narrow to one registration.
subgatewayMerchant.authentication[n].3DS2.requestorId String = CONDITIONAL
subgatewayMerchant.authentication[n].3DS2.requestorName String = CONDITIONAL
subgatewayMerchant.authentication[n].acquirerBIN Digits = CONDITIONAL
subgatewayMerchant.authentication[n].protocol Enumeration = Always Provided
subgatewayMerchant.id Alphanumeric + additional characters = Always Provided
subgatewayMerchant.name String = Always Provided
subgatewayMerchant.websiteUrl Url = Always Provided
timeOfLastUpdate DateTime = CONDITIONAL
timeOfRecord DateTime = CONDITIONAL
transaction = Always Provided
transaction.acquirer.merchantId String = CONDITIONAL
transaction.amount Decimal = Always Provided
transaction.authenticationStatus Enumeration = CONDITIONAL
transaction.currency Upper case alphabetic text = Always Provided
transaction.id String = Always Provided
- 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.
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.