Initiate Authentication
Request returning which payer authentication mechanism (e.g. 3-D Secure authentication version 2, 3-D Secure authentication version 1, RuPay PaySecure) the gateway recommends you to use for this order.
Where both 3-D Secure Authentication version 1 and version 2 are available the gateway returns 3-D Secure authentication version 2.
You must provide details about the card, the purpose of the authentication (e.g payment or card registration only), and how the payer will interact with the authentication process (e.g. via the browser or mobile app).
You can provide the actual card details, or a gateway token, scheme token or device payment details.
The response will indicate, if payer authentication is available. You can either
- only proceed with the Authenticate Payer operation where the response indicates that payer authentication is available (transaction.authenticationStatus=AUTHENTICATION_AVAILABLE ) or
- (to simplify your integration) always proceed with the Authenticate Payer operation. Where no payer authentication is available, the payer will simply be redirected back to your website.
When using a payment session build your integration as follows:
- When you create the payment session, populate it with all the transaction data required for the Authenticate Payer operation.
- As soon as you have the card number, invoke the Initiate Authentication operation with the payment session identifier. It is recommended that you perform this asynchronously, so that the payer can continue filling out payment details.
- When the payers clicks PAY, update the payment session with the additional data entered by the payer and invoke the Authenticate Payer operation with the payment session identifier.
- On your website, receive the POST callback from the gateway following the Authenticate Payer operation and submit the payment for processing by the gateway with the payment session identifier.
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-gateway.mastercard.com/api/nvp/version/81 |
HTTP Method | POST |
Authentication |
This operation requires authentication via one of the following methods:
|
Request Parameters
apiOperation String =INITIATE_AUTHENTICATION FIXED
merchant Alphanumeric + additional characters = COMPULSORY
order.currency Upper case alphabetic text = COMPULSORY
order.id String = COMPULSORY
session.id ASCII Text = OPTIONAL
transaction.id 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.
apiOperation String =INITIATE_AUTHENTICATION 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.acceptVersions Comma Separated Enumeration = OPTIONAL
You only need to provide a value if you want to restrict the authentication methods you will accept.
If you do not specify a value, then the gateway treats it as if you will accept all available authentication methods.
If you accept both 3DS2 and 3DS1, then the gateway will use 3-D Secure version 2 if supported by the issuer and fallback to use 3-D Secure version 1 if it is not.
authentication.methodNotificationUrl Url = OPTIONAL
You only need to provide this value if you want to be notified on completion of the 3DS Method call.
If you do not specify a value, and if Method URL is supported for the transaction, then the gateway will handle the Method completion on behalf of you.
correlationId String = OPTIONAL
merchant Alphanumeric + additional characters = COMPULSORY
order = OPTIONAL
order.reference String = OPTIONAL
order.subMerchant = OPTIONAL
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 = OPTIONAL
order.subMerchant.address.city String = OPTIONAL
order.subMerchant.address.company String = OPTIONAL
order.subMerchant.address.country Upper case alphabetic text = OPTIONAL
order.subMerchant.address.postcodeZip Alphanumeric + additional characters = OPTIONAL
order.subMerchant.address.stateProvince String = OPTIONAL
order.subMerchant.address.street String = OPTIONAL
order.subMerchant.address.street2 String = OPTIONAL
order.subMerchant.authentication[n] = OPTIONAL
order.subMerchant.authentication[n].3DS2 = OPTIONAL
order.subMerchant.authentication[n].3DS2.requestorId String = OPTIONAL
order.subMerchant.authentication[n].3DS2.requestorName String = OPTIONAL
order.subMerchant.authentication[n].protocol Enumeration = COMPULSORY
order.subMerchant.bankIndustryCode Digits = OPTIONAL
order.subMerchant.disputeContactPhone Telephone Number = OPTIONAL
order.subMerchant.email Email = OPTIONAL
order.subMerchant.identifier Alphanumeric + additional characters = COMPULSORY
order.subMerchant.phone String = OPTIONAL
order.subMerchant.registeredName String = OPTIONAL
order.subMerchant.tradingName String = COMPULSORY
order.subMerchant.websiteUrl Url = OPTIONAL
order.walletProvider Enumeration = OPTIONAL
order.currency Upper case alphabetic text = COMPULSORY
order.id String = COMPULSORY
order.merchantCategoryCode Digits = OPTIONAL
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.
order.notificationUrl Url = OPTIONAL
partnerSolutionId String = 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.
sourceOfFunds = OPTIONAL
sourceOfFunds.provided = OPTIONAL
sourceOfFunds.provided.card = OPTIONAL
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
You must provide this field if you have it. This field is not applicable for payments using digital wallets.
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. For MDES (Mastercard Digital Enablement Service) tokens this is the UCAF cryptogram (de48se43Data). For VTS (Visa Token Service) tokens this is the TAVV cryptogram.
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.number Digits = OPTIONAL
- 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.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.
sourceOfFunds.type Enumeration = OPTIONAL
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 = OPTIONAL
- 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] = COMPULSORY
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 = OPTIONAL
subgatewayMerchant.acquirer[n].3DS1.mastercardSecureCode = OPTIONAL
subgatewayMerchant.acquirer[n].3DS1.mastercardSecureCode.merchantId String = OPTIONAL
subgatewayMerchant.acquirer[n].3DS1.verifiedByVisa = OPTIONAL
subgatewayMerchant.acquirer[n].3DS1.verifiedByVisa.cardAcceptorId String = OPTIONAL
subgatewayMerchant.acquirer[n].3DS1.verifiedByVisa.cardAcceptorTerminalId String = OPTIONAL
subgatewayMerchant.acquirer[n].acquirerMerchantId String = COMPULSORY
subgatewayMerchant.acquirer[n].amexSafeKey = OPTIONAL
subgatewayMerchant.acquirer[n].amexSafeKey.merchantId Regex = OPTIONAL
subgatewayMerchant.acquirer[n].countryCode Upper case alphabetic text = OPTIONAL
subgatewayMerchant.acquirer[n].fraudRate Integer = OPTIONAL
subgatewayMerchant.acquirer[n].id String = COMPULSORY
subgatewayMerchant.acquirer[n].merchantCategoryCode Digits = OPTIONAL
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 = OPTIONAL
subgatewayMerchant.address.city String = COMPULSORY
subgatewayMerchant.address.countryCode Upper case alphabetic text = COMPULSORY
subgatewayMerchant.address.postcodeZip String = COMPULSORY
subgatewayMerchant.address.stateProvince String = COMPULSORY
For Canadian merchants provide the 2-letter ISO 3166-2 province code.
subgatewayMerchant.address.street1 String = COMPULSORY
subgatewayMerchant.address.street2 String = OPTIONAL
subgatewayMerchant.authentication[n] = OPTIONAL
subgatewayMerchant.authentication[n].3DS2 = OPTIONAL
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 = OPTIONAL
subgatewayMerchant.authentication[n].3DS2.requestorName String = OPTIONAL
subgatewayMerchant.authentication[n].acquirerBIN Digits = OPTIONAL
subgatewayMerchant.authentication[n].protocol Enumeration = COMPULSORY
subgatewayMerchant.id Alphanumeric + additional characters = COMPULSORY
subgatewayMerchant.name String = COMPULSORY
subgatewayMerchant.websiteUrl Url = COMPULSORY
transaction = OPTIONAL
transaction.reference String = OPTIONAL
transaction.id 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.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
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.3ds1 = 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.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.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.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.acceptVersions Comma Separated Enumeration = Always Provided
You only need to provide a value if you want to restrict the authentication methods you will accept.
If you do not specify a value, then the gateway treats it as if you will accept all available authentication methods.
If you accept both 3DS2 and 3DS1, then the gateway will use 3-D Secure version 2 if supported by the issuer and fallback to use 3-D Secure version 1 if it is not.
authentication.method Enumeration = CONDITIONAL
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.methodPostData Base64 = CONDITIONAL
authentication.redirect.customizedHtml.3ds2.methodUrl Url = CONDITIONAL
authentication.redirect.html String = CONDITIONAL
authentication.version Enumeration = Always Provided
correlationId 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.authenticationStatus Enumeration = CONDITIONAL
order.creationTime DateTime = Always Provided
order.currency Upper case alphabetic text = Always Provided
order.id String = Always Provided
order.lastUpdatedTime DateTime = Always Provided
order.merchantCategoryCode Digits = CONDITIONAL
order.notificationUrl Url = CONDITIONAL
order.reference 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.totalAuthorizedAmount Decimal = Always Provided
order.totalCapturedAmount Decimal = Always Provided
order.totalRefundedAmount Decimal = Always Provided
order.walletProvider Enumeration = CONDITIONAL
partnerSolutionId String = CONDITIONAL
response = Always Provided
response.accountUpdater = CONDITIONAL
response.accountUpdater.gatewayCode Enumeration = CONDITIONAL
The gateway assigns a replacement token, if your token repository is configured with the 'UNIQUE_ACCOUNT_IDENTIFIER' token management strategy and the repository already contains a token for the new card that was updated by the Account Updater.
For more details see Gateway Tokenization
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
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
sourceOfFunds.provided.card.expiry.year Digits = Always Provided
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.epsUeberweisung = CONDITIONAL
sourceOfFunds.provided.epsUeberweisung.bankAccountCountryCode Alpha = Always Provided
sourceOfFunds.provided.epsUeberweisung.bankAccountHolder String = CONDITIONAL
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.klarnaPayLater = CONDITIONAL
sourceOfFunds.provided.klarnaPayLater.bankAccountCountryCode Upper case alphabetic text = Always Provided
sourceOfFunds.provided.klarnaPayNow = CONDITIONAL
sourceOfFunds.provided.klarnaPayNow.bankAccountCountryCode Alpha = Always Provided
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.payU = CONDITIONAL
sourceOfFunds.provided.payU.bankAccountCountryCode Alpha = Always Provided
sourceOfFunds.provided.payU.bankAccountHolder String = 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.paysafecard = CONDITIONAL
sourceOfFunds.provided.paysafecard.accountEmail Email = Always Provided
sourceOfFunds.provided.paysafecard.countryCode Alpha = Always Provided
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.bankAccountCountryCode Upper case alphabetic text = 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.iban String = CONDITIONAL
sourceOfFunds.provided.trustly = CONDITIONAL
sourceOfFunds.provided.trustly.bankAccountCountryCode Alpha = Always Provided
sourceOfFunds.provided.trustly.bankAccountHolder String = Always Provided
sourceOfFunds.provided.weChatPay = CONDITIONAL
sourceOfFunds.provided.weChatPay.accountHolder String = Always Provided
sourceOfFunds.token Alphanumeric = CONDITIONAL
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.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.