Retrieve Session
Request to obtain the request fields contained in the session
URL | https://test-gateway.mastercard.com/api/rest/version/81/merchant/{merchantId}/session/{sessionId} |
HTTP Method | GET |
Authentication |
This operation requires authentication via one of the following methods:
|
Request Parameters
correlationId String = OPTIONAL
responseControls = OPTIONAL
responseControls.sensitiveData String = OPTIONAL
{merchantId} Alphanumeric + additional characters COMPULSORY
{sessionId} ASCII Text COMPULSORY
Response Parameters
merchant Alphanumeric + additional characters = Always Provided
session = Always Provided
session.id ASCII Text = Always Provided
session.updateStatus Enumeration = Always Provided
session.version ASCII Text = Always Provided
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.
See Making Business Decisions Based on Session Content.
wallet.masterpass = CONDITIONAL
wallet.masterpass.allowedCardTypes String = CONDITIONAL
wallet.masterpass.longAccessToken String = CONDITIONAL
wallet.masterpass.merchantCheckoutId String = CONDITIONAL
wallet.masterpass.originUrl Url = CONDITIONAL
wallet.masterpass.payerAuthentication Enumeration = CONDITIONAL
wallet.masterpass.requestToken String = CONDITIONAL
wallet.masterpass.secondaryOriginUrl Url = CONDITIONAL
wallet.visaCheckout = CONDITIONAL
wallet.visaCheckout.cardArts String = CONDITIONAL
wallet.visaCheckout.cardBrand String = CONDITIONAL
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.address = CONDITIONAL
accountFunding.recipient.address.city String = CONDITIONAL
accountFunding.recipient.address.country Upper case alphabetic text = CONDITIONAL
accountFunding.recipient.address.postCodeZip String = CONDITIONAL
accountFunding.recipient.address.stateProvinceCode String = CONDITIONAL
accountFunding.recipient.address.street String = CONDITIONAL
accountFunding.recipient.address.street2 String = CONDITIONAL
accountFunding.recipient.country Upper case alphabetic text = CONDITIONAL
accountFunding.recipient.dateOfBirth Date = CONDITIONAL
accountFunding.recipient.firstName String = CONDITIONAL
accountFunding.recipient.identification = CONDITIONAL
accountFunding.recipient.identification.country Upper case alphabetic text = CONDITIONAL
accountFunding.recipient.identification.type Enumeration = CONDITIONAL
accountFunding.recipient.identification.value 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
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 = 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.
airline = CONDITIONAL
airline.bookingReference Alphanumeric = CONDITIONAL
airline.documentType Enumeration = CONDITIONAL
airline.itinerary = CONDITIONAL
airline.itinerary.leg[n] = CONDITIONAL
airline.itinerary.leg[n].carrierCode Regex = CONDITIONAL
airline.itinerary.leg[n].conjunctionTicketNumber Alphanumeric = CONDITIONAL
airline.itinerary.leg[n].couponNumber Alphanumeric = CONDITIONAL
airline.itinerary.leg[n].departureAirport Upper case alphabetic text = CONDITIONAL
airline.itinerary.leg[n].departureDate Date = CONDITIONAL
airline.itinerary.leg[n].departureTax Decimal = CONDITIONAL
airline.itinerary.leg[n].departureTime Time = CONDITIONAL
airline.itinerary.leg[n].destinationAirport Upper case alphabetic text = CONDITIONAL
airline.itinerary.leg[n].destinationArrivalDate Date = CONDITIONAL
airline.itinerary.leg[n].destinationArrivalTime Time = CONDITIONAL
airline.itinerary.leg[n].endorsementsRestrictions Alphanumeric = CONDITIONAL
airline.itinerary.leg[n].exchangeTicketNumber Alphanumeric = CONDITIONAL
airline.itinerary.leg[n].fare Decimal = CONDITIONAL
airline.itinerary.leg[n].fareBasis Alphanumeric = CONDITIONAL
airline.itinerary.leg[n].fees Decimal = CONDITIONAL
airline.itinerary.leg[n].flightNumber Alphanumeric = CONDITIONAL
airline.itinerary.leg[n].stopoverPermitted Boolean = CONDITIONAL
airline.itinerary.leg[n].taxes Decimal = CONDITIONAL
airline.itinerary.leg[n].travelClass Alphanumeric = CONDITIONAL
airline.itinerary.numberInParty Digits = CONDITIONAL
airline.itinerary.originCountry Upper case alphabetic text = CONDITIONAL
airline.passenger[n] = CONDITIONAL
airline.passenger[n].firstName String = CONDITIONAL
airline.passenger[n].frequentFlyerNumber String = CONDITIONAL
airline.passenger[n].lastName String = CONDITIONAL
airline.passenger[n].middleName String = CONDITIONAL
airline.passenger[n].specificInformation Alphanumeric = CONDITIONAL
airline.passenger[n].title String = CONDITIONAL
airline.planNumber Alphanumeric = CONDITIONAL
airline.ticket = CONDITIONAL
airline.ticket.conjunctionTicketIndicator Boolean = CONDITIONAL
airline.ticket.eTicket Boolean = CONDITIONAL
airline.ticket.exchangedTicketNumber Alphanumeric = CONDITIONAL
airline.ticket.issue = CONDITIONAL
airline.ticket.issue.address String = CONDITIONAL
airline.ticket.issue.carrierCode Regex = CONDITIONAL
airline.ticket.issue.carrierName Alphanumeric = CONDITIONAL
airline.ticket.issue.city String = CONDITIONAL
airline.ticket.issue.country Upper case alphabetic text = CONDITIONAL
airline.ticket.issue.date Date = CONDITIONAL
airline.ticket.issue.travelAgentCode Alphanumeric = CONDITIONAL
airline.ticket.issue.travelAgentName Alphanumeric = CONDITIONAL
airline.ticket.restricted Boolean = CONDITIONAL
airline.ticket.taxOrFee[n] = CONDITIONAL
airline.ticket.taxOrFee[n].amount Decimal = CONDITIONAL
airline.ticket.taxOrFee[n].type Alphanumeric = CONDITIONAL
airline.ticket.ticketNumber Alphanumeric = CONDITIONAL
airline.ticket.totalFare Decimal = CONDITIONAL
airline.ticket.totalFees Decimal = CONDITIONAL
airline.ticket.totalTaxes Decimal = CONDITIONAL
airline.transactionType Enumeration = CONDITIONAL
appPayment = CONDITIONAL
appPayment.returnUrl Url = CONDITIONAL
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
Parameters in this group apply to both 3-D Secure authentication version 1 and 3-D Secure Authentication version 2.
Depending on the 3-D Secure authentication version applicable you will also need additional parameters:
- 3-D Secure authentication version 1: see the authentication.3ds1 parameter group.
- 3-D Secure authentication version 2: see the authentication.3ds2 parameter group.
authentication.3ds.acsEci 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.
authentication.3ds1 = CONDITIONAL
authentication.3ds1.paResStatus Alpha = CONDITIONAL
authentication.3ds1.veResEnrolled Alpha = CONDITIONAL
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.acsReference String = CONDITIONAL
authentication.3ds2.acsTransactionId String = CONDITIONAL
authentication.3ds2.authenticationScheme Enumeration = 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.dsReference String = CONDITIONAL
authentication.3ds2.protocolVersion Alphanumeric + additional characters = CONDITIONAL
authentication.3ds2.sdk = CONDITIONAL
authentication.3ds2.sdk.appId String = CONDITIONAL
This field corresponds to EMVCo field sdkAppID
authentication.3ds2.sdk.encryptedData String = CONDITIONAL
This field corresponds to EMVCo field sdkEncData
authentication.3ds2.sdk.ephemeralPublicKey JSON Text = CONDITIONAL
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 = 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.referenceNumber String = CONDITIONAL
authentication.3ds2.sdk.timeout Integer = CONDITIONAL
This field corresponds to EMVCo field sdkMaxTimeout
authentication.3ds2.sdk.transactionId String = CONDITIONAL
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.acceptVersions Comma Separated Enumeration = CONDITIONAL
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.amount Decimal = CONDITIONAL
authentication.challengePreference Enumeration = CONDITIONAL
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 = CONDITIONAL
authentication.methodNotificationUrl Url = CONDITIONAL
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.
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.redirectResponseUrl Url = CONDITIONAL
You must provide this URL, unless you are certain that there will be no interaction with the payer.
authentication.time DateTime = CONDITIONAL
authentication.transactionId String = 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
browserPayment = CONDITIONAL
browserPayment.openBankingBankTransfer = CONDITIONAL
browserPayment.openBankingBankTransfer.refundConsent Boolean = CONDITIONAL
browserPayment.operation Enumeration = CONDITIONAL
browserPayment.paypal = CONDITIONAL
browserPayment.paypal.agreementConfirmation Enumeration = CONDITIONAL
browserPayment.paypal.displayShippingAddress Boolean = CONDITIONAL
browserPayment.paypal.overrideShippingAddress Boolean = CONDITIONAL
browserPayment.paypal.paymentConfirmation Enumeration = CONDITIONAL
browserPayment.preferredLanguage String = CONDITIONAL
browserPayment.returnUrl Url = CONDITIONAL
constraints = CONDITIONAL
constraints.paymentPlans = CONDITIONAL
constraints.paymentPlans.deferralPeriod Integer = CONDITIONAL
constraints.paymentPlans.numberOfPayments Integer = CONDITIONAL
constraints.paymentPlans.supported[n] String = CONDITIONAL
See Payment Plans for the supported payment plans and their identifiers.
correlationId String = CONDITIONAL
creditCardBillPayment = CONDITIONAL
creditCardBillPayment.paymentSender = CONDITIONAL
creditCardBillPayment.paymentSender.address = CONDITIONAL
creditCardBillPayment.paymentSender.address.city String = CONDITIONAL
creditCardBillPayment.paymentSender.address.country Upper case alphabetic text = CONDITIONAL
creditCardBillPayment.paymentSender.address.postcodeZip Alphanumeric + additional characters = CONDITIONAL
creditCardBillPayment.paymentSender.address.stateProvinceCode String = CONDITIONAL
creditCardBillPayment.paymentSender.address.street String = CONDITIONAL
creditCardBillPayment.paymentSender.bankAccountNumber Digits = CONDITIONAL
creditCardBillPayment.paymentSender.cardNumber Digits = CONDITIONAL
creditCardBillPayment.paymentSender.firstName String = CONDITIONAL
creditCardBillPayment.paymentSender.lastName String = CONDITIONAL
cruise = CONDITIONAL
cruise.bookingReference String = CONDITIONAL
cruise.company = CONDITIONAL
cruise.company.contact = CONDITIONAL
cruise.company.contact.companyPhone Telephone Number = CONDITIONAL
cruise.company.contact.customerServicePhone Telephone Number = CONDITIONAL
cruise.departureDate Date = CONDITIONAL
This field is required when cruise industry data is provided.
cruise.departurePort = CONDITIONAL
cruise.departurePort.address = CONDITIONAL
cruise.departurePort.address.city String = CONDITIONAL
cruise.departurePort.address.country Upper case alphabetic text = CONDITIONAL
cruise.departurePort.address.postCodeZip Alphanumeric + additional characters = CONDITIONAL
cruise.departurePort.address.stateProvinceCode String = CONDITIONAL
cruise.departurePort.address.street String = CONDITIONAL
cruise.departurePort.address.street2 String = CONDITIONAL
cruise.passenger[n] = CONDITIONAL
cruise.passenger[n].firstName String = CONDITIONAL
cruise.passenger[n].folioNumber String = CONDITIONAL
cruise.passenger[n].lastName String = CONDITIONAL
cruise.passenger[n].middleName String = CONDITIONAL
cruise.passenger[n].title String = CONDITIONAL
cruise.returnDate Date = CONDITIONAL
This field is required when cruise.departureDate is provided and the value must be equal to or later than cruise.departureDate.
cruise.shipName String = CONDITIONAL
cruise.travelAgentCode Alphanumeric = CONDITIONAL
cruise.travelAgentName String = CONDITIONAL
cruise.travelPackageItems Comma separated enumeration = CONDITIONAL
If the value CRUISE_ONLY is provided then other items are not permitted in the list.
currencyConversion = CONDITIONAL
You can only provide DCC information on the initial transaction for an order.
If the initial transaction for an order is a payer authentication transaction with DCC information and the subsequent authorization or pay transaction contains different DCC information, that authorization or pay transaction will be rejected.
If DCC information is provided on subsequent capture or refund for an order, it will be ignored.
currencyConversion.exchangeRateTime DateTime = CONDITIONAL
currencyConversion.marginPercentage Decimal = CONDITIONAL
currencyConversion.payerAmount Decimal = CONDITIONAL
currencyConversion.payerCurrency Upper case alphabetic text = CONDITIONAL
currencyConversion.payerExchangeRate Decimal = CONDITIONAL
currencyConversion.providerReceipt String = CONDITIONAL
currencyConversion.requestId String = CONDITIONAL
currencyConversion.uptake Enumeration = 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.data String = 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.dateOfBirth Date = CONDITIONAL
customer.email Email = CONDITIONAL
customer.firstName String = CONDITIONAL
customer.identification = CONDITIONAL
customer.identification.country Upper case alphabetic text = CONDITIONAL
customer.identification.type Enumeration = CONDITIONAL
customer.identification.value String = CONDITIONAL
customer.lastName String = CONDITIONAL
customer.middleName String = CONDITIONAL
customer.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).
customer.nationalId String = CONDITIONAL
customer.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).
customer.taxRegistrationId String = CONDITIONAL
debtRepayment = CONDITIONAL
debtRepayment.recipient = CONDITIONAL
debtRepayment.recipient.accountIdentifier String = CONDITIONAL
debtRepayment.recipient.dateOfBirth Date = CONDITIONAL
debtRepayment.recipient.lastName String = CONDITIONAL
debtRepayment.recipient.postcodeZip 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.browserDetails = CONDITIONAL
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 = CONDITIONAL
device.browserDetails.acceptHeaders String = CONDITIONAL
This must be provided for authentication operations where authentication.channel is PAYER_BROWSER.
device.browserDetails.colorDepth Integer = CONDITIONAL
This must be provided for authentication operations where authentication.channel is PAYER_BROWSER.
device.browserDetails.javaEnabled Boolean = CONDITIONAL
This must be provided for authentication operations where authentication.channel is PAYER_BROWSER.
device.browserDetails.javaScriptEnabled Boolean = CONDITIONAL
device.browserDetails.language String = CONDITIONAL
This must be provided for authentication operations where authentication.channel is PAYER_BROWSER.
device.browserDetails.screenHeight Integer = CONDITIONAL
This must be provided for authentication operations where authentication.channel is PAYER_BROWSER.
device.browserDetails.screenWidth Integer = CONDITIONAL
This must be provided for authentication operations where authentication.channel is PAYER_BROWSER.
device.browserDetails.timeZone Browser Time Zone Offset = CONDITIONAL
This must be provided for authentication operations where authentication.channel is PAYER_BROWSER.
device.fingerprint String = CONDITIONAL
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
disbursementType Enumeration = CONDITIONAL
gatewayEntryPoint Enumeration = CONDITIONAL
initiator.userId String = CONDITIONAL
interaction = CONDITIONAL
interaction.operation Enumeration = CONDITIONAL
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.
locale String = CONDITIONAL
See Dynamic Currency Conversion for more detail.
merchant Alphanumeric + additional characters = Always Provided
order = CONDITIONAL
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 = CONDITIONAL
order.cashAdvance Boolean = CONDITIONAL
order.cashbackAmount Decimal = CONDITIONAL
This field corresponds to EMV tag 9F03
order.certainty Enumeration = CONDITIONAL
order.currency Upper case alphabetic text = CONDITIONAL
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.expectedNumberOfCaptures Digits = CONDITIONAL
The field indicates the total number of Capture requests you intend to submit for an order. For example, if you intend to deliver the goods in two shipments and will capture part of the total authorized amount when you make each shipment, set the value of this field to 2.
If the value equals or drops below the actual number of successful Captures, then the gateway will prevent further Captures and void the outstanding Authorization amount (depending on your merchant profile configuration). If you are unsure of the number of Captures, set the value to 99, and to one on your last Capture.
If you do not provided a value for this field, but had previously provided one, the previous value is applied. For example, if you provide a value 2 on the first Capture for the order and then submit a second Capture without a value, the gateway assumes that the value is still 2.
order.gratuityAmount Decimal = CONDITIONAL
order.id String = CONDITIONAL
order.industryPracticePaymentReason Enumeration = CONDITIONAL
A merchant initiated industry practice transaction must also contain the 'scheme transaction Id' from the associated cardholder initiated transaction.
You can provide the referenceOrderId of the relevant cardholder initiated transaction and the gateway will include the 'scheme transaction Id' on the industry practice transaction. For example, when you submit a 'delayed charge', you should provide the referenceOrderId of the cardholder-initiated transaction that resulted in the delayed charge.
Alternatively, you can provide the 'scheme transaction Id' of the cardholder initiated transaction in the industry practice transaction using the field transaction.acquirer.traceId.
You must have obtained the payer's consent prior to submitting industry practice transactions.
order.invoiceNumber String = CONDITIONAL
order.items[n] = CONDITIONAL
order.items[n].name String = CONDITIONAL
order.items[n].quantity Decimal = CONDITIONAL
order.items[n].serialNumber String = CONDITIONAL
order.items[n].sku String = CONDITIONAL
order.items[n].unitPrice Decimal = CONDITIONAL
order.localTaxRegistrationId String = CONDITIONAL
order.marketplace = CONDITIONAL
order.marketplace.retailerLocation Enumeration = CONDITIONAL
order.merchantCategoryCode Digits = CONDITIONAL
You only need to provide the MCC if you want to override the default value configured for your acquirer link.The value you provide must match one of those configured by your payment service provider.
order.merchantCharge = CONDITIONAL
order.merchantCharge.amount Decimal = CONDITIONAL
order.merchantCharge.type Enumeration = CONDITIONAL
order.netAmount Decimal = CONDITIONAL
order.notificationUrl Url = CONDITIONAL
order.owningEntity String = CONDITIONAL
order.purchaseType Enumeration = CONDITIONAL
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.reference String = CONDITIONAL
order.requestorName String = CONDITIONAL
order.reward = CONDITIONAL
order.reward.amount Decimal = CONDITIONAL
order.reward.balanceId Alphanumeric + additional characters = 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.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 = CONDITIONAL
order.subMerchant.bankIndustryCode Digits = CONDITIONAL
order.subMerchant.disputeContactPhone Telephone Number = CONDITIONAL
order.subMerchant.email Email = CONDITIONAL
order.subMerchant.governmentCountryCode Upper case alphabetic text = CONDITIONAL
order.subMerchant.identifier Alphanumeric + additional characters = CONDITIONAL
order.subMerchant.marketplaceId String = CONDITIONAL
order.subMerchant.phone String = CONDITIONAL
order.subMerchant.registeredName String = CONDITIONAL
order.subMerchant.tradingName String = CONDITIONAL
order.subMerchant.websiteUrl Url = CONDITIONAL
order.supply = CONDITIONAL
order.supply.preorder Boolean = CONDITIONAL
order.supply.preorderAvailabilityDate Date = CONDITIONAL
order.supply.reorder Boolean = 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
If you provide both this value and line item data, then the order.taxAmount MUST equal the total tax amount.
order.taxRegistrationId String = CONDITIONAL
order.taxStatus Enumeration = CONDITIONAL
order.transactionFiltering = CONDITIONAL
order.transactionFiltering.avsResponseCodeRules[n] = CONDITIONAL
order.transactionFiltering.avsResponseCodeRules[n].action Enumeration = CONDITIONAL
order.transactionFiltering.avsResponseCodeRules[n].avsResponseCode Enumeration = CONDITIONAL
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
- • 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.
partnerSolutionId String = CONDITIONAL
paymentPlan = CONDITIONAL
paymentPlan.offerId Alphanumeric + additional characters = CONDITIONAL
paymentType Enumeration = CONDITIONAL
referenceOrderId String = CONDITIONAL
Tokenization requests:
Identifier for the order which will be used to generate a gateway token. The gateway will attempt tokenization of payment credentials linked to the order ID.
The order identifier provided in this field must be linked to a successfully processed order which has card (FPAN / DPAN) as the payment method.
When providing this field, you must not provide card details in the sourceOfFunds.provided.card parameter group, and you must set the sourceOfFunds.type field to CARD.
Payment transactions:
When submitting:
- an industry practice payment, this is the reference to the initial cardholder-initiated transaction.
- a resubmission transaction, this is the reference to the order which is being resubmitted.
responseControls = CONDITIONAL
responseControls.sensitiveData String = CONDITIONAL
risk = CONDITIONAL
risk.bypassMerchantRiskRules Enumeration = CONDITIONAL
risk.custom String = CONDITIONAL
Field: risk.custom.headOfficeLocation
Value: London UK
risk.paymentRecipient = CONDITIONAL
risk.paymentRecipient.accountIdentifier String = CONDITIONAL
risk.paymentRecipient.dateOfBirth Date = CONDITIONAL
risk.paymentRecipient.lastName String = CONDITIONAL
risk.paymentRecipient.postcodeZip String = CONDITIONAL
session = Always Provided
session.id ASCII Text = Always Provided
session.updateStatus Enumeration = Always Provided
session.version ASCII Text = Always Provided
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.
See Making Business Decisions Based on Session Content.
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.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.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.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
origin.postcodeZip Alphanumeric + additional characters = CONDITIONAL
sourceOfFunds = CONDITIONAL
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.alipay = CONDITIONAL
sourceOfFunds.provided.alipay.payerCode String = CONDITIONAL
sourceOfFunds.provided.bancontact = CONDITIONAL
sourceOfFunds.provided.bancontact.bankAccountHolder String = CONDITIONAL
sourceOfFunds.provided.blik = CONDITIONAL
sourceOfFunds.provided.blik.bankAccountHolder String = CONDITIONAL
sourceOfFunds.provided.boletoBancario = CONDITIONAL
sourceOfFunds.provided.boletoBancario.actionType Enumeration = CONDITIONAL
sourceOfFunds.provided.boletoBancario.bankAccountHolder String = CONDITIONAL
sourceOfFunds.provided.boletoBancario.customerType Enumeration = CONDITIONAL
sourceOfFunds.provided.boletoBancario.daysBeforeAction Digits = CONDITIONAL
sourceOfFunds.provided.boletoBancario.dueDate Date = CONDITIONAL
sourceOfFunds.provided.card = CONDITIONAL
sourceOfFunds.provided.card.accountType Enumeration = CONDITIONAL
sourceOfFunds.provided.card.devicePayment = CONDITIONAL
- • 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. This applies when you have tokenized the payer's card number using a card scheme tokenization service such as Mastercard Digital Enablement Service (MDES).
sourceOfFunds.provided.card.devicePayment.cryptogramFormat Enumeration = CONDITIONAL
- • 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 = CONDITIONAL
This field is not applicable for payments using digital wallets or card scheme tokens.
sourceOfFunds.provided.card.devicePayment.onlinePaymentCryptogram Base64 = CONDITIONAL
- • 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 = CONDITIONAL
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.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.expiry = CONDITIONAL
sourceOfFunds.provided.card.expiry.month Digits = CONDITIONAL
sourceOfFunds.provided.card.expiry.year Digits = CONDITIONAL
sourceOfFunds.provided.card.maskedFpan Masked digits = CONDITIONAL
RequestNormally you do not need to populate this field, as the gateway will populate this field in the session, and populate it into the payment request when you submit the payment using the session. You would only provide this value, if you had access to FPAN information that was not available to the gateway. On responses, the gateway populates it with a form that the payer would recognize (also explained in more detail below).
Retrieve session response
The gateway always populates this field with its best understanding of the masked FPAN.If you are showing PAN data from the session to the payer, then use this field rather than sourceOfFunds.provided.card.number from the session. This is because this field contains a PAN that the payer will recognize whereas sourceOfFunds.provided.card.number could contain a scheme token, or device PAN which the payer will not recognize. After the payment is processed, the gateway will populate the sourceOfFunds.provided.card.number in the payment response with its best understanding of the masked FPAN. You can show this value to the payer after the payment is complete. This logic also applies to the maskedFpanExpiry field.
sourceOfFunds.provided.card.maskedFpanExpiry = CONDITIONAL
sourceOfFunds.provided.card.maskedFpanExpiry.month Digits = CONDITIONAL
sourceOfFunds.provided.card.maskedFpanExpiry.year Digits = CONDITIONAL
sourceOfFunds.provided.card.mobileWallet = CONDITIONAL
sourceOfFunds.provided.card.mobileWallet.3DSecure = CONDITIONAL
sourceOfFunds.provided.card.mobileWallet.3DSecure.eciIndicator Digits = CONDITIONAL
sourceOfFunds.provided.card.mobileWallet.3DSecure.onlinePaymentCryptogram Base64 = CONDITIONAL
sourceOfFunds.provided.card.mobileWallet.cryptogramFormat Enumeration = CONDITIONAL
sourceOfFunds.provided.card.nameOnCard String = CONDITIONAL
sourceOfFunds.provided.card.number Digits = CONDITIONAL
sourceOfFunds.provided.card.provided.card.p2pe = CONDITIONAL
sourceOfFunds.provided.card.provided.card.p2pe.cardBin Digits = CONDITIONAL
If you do not provided this, the gateway will not perform this check.
sourceOfFunds.provided.card.provided.card.p2pe.encryptionState String = CONDITIONAL
sourceOfFunds.provided.card.provided.card.p2pe.initializationVector Hex = CONDITIONAL
sourceOfFunds.provided.card.provided.card.p2pe.keySerialNumber Hex = CONDITIONAL
sourceOfFunds.provided.card.provided.card.p2pe.payload Hex = CONDITIONAL
sourceOfFunds.provided.card.provided.card.prefix Digits = CONDITIONAL
sourceOfFunds.provided.card.securityCode Digits = CONDITIONAL
sourceOfFunds.provided.card.sequenceNumber Digits = CONDITIONAL
sourceOfFunds.provided.card.storedOnFile Enumeration = CONDITIONAL
sourceOfFunds.provided.directDebitCanada = CONDITIONAL
sourceOfFunds.provided.directDebitCanada.accountType Enumeration = CONDITIONAL
sourceOfFunds.provided.directDebitCanada.bankAccountHolder String = CONDITIONAL
sourceOfFunds.provided.directDebitCanada.bankAccountNumber Alphanumeric + additional characters = CONDITIONAL
sourceOfFunds.provided.directDebitCanada.financialInstitutionNumber Digits = CONDITIONAL
sourceOfFunds.provided.directDebitCanada.transitNumber Digits = 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 = CONDITIONAL
sourceOfFunds.provided.epsUeberweisung = CONDITIONAL
sourceOfFunds.provided.epsUeberweisung.bankAccountCountryCode Alpha = CONDITIONAL
sourceOfFunds.provided.epsUeberweisung.bankAccountHolder String = CONDITIONAL
sourceOfFunds.provided.giftCard = CONDITIONAL
sourceOfFunds.provided.giftCard.expectedLocalBrand String = CONDITIONAL
sourceOfFunds.provided.giftCard.number Digits = CONDITIONAL
sourceOfFunds.provided.giftCard.pin Digits = CONDITIONAL
sourceOfFunds.provided.giropay = CONDITIONAL
sourceOfFunds.provided.giropay.bankIdentifier Digits = CONDITIONAL
sourceOfFunds.provided.giropay.bic Alphanumeric = CONDITIONAL
sourceOfFunds.provided.grabPay = CONDITIONAL
sourceOfFunds.provided.grabPay.accountHolder String = CONDITIONAL
sourceOfFunds.provided.ideal = CONDITIONAL
sourceOfFunds.provided.ideal.bic Alphanumeric = CONDITIONAL
sourceOfFunds.provided.klarnaPayLater = CONDITIONAL
sourceOfFunds.provided.klarnaPayLater.bankAccountCountryCode Upper case alphabetic text = CONDITIONAL
sourceOfFunds.provided.klarnaPayNow = CONDITIONAL
sourceOfFunds.provided.klarnaPayNow.bankAccountCountryCode Alpha = CONDITIONAL
sourceOfFunds.provided.openBankingBankTransfer = CONDITIONAL
sourceOfFunds.provided.openBankingBankTransfer.aspspId String = CONDITIONAL
sourceOfFunds.provided.oxxo = CONDITIONAL
sourceOfFunds.provided.oxxo.bankAccountHolder String = CONDITIONAL
sourceOfFunds.provided.oxxo.dueDate Date = CONDITIONAL
sourceOfFunds.provided.payU = CONDITIONAL
sourceOfFunds.provided.payU.bankAccountCountryCode Alpha = CONDITIONAL
sourceOfFunds.provided.payU.bankAccountHolder String = CONDITIONAL
sourceOfFunds.provided.payconiq = CONDITIONAL
sourceOfFunds.provided.payconiq.countryCode Alpha = 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 = CONDITIONAL
sourceOfFunds.provided.paysafecard.countryCode Alpha = CONDITIONAL
sourceOfFunds.provided.pbba = CONDITIONAL
sourceOfFunds.provided.pbba.returnUrl Url = CONDITIONAL
sourceOfFunds.provided.poli = CONDITIONAL
sourceOfFunds.provided.poli.bankAccountHolder String = CONDITIONAL
sourceOfFunds.provided.przelewy24 = CONDITIONAL
sourceOfFunds.provided.przelewy24.bankAccountHolder String = CONDITIONAL
sourceOfFunds.provided.sepa = CONDITIONAL
sourceOfFunds.provided.sepa.bankAccountHolder String = CONDITIONAL
sourceOfFunds.provided.sepa.bic Alphanumeric = CONDITIONAL
sourceOfFunds.provided.sepa.iban String = CONDITIONAL
sourceOfFunds.provided.sofort = CONDITIONAL
sourceOfFunds.provided.sofort.bankAccountCountryCode Upper case alphabetic text = CONDITIONAL
sourceOfFunds.provided.trustly = CONDITIONAL
sourceOfFunds.provided.trustly.bankAccountCountryCode Alpha = CONDITIONAL
sourceOfFunds.provided.trustly.bankAccountHolder String = CONDITIONAL
sourceOfFunds.provided.weChatPay = CONDITIONAL
sourceOfFunds.provided.weChatPay.accountHolder String = CONDITIONAL
sourceOfFunds.schemeTokenProvisioningIdentifier ASCII Text = CONDITIONAL
When providing this field, you must not provide card details in the sourceOfFunds.provided.card parameter group, and you must set the sourceOfFunds.type field to CARD.
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 sourceOfFunds.token field. However you can set this to CARD if you want to overwrite or augment the token data with a card security code, expiry date, or cardholder name.
subMerchant = CONDITIONAL
subMerchant.identifier Alphanumeric + additional characters = CONDITIONAL
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] = CONDITIONAL
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 = CONDITIONAL
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 = CONDITIONAL
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 = CONDITIONAL
subgatewayMerchant.address.countryCode Upper case alphabetic text = CONDITIONAL
subgatewayMerchant.address.postcodeZip String = CONDITIONAL
subgatewayMerchant.address.stateProvince String = CONDITIONAL
For Canadian merchants provide the 2-letter ISO 3166-2 province code.
subgatewayMerchant.address.street1 String = CONDITIONAL
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 = CONDITIONAL
subgatewayMerchant.id Alphanumeric + additional characters = CONDITIONAL
subgatewayMerchant.name String = CONDITIONAL
subgatewayMerchant.websiteUrl Url = CONDITIONAL
token Alphanumeric = CONDITIONAL
On response, the format of the token depends on the token generation strategy configured for your repository. See Tokenization for more details.
transaction = CONDITIONAL
transaction.acquirer = CONDITIONAL
transaction.acquirer.customData String = CONDITIONAL
transaction.acquirer.traceId String = CONDITIONAL
For a Mastercard transaction this identifier must contain the scheme issued transaction identifier, network code and network date, and is also known as the Trace ID. For a Visa or American Express transaction this identifier matches the scheme issued transaction identifier, also known as Transaction Identifier or TID. Refer to the scheme's documentation for more details.
Payment in a Series
You must provide the information returned in the Authorization/Payment/Verification response for the last payer-initiated transaction in the series (CIT).
Refund
You must provide the information returned in the Authorization/Payment response for the payment for which you are issuing a refund.
Resubmission
For resubmission transactions, the gateway will include the scheme transaction identifier from the failed transaction.
However, you may use this field to directly provide the scheme transaction identifier to be used on the resubmission in certain scenarios:
- Original failed transaction was processed outside the gateway.
- Multiple failed authorizations exist on the order and the resubmission needs to refer to a failed transaction which is not the latest.
transaction.acquirer.transactionId String = CONDITIONAL
transaction.amount Decimal = CONDITIONAL
transaction.currency Upper case alphabetic text = CONDITIONAL
transaction.deferredAuthorization Boolean = CONDITIONAL
transaction.discountAmount Decimal = CONDITIONAL
transaction.dutyAmount Decimal = CONDITIONAL
transaction.id String = CONDITIONAL
- 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.item[n] = CONDITIONAL
transaction.item[n].brand String = CONDITIONAL
transaction.item[n].category String = CONDITIONAL
transaction.item[n].description String = CONDITIONAL
transaction.item[n].detail = CONDITIONAL
transaction.item[n].detail.acquirerCustom JSON Text = CONDITIONAL
transaction.item[n].detail.commodityCode Digits = CONDITIONAL
transaction.item[n].detail.tax[n] = CONDITIONAL
transaction.item[n].detail.tax[n].amount Decimal = CONDITIONAL
transaction.item[n].detail.tax[n].rate Decimal = CONDITIONAL
transaction.item[n].detail.tax[n].type String = CONDITIONAL
transaction.item[n].detail.unitDiscountRate Decimal = CONDITIONAL
transaction.item[n].detail.unitTaxRate Decimal = CONDITIONAL
transaction.item[n].detail.unitTaxType String = CONDITIONAL
transaction.item[n].detail.unspsc Digits = CONDITIONAL
transaction.item[n].detail.upc Digits = CONDITIONAL
transaction.item[n].industryCategory Enumeration = CONDITIONAL
(order.item.unitPrice + order.item.tax) * order.item.quantity
transaction.item[n].name String = CONDITIONAL
transaction.item[n].quantity Decimal = CONDITIONAL
transaction.item[n].sku String = CONDITIONAL
transaction.item[n].unitDiscountAmount Decimal = CONDITIONAL
transaction.item[n].unitOfMeasure String = CONDITIONAL
transaction.item[n].unitPrice Decimal = CONDITIONAL
transaction.item[n].unitTaxAmount Decimal = CONDITIONAL
transaction.itemAmount Decimal = CONDITIONAL
transaction.merchantNote String = CONDITIONAL
transaction.payerConsentForStoringCardDetails Enumeration = CONDITIONAL
transaction.priorApproval Enumeration = CONDITIONAL
transaction.reference String = CONDITIONAL
transaction.resubmission Boolean = CONDITIONAL
transaction.shippingAndHandlingAmount Decimal = CONDITIONAL
transaction.shippingAndHandlingTaxAmount Decimal = CONDITIONAL
transaction.shippingAndHandlingTaxRate Decimal = CONDITIONAL
transaction.source Enumeration = CONDITIONAL
If you have an existing agreement with the payer that authorizes you to process this payment (for example, a recurring payment) then set this value to MERCHANT.You only need to provide transaction.source if you want to override the default value configured for your acquirer link.
Note:
- You can only override the default value if you have the requisite permission.
- The value you provide must match one of those configured by your payment service provider.
- You can only set the transaction source on the initial transaction on an order. It cannot be changed on subsequent transactions.
transaction.targetTransactionId String = CONDITIONAL
For example: This can be the transaction id of the contactless transaction which was processed with a single tap indicator and you want to provide the PIN in this request.
transaction.tax[n] = CONDITIONAL
transaction.tax[n].amount Decimal = CONDITIONAL
transaction.tax[n].rate Decimal = CONDITIONAL
transaction.tax[n].type String = CONDITIONAL
transaction.taxAmount Decimal = CONDITIONAL
transaction.taxStatus Enumeration = CONDITIONAL
transactionSource Enumeration = CONDITIONAL
If you have an existing agreement with the payer that authorizes you to process this payment (for example, a recurring payment) then set this value to MERCHANT.You only need to provide transaction.source if you want to override the default value configured for your acquirer link.
Note:
- You can only override the default value if you have the requisite permission.
- The value you provide must match one of those configured by your payment service provider.
- You can only set the transaction source on the initial transaction on an order. It cannot be changed on subsequent transactions.
verificationStrategy Enumeration = CONDITIONAL
- BASIC you must also provide the card expiry date in the sourceOfFunds.provided.card.expiry parameter group.
- ACQUIRER you must also provide the card expiry date in the sourceOfFunds.provided.card.expiry parameter group and the currency in the transaction.currency field.
- ACCOUNT_UPDATER you must also provide a currency in the transaction.currency field and the sourceOfFunds parameter group is optional.
- you need to be enabled for Account Updater by your payment service provider.
- you can subsequently inquire about any updates the gateway has made to the token based on the Account Updater response using the RETRIEVE_TOKEN or SEARCH_TOKENS operations.