Update Session
Request to add or update request fields contained in the session.
URL | https://test-nbkpayment.mtf.gateway.mastercard.com/api/rest/version/81/merchant/{merchantId}/session/{sessionId} |
HTTP Method | PUT |
Authentication |
This operation requires authentication via one of the following methods:
|
Request Parameters
accountFunding = OPTIONAL
accountFunding.purpose Enumeration = OPTIONAL
accountFunding.recipient = OPTIONAL
accountFunding.recipient.account = OPTIONAL
accountFunding.recipient.account.fundingMethod Enumeration = OPTIONAL
accountFunding.recipient.account.identifier String = OPTIONAL
accountFunding.recipient.account.identifierType Enumeration = OPTIONAL
accountFunding.recipient.address = OPTIONAL
accountFunding.recipient.address.city String = OPTIONAL
accountFunding.recipient.address.country Upper case alphabetic text = OPTIONAL
accountFunding.recipient.address.postCodeZip String = OPTIONAL
accountFunding.recipient.address.stateProvinceCode String = OPTIONAL
accountFunding.recipient.address.street String = OPTIONAL
accountFunding.recipient.address.street2 String = OPTIONAL
accountFunding.recipient.country Upper case alphabetic text = OPTIONAL
accountFunding.recipient.dateOfBirth Date = OPTIONAL
accountFunding.recipient.firstName String = OPTIONAL
accountFunding.recipient.identification = OPTIONAL
accountFunding.recipient.identification.country Upper case alphabetic text = OPTIONAL
accountFunding.recipient.identification.type Enumeration = OPTIONAL
accountFunding.recipient.identification.value String = OPTIONAL
accountFunding.recipient.lastName String = OPTIONAL
accountFunding.recipient.middleName String = OPTIONAL
accountFunding.recipient.postCodeZip String = OPTIONAL
accountFunding.recipient.stateProvinceCode String = OPTIONAL
accountFunding.senderIsRecipient Boolean = OPTIONAL
accountFunding.senderType Enumeration = OPTIONAL
agreement = OPTIONAL
Do not provide this parameter group if you are storing the payment details for subsequent payer-initiated payments only.
See Credential on File, Cardholder, and Merchant Initiated Transactions for details.
agreement.amountVariability Enumeration = OPTIONAL
agreement.customData String = OPTIONAL
agreement.expiryDate Date = OPTIONAL
agreement.id String = OPTIONAL
- Recurring payments: you have an agreement with the payer that authorizes you to automatically debit their account at agreed intervals for fixed or variable amounts. For example, gym membership, phone bills, or magazine subscriptions.
- Installment payments: you have an agreement with the payer that authorizes you to process multiple payments over an agreed period of time for a single purchase. For example, the payer purchases an item for $1000 and pays for it in four monthly installments.
- Unscheduled: you have an agreement with the payer that authorizes you to process future payments when required. For example, the payer authorizes you to process an account top-up transaction for a transit card when the account balance drops below a certain threshold.
- Industry Practice: you have an agreement with the payer that authorizes you to initiate additional transactions to fulfil a standard business practice related to an original payment initiated by the payer. For example, a delayed charge for use of the hotel mini bar after the payer has checked out or a no show penalty charge when the payer fails to show for a booking.
agreement.maximumAmountPerPayment Decimal = OPTIONAL
agreement.minimumAmountPerPayment Decimal = OPTIONAL
agreement.minimumDaysBetweenPayments Integer = OPTIONAL
agreement.numberOfPayments Integer = OPTIONAL
agreement.paymentFrequency Enumeration = OPTIONAL
agreement.retailer = OPTIONAL
agreement.retailer.abbreviatedTradingName String = OPTIONAL
agreement.retailer.merchantCategoryCode String = OPTIONAL
agreement.retailer.tradingName String = OPTIONAL
agreement.startDate Date = OPTIONAL
agreement.type Enumeration = OPTIONAL
The gateway will use the value you specify for subsequent payments in the series.
airline = OPTIONAL
airline.bookingReference Alphanumeric = OPTIONAL
airline.documentType Enumeration = OPTIONAL
airline.itinerary = OPTIONAL
airline.itinerary.leg[n] = OPTIONAL
airline.itinerary.leg[n].carrierCode Regex = OPTIONAL
airline.itinerary.leg[n].conjunctionTicketNumber Alphanumeric = OPTIONAL
airline.itinerary.leg[n].couponNumber Alphanumeric = OPTIONAL
airline.itinerary.leg[n].departureAirport Upper case alphabetic text = OPTIONAL
airline.itinerary.leg[n].departureDate Date = OPTIONAL
airline.itinerary.leg[n].departureTax Decimal = OPTIONAL
airline.itinerary.leg[n].departureTime Time = OPTIONAL
airline.itinerary.leg[n].destinationAirport Upper case alphabetic text = OPTIONAL
airline.itinerary.leg[n].destinationArrivalDate Date = OPTIONAL
airline.itinerary.leg[n].destinationArrivalTime Time = OPTIONAL
airline.itinerary.leg[n].endorsementsRestrictions Alphanumeric = OPTIONAL
airline.itinerary.leg[n].exchangeTicketNumber Alphanumeric = OPTIONAL
airline.itinerary.leg[n].fare Decimal = OPTIONAL
airline.itinerary.leg[n].fareBasis Alphanumeric = OPTIONAL
airline.itinerary.leg[n].fees Decimal = OPTIONAL
airline.itinerary.leg[n].flightNumber Alphanumeric = OPTIONAL
airline.itinerary.leg[n].stopoverPermitted Boolean = OPTIONAL
airline.itinerary.leg[n].taxes Decimal = OPTIONAL
airline.itinerary.leg[n].travelClass Alphanumeric = OPTIONAL
airline.itinerary.numberInParty Digits = OPTIONAL
airline.itinerary.originCountry Upper case alphabetic text = OPTIONAL
airline.passenger[n] = OPTIONAL
airline.passenger[n].firstName String = OPTIONAL
airline.passenger[n].frequentFlyerNumber String = OPTIONAL
airline.passenger[n].lastName String = OPTIONAL
airline.passenger[n].middleName String = OPTIONAL
airline.passenger[n].specificInformation Alphanumeric = OPTIONAL
airline.passenger[n].title String = OPTIONAL
airline.planNumber Alphanumeric = OPTIONAL
airline.ticket = OPTIONAL
airline.ticket.conjunctionTicketIndicator Boolean = OPTIONAL
airline.ticket.eTicket Boolean = OPTIONAL
airline.ticket.exchangedTicketNumber Alphanumeric = OPTIONAL
airline.ticket.issue = OPTIONAL
airline.ticket.issue.address String = OPTIONAL
airline.ticket.issue.carrierCode Regex = OPTIONAL
airline.ticket.issue.carrierName Alphanumeric = OPTIONAL
airline.ticket.issue.city String = OPTIONAL
airline.ticket.issue.country Upper case alphabetic text = OPTIONAL
airline.ticket.issue.date Date = OPTIONAL
airline.ticket.issue.travelAgentCode Alphanumeric = OPTIONAL
airline.ticket.issue.travelAgentName Alphanumeric = OPTIONAL
airline.ticket.restricted Boolean = OPTIONAL
airline.ticket.taxOrFee[n] = OPTIONAL
airline.ticket.taxOrFee[n].amount Decimal = OPTIONAL
airline.ticket.taxOrFee[n].type Alphanumeric = OPTIONAL
airline.ticket.ticketNumber Alphanumeric = OPTIONAL
airline.ticket.totalFare Decimal = OPTIONAL
airline.ticket.totalFees Decimal = OPTIONAL
airline.ticket.totalTaxes Decimal = OPTIONAL
airline.transactionType Enumeration = OPTIONAL
appPayment = OPTIONAL
appPayment.returnUrl Url = OPTIONAL
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.3ds = OPTIONAL
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 = OPTIONAL
authentication.3ds.authenticationToken Base64 = OPTIONAL
For 3DS version 2, this field corresponds to the Authentication Value.
authentication.3ds.transactionId String = OPTIONAL
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 = OPTIONAL
authentication.3ds1.paResStatus Alpha = OPTIONAL
authentication.3ds1.veResEnrolled Alpha = OPTIONAL
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 = OPTIONAL
authentication.3ds2.acsReference String = OPTIONAL
authentication.3ds2.acsTransactionId String = OPTIONAL
authentication.3ds2.authenticationScheme Enumeration = OPTIONAL
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 = OPTIONAL
authentication.3ds2.dsReference String = OPTIONAL
authentication.3ds2.protocolVersion Alphanumeric + additional characters = OPTIONAL
authentication.3ds2.sdk = OPTIONAL
authentication.3ds2.sdk.appId String = OPTIONAL
This field corresponds to EMVCo field sdkAppID
authentication.3ds2.sdk.encryptedData String = OPTIONAL
This field corresponds to EMVCo field sdkEncData
authentication.3ds2.sdk.ephemeralPublicKey JSON Text = OPTIONAL
The key is a JSON Web Key (JWK) object in JSON format. When using the REST/JSON gateway API, express this as a JSON string (i.e the embedded quotes will be escaped).
This field corresponds to EMVCo field sdkEphemPubKey
authentication.3ds2.sdk.interface Enumeration = OPTIONAL
You only need to provide this value if you only support one of these formats.
This field corresponds to EMVCo data element sdkInterface in the field deviceRenderOptions.
authentication.3ds2.sdk.referenceNumber String = OPTIONAL
authentication.3ds2.sdk.timeout Integer = OPTIONAL
This field corresponds to EMVCo field sdkMaxTimeout
authentication.3ds2.sdk.transactionId String = OPTIONAL
authentication.3ds2.sdk.uiType Comma separated enumeration = OPTIONAL
You only need to provide this value if all of these values are not supported.
Note: OTHER_HTML is only supported when authentication.3ds2.sdk.interface allows a HTML UI format.
This field corresponds to EMVCo data element sdkUiType in the field deviceRenderOptions.
authentication.3ds2.statusReasonCode String = OPTIONAL
authentication.3ds2.transactionStatus Alpha = OPTIONAL
Refer to the EMVCo specification for 3-D Secure.
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.amount Decimal = OPTIONAL
authentication.challengePreference Enumeration = OPTIONAL
If you do not provide a value, the gateway will use NO_PREFERENCE. If there is no payer present (for example, recurring payments), then the gateway will ignore this field and use NO_CHALLENGE.
Note: 'challenge' means requiring the payer to take action to identify themselves, for example, entering a password.
authentication.goodsDescription String = OPTIONAL
authentication.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.
authentication.psd2 = OPTIONAL
authentication.psd2.exemption Enumeration = OPTIONAL
- For recurring payments provide the RECURRING_PAYMENT value only if the amount is the same. If the amount varies, provide MERCHANT_INITIATED_TRANSACTION instead.
authentication.redirectResponseUrl Url = OPTIONAL
You must provide this URL, unless you are certain that there will be no interaction with the payer.
authentication.time DateTime = OPTIONAL
authentication.transactionId String = OPTIONAL
billing = OPTIONAL
billing.address = OPTIONAL
billing.address.city String = OPTIONAL
billing.address.company String = OPTIONAL
billing.address.country Upper case alphabetic text = OPTIONAL
billing.address.postcodeZip Alphanumeric + additional characters = OPTIONAL
billing.address.stateProvince String = OPTIONAL
billing.address.stateProvinceCode String = OPTIONAL
billing.address.street String = OPTIONAL
billing.address.street2 String = OPTIONAL
browserPayment = OPTIONAL
browserPayment.openBankingBankTransfer = OPTIONAL
browserPayment.openBankingBankTransfer.refundConsent Boolean = OPTIONAL
browserPayment.operation Enumeration = OPTIONAL
browserPayment.paypal = OPTIONAL
browserPayment.paypal.agreementConfirmation Enumeration = OPTIONAL
browserPayment.paypal.displayShippingAddress Boolean = OPTIONAL
browserPayment.paypal.overrideShippingAddress Boolean = OPTIONAL
browserPayment.paypal.paymentConfirmation Enumeration = OPTIONAL
browserPayment.preferredLanguage String = OPTIONAL
browserPayment.returnUrl Url = OPTIONAL
constraints = OPTIONAL
constraints.paymentPlans = OPTIONAL
constraints.paymentPlans.deferralPeriod Integer = OPTIONAL
constraints.paymentPlans.numberOfPayments Integer = OPTIONAL
constraints.paymentPlans.supported[n] String = OPTIONAL
See Payment Plans for the supported payment plans and their identifiers.
correlationId String = OPTIONAL
creditCardBillPayment = OPTIONAL
creditCardBillPayment.paymentSender = OPTIONAL
creditCardBillPayment.paymentSender.address = OPTIONAL
creditCardBillPayment.paymentSender.address.city String = OPTIONAL
creditCardBillPayment.paymentSender.address.country Upper case alphabetic text = OPTIONAL
creditCardBillPayment.paymentSender.address.postcodeZip Alphanumeric + additional characters = OPTIONAL
creditCardBillPayment.paymentSender.address.stateProvinceCode String = OPTIONAL
creditCardBillPayment.paymentSender.address.street String = OPTIONAL
creditCardBillPayment.paymentSender.bankAccountNumber Digits = OPTIONAL
creditCardBillPayment.paymentSender.cardNumber Digits = OPTIONAL
creditCardBillPayment.paymentSender.firstName String = OPTIONAL
creditCardBillPayment.paymentSender.lastName String = OPTIONAL
cruise = OPTIONAL
cruise.bookingReference String = OPTIONAL
cruise.company = OPTIONAL
cruise.company.contact = OPTIONAL
cruise.company.contact.companyPhone Telephone Number = OPTIONAL
cruise.company.contact.customerServicePhone Telephone Number = OPTIONAL
cruise.departureDate Date = OPTIONAL
This field is required when cruise industry data is provided.
cruise.departurePort = OPTIONAL
cruise.departurePort.address = OPTIONAL
cruise.departurePort.address.city String = OPTIONAL
cruise.departurePort.address.country Upper case alphabetic text = OPTIONAL
cruise.departurePort.address.postCodeZip Alphanumeric + additional characters = OPTIONAL
cruise.departurePort.address.stateProvinceCode String = OPTIONAL
cruise.departurePort.address.street String = OPTIONAL
cruise.departurePort.address.street2 String = OPTIONAL
cruise.passenger[n] = OPTIONAL
cruise.passenger[n].firstName String = OPTIONAL
cruise.passenger[n].folioNumber String = OPTIONAL
cruise.passenger[n].lastName String = OPTIONAL
cruise.passenger[n].middleName String = OPTIONAL
cruise.passenger[n].title String = OPTIONAL
cruise.returnDate Date = OPTIONAL
This field is required when cruise.departureDate is provided and the value must be equal to or later than cruise.departureDate.
cruise.shipName String = OPTIONAL
cruise.travelAgentCode Alphanumeric = OPTIONAL
cruise.travelAgentName String = OPTIONAL
cruise.travelPackageItems Comma separated enumeration = OPTIONAL
If the value CRUISE_ONLY is provided then other items are not permitted in the list.
currencyConversion = OPTIONAL
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 = OPTIONAL
currencyConversion.marginPercentage Decimal = OPTIONAL
currencyConversion.payerAmount Decimal = OPTIONAL
currencyConversion.payerCurrency Upper case alphabetic text = OPTIONAL
currencyConversion.payerExchangeRate Decimal = OPTIONAL
currencyConversion.providerReceipt String = OPTIONAL
currencyConversion.requestId String = OPTIONAL
currencyConversion.uptake Enumeration = OPTIONAL
customer = OPTIONAL
customer.account = OPTIONAL
customer.account.authentication = OPTIONAL
customer.account.authentication.cardAssociation = OPTIONAL
customer.account.authentication.cardAssociation.action Enumeration = OPTIONAL
customer.account.authentication.data String = OPTIONAL
customer.account.authentication.method Enumeration = OPTIONAL
customer.account.authentication.time DateTime = OPTIONAL
customer.account.history = OPTIONAL
customer.account.history.addCardAttempts Integer = OPTIONAL
customer.account.history.annualActivity Integer = OPTIONAL
customer.account.history.creationDate Date = OPTIONAL
customer.account.history.issuerAuthentication = OPTIONAL
customer.account.history.issuerAuthentication.acsTransactionId String = OPTIONAL
customer.account.history.issuerAuthentication.authenticationToken Base64 = OPTIONAL
customer.account.history.issuerAuthentication.time DateTime = OPTIONAL
customer.account.history.issuerAuthentication.transactionId String = OPTIONAL
customer.account.history.issuerAuthentication.type Enumeration = OPTIONAL
customer.account.history.lastUpdated Date = OPTIONAL
customer.account.history.passwordLastChanged Date = OPTIONAL
customer.account.history.recentActivity Integer = OPTIONAL
customer.account.history.shippingAddressDate Date = OPTIONAL
customer.account.history.suspiciousActivity Boolean = OPTIONAL
customer.account.id String = OPTIONAL
customer.dateOfBirth Date = OPTIONAL
customer.email Email = OPTIONAL
customer.firstName String = OPTIONAL
customer.identification = OPTIONAL
customer.identification.country Upper case alphabetic text = OPTIONAL
customer.identification.type Enumeration = OPTIONAL
customer.identification.value String = OPTIONAL
customer.lastName String = OPTIONAL
customer.middleName String = OPTIONAL
customer.mobilePhone Telephone Number = OPTIONAL
The number consists of:
- ‘+’
- country code (1, 2 or 3 digits)
- ‘space’
- national number ( which may embed single spaces characters for readability).
customer.nationalId String = OPTIONAL
customer.phone Telephone Number = OPTIONAL
The number consists of:
- ‘+’
- country code (1, 2 or 3 digits)
- ‘space’
- national number ( which may embed single spaces characters for readability).
customer.taxRegistrationId String = OPTIONAL
debtRepayment = OPTIONAL
debtRepayment.recipient = OPTIONAL
debtRepayment.recipient.accountIdentifier String = OPTIONAL
debtRepayment.recipient.dateOfBirth Date = OPTIONAL
debtRepayment.recipient.lastName String = OPTIONAL
debtRepayment.recipient.postcodeZip String = OPTIONAL
device = OPTIONAL
device.ani String = OPTIONAL
device.aniCallType String = OPTIONAL
device.browser String = OPTIONAL
You must provide a value in this field if you are performing 3-D Secure authentication of the payer and set authentication.channel = PAYER_BROWSER.
device.browserDetails = OPTIONAL
You must provide values for fields in this parameter group if you are performing 3-D Secure authentication of the payer and set authentication.channel = PAYER_BROWSER.
device.browserDetails.3DSecureChallengeWindowSize Enumeration = OPTIONAL
device.browserDetails.acceptHeaders String = OPTIONAL
This must be provided for authentication operations where authentication.channel is PAYER_BROWSER.
device.browserDetails.colorDepth Integer = OPTIONAL
This must be provided for authentication operations where authentication.channel is PAYER_BROWSER.
device.browserDetails.javaEnabled Boolean = OPTIONAL
This must be provided for authentication operations where authentication.channel is PAYER_BROWSER.
device.browserDetails.javaScriptEnabled Boolean = OPTIONAL
device.browserDetails.language String = OPTIONAL
This must be provided for authentication operations where authentication.channel is PAYER_BROWSER.
device.browserDetails.screenHeight Integer = OPTIONAL
This must be provided for authentication operations where authentication.channel is PAYER_BROWSER.
device.browserDetails.screenWidth Integer = OPTIONAL
This must be provided for authentication operations where authentication.channel is PAYER_BROWSER.
device.browserDetails.timeZone Browser Time Zone Offset = OPTIONAL
This must be provided for authentication operations where authentication.channel is PAYER_BROWSER.
device.fingerprint String = OPTIONAL
device.hostname String = OPTIONAL
device.ipAddress String = OPTIONAL
IPv6 address will only be used in EMV 3DS authentication. Supplied IPv6 address will not be used for any other purposes.
device.mobilePhoneModel String = OPTIONAL
disbursementType Enumeration = OPTIONAL
gatewayEntryPoint Enumeration = OPTIONAL
initiator.userId String = OPTIONAL
interaction = OPTIONAL
interaction.operation Enumeration = OPTIONAL
locale String = OPTIONAL
See Dynamic Currency Conversion for more detail.
merchant Alphanumeric + additional characters = OPTIONAL
order = OPTIONAL
order.acceptPartialAmount Boolean = OPTIONAL
Unless you have been advised by your payment service provider that the gateway supports partial approvals for your acquirer, you can ignore this field.
If the gateway supports partial approvals for your acquirer you must set this field to TRUE else the transaction is rejected by the gateway.
order.amount Decimal = OPTIONAL
order.cashAdvance Boolean = OPTIONAL
order.cashbackAmount Decimal = OPTIONAL
This field corresponds to EMV tag 9F03
order.certainty Enumeration = OPTIONAL
order.currency Upper case alphabetic text = OPTIONAL
order.custom String = OPTIONAL
order.customerNote String = OPTIONAL
order.customerOrderDate Date = OPTIONAL
order.customerReference ASCII Text = OPTIONAL
order.description String = OPTIONAL
order.discount = OPTIONAL
order.discount.amount Decimal = OPTIONAL
order.discount.code String = OPTIONAL
order.discount.description String = OPTIONAL
order.dutyAmount Decimal = OPTIONAL
order.expectedNumberOfCaptures Digits = OPTIONAL
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 = OPTIONAL
order.id String = OPTIONAL
order.industryPracticePaymentReason Enumeration = OPTIONAL
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 = OPTIONAL
order.items[n] = OPTIONAL
order.items[n].name String = OPTIONAL
order.items[n].quantity Decimal = OPTIONAL
order.items[n].serialNumber String = OPTIONAL
order.items[n].sku String = OPTIONAL
order.items[n].unitPrice Decimal = OPTIONAL
order.localTaxRegistrationId String = OPTIONAL
order.marketplace = OPTIONAL
order.marketplace.retailerLocation Enumeration = OPTIONAL
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.merchantCharge = OPTIONAL
order.merchantCharge.amount Decimal = OPTIONAL
order.merchantCharge.type Enumeration = OPTIONAL
order.netAmount Decimal = OPTIONAL
order.notificationUrl Url = OPTIONAL
order.owningEntity String = OPTIONAL
order.purchaseType Enumeration = OPTIONAL
6051 (Quasi Cash – Merchant or Non-Financial Institutions – Foreign Currency, Non-Fiat Currency) and this transaction is for the purchase of cryptocurrency. Set the value to CRYPTOCURRENCY.
6211 (Securities – Brokers/Dealers) and this transaction is for the purchase of high-risk securities. Set the value to HIGH_RISK_SECURITIES.
6012 (Merchandise and Services—Customer Financial Institutions) or 6051 (Non-Financial Institutions – Foreign Currency, Non-Fiat Currency) and this transaction is for debt repayment. Set the value to DEBT_REPAYMENT.
If the transaction pulls money from an account for the purpose of crediting another account you must set purchase type to ACCOUNT_FUNDING.
You may set purchase type to OTHER for any other type of payment.
order.reference String = OPTIONAL
order.requestorName String = OPTIONAL
order.reward = OPTIONAL
order.reward.amount Decimal = OPTIONAL
order.reward.balanceId Alphanumeric + additional characters = OPTIONAL
order.shippingAndHandlingAmount Decimal = OPTIONAL
order.shippingAndHandlingTaxAmount Decimal = OPTIONAL
order.shippingAndHandlingTaxRate Decimal = OPTIONAL
order.statementDescriptor = OPTIONAL
order.statementDescriptor.address = OPTIONAL
order.statementDescriptor.address.city String = OPTIONAL
order.statementDescriptor.address.company String = OPTIONAL
order.statementDescriptor.address.country Upper case alphabetic text = OPTIONAL
order.statementDescriptor.address.postcodeZip Alphanumeric + additional characters = OPTIONAL
order.statementDescriptor.address.stateProvince String = OPTIONAL
For an address in Canada provide the 2-letter ISO 3166-2 province code.
order.statementDescriptor.address.street String = OPTIONAL
order.statementDescriptor.address.street2 String = OPTIONAL
order.statementDescriptor.name String = OPTIONAL
order.statementDescriptor.phone 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
For an address in Canada provide the 2-letter ISO 3166-2 province code.
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 = OPTIONAL
order.subMerchant.bankIndustryCode Digits = OPTIONAL
order.subMerchant.disputeContactPhone Telephone Number = OPTIONAL
order.subMerchant.email Email = OPTIONAL
order.subMerchant.governmentCountryCode Upper case alphabetic text = OPTIONAL
order.subMerchant.identifier Alphanumeric + additional characters = OPTIONAL
order.subMerchant.marketplaceId String = OPTIONAL
order.subMerchant.phone String = OPTIONAL
order.subMerchant.registeredName String = OPTIONAL
order.subMerchant.tradingName String = OPTIONAL
order.subMerchant.websiteUrl Url = OPTIONAL
order.supply = OPTIONAL
order.supply.preorder Boolean = OPTIONAL
order.supply.preorderAvailabilityDate Date = OPTIONAL
order.supply.reorder Boolean = OPTIONAL
order.tax[n] = OPTIONAL
order.tax[n].amount Decimal = OPTIONAL
order.tax[n].rate Decimal = OPTIONAL
order.tax[n].type String = OPTIONAL
order.taxAmount Decimal = OPTIONAL
If you provide both this value and line item data, then the order.taxAmount MUST equal the total tax amount.
order.taxRegistrationId String = OPTIONAL
order.taxStatus Enumeration = OPTIONAL
order.transactionFiltering = OPTIONAL
order.transactionFiltering.avsResponseCodeRules[n] = OPTIONAL
order.transactionFiltering.avsResponseCodeRules[n].action Enumeration = OPTIONAL
order.transactionFiltering.avsResponseCodeRules[n].avsResponseCode Enumeration = OPTIONAL
order.valueTransfer = OPTIONAL
order.valueTransfer.accountType Enumeration = OPTIONAL
order.valueTransfer.amount Decimal = OPTIONAL
order.valueTransfer.currency Upper case alphabetic text = OPTIONAL
The default value is order.currency.
order.valueTransfer.numberOfCards Integer = OPTIONAL
order.walletIndicator String = OPTIONAL
order.walletProvider Enumeration = OPTIONAL
- • 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 = OPTIONAL
paymentPlan = OPTIONAL
paymentPlan.offerId Alphanumeric + additional characters = OPTIONAL
paymentType Enumeration = OPTIONAL
referenceOrderId String = OPTIONAL
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 = OPTIONAL
responseControls.sensitiveData String = OPTIONAL
risk = OPTIONAL
risk.bypassMerchantRiskRules Enumeration = OPTIONAL
risk.custom String = OPTIONAL
Field: risk.custom.headOfficeLocation
Value: London UK
risk.paymentRecipient = OPTIONAL
risk.paymentRecipient.accountIdentifier String = OPTIONAL
risk.paymentRecipient.dateOfBirth Date = OPTIONAL
risk.paymentRecipient.lastName String = OPTIONAL
risk.paymentRecipient.postcodeZip String = OPTIONAL
session.version ASCII Text = OPTIONAL
To use optimistic locking, record session.version when you make your decisions, and then pass that value in session.version when you submit your request operation to the gateway.
If session.version provided by you does not match that stored against the session, the gateway will reject the operation with error.cause=INVALID_REQUEST.
See Making Business Decisions Based on Session Content.
shipping = OPTIONAL
shipping.address = OPTIONAL
shipping.address.city String = OPTIONAL
shipping.address.company String = OPTIONAL
shipping.address.country Upper case alphabetic text = OPTIONAL
shipping.address.postcodeZip Alphanumeric + additional characters = OPTIONAL
shipping.address.sameAsBilling Enumeration = OPTIONAL
The default value for this field is:
SAME - if the shipping and billing address are supplied, and all fields are the same (ignoring non-alphanumerics).
DIFFERENT - if the shipping and billing address are supplied, and at least one field is different (ignoring non-alphanumerics).
UNKNOWN - either shipping address or billing address is absent.
shipping.address.source Enumeration = OPTIONAL
shipping.address.stateProvince String = OPTIONAL
shipping.address.stateProvinceCode String = OPTIONAL
shipping.address.street String = OPTIONAL
shipping.address.street2 String = OPTIONAL
shipping.contact = OPTIONAL
shipping.contact.email Email = OPTIONAL
shipping.contact.firstName String = OPTIONAL
shipping.contact.lastName String = OPTIONAL
shipping.contact.mobilePhone Telephone Number = OPTIONAL
The number consists of:
- ‘+’
- country code (1, 2 or 3 digits)
- ‘space’
- national number ( which may embed single spaces characters for readability).
shipping.contact.phone Telephone Number = OPTIONAL
The number consists of:
- ‘+’
- country code (1, 2 or 3 digits)
- ‘space’
- national number ( which may embed single spaces characters for readability).
shipping.contact.sameAsBilling Enumeration = OPTIONAL
Default value is UNKNOWN
shipping.method Enumeration = OPTIONAL
origin.postcodeZip Alphanumeric + additional characters = OPTIONAL
sourceOfFunds = OPTIONAL
sourceOfFunds.provided = OPTIONAL
sourceOfFunds.provided.ach = OPTIONAL
sourceOfFunds.provided.ach.accountType Enumeration = OPTIONAL
- 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 = OPTIONAL
sourceOfFunds.provided.ach.bankAccountNumber Alphanumeric + additional characters = OPTIONAL
sourceOfFunds.provided.ach.routingNumber Digits = OPTIONAL
- 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 = OPTIONAL
sourceOfFunds.provided.alipay = OPTIONAL
sourceOfFunds.provided.alipay.payerCode String = OPTIONAL
sourceOfFunds.provided.bancontact = OPTIONAL
sourceOfFunds.provided.bancontact.bankAccountHolder String = OPTIONAL
sourceOfFunds.provided.blik = OPTIONAL
sourceOfFunds.provided.blik.bankAccountHolder String = OPTIONAL
sourceOfFunds.provided.boletoBancario = OPTIONAL
sourceOfFunds.provided.boletoBancario.actionType Enumeration = OPTIONAL
sourceOfFunds.provided.boletoBancario.bankAccountHolder String = OPTIONAL
sourceOfFunds.provided.boletoBancario.customerType Enumeration = OPTIONAL
sourceOfFunds.provided.boletoBancario.daysBeforeAction Digits = OPTIONAL
sourceOfFunds.provided.boletoBancario.dueDate Date = OPTIONAL
sourceOfFunds.provided.card = OPTIONAL
sourceOfFunds.provided.card.accountType Enumeration = OPTIONAL
sourceOfFunds.provided.card.devicePayment = OPTIONAL
- • 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 = OPTIONAL
- • Device payments: provide the cryptogram format when you decrypt the payment token and provide the payment details (including the online payment cryptogram) in the transaction request.
This field does not apply to Card Scheme token payments.
sourceOfFunds.provided.card.devicePayment.eciIndicator Digits = OPTIONAL
This field is not applicable for payments using digital wallets or card scheme tokens.
sourceOfFunds.provided.card.devicePayment.onlinePaymentCryptogram Base64 = OPTIONAL
- • Device payments: source this field directly from the decrypted payment token.
- • Card scheme tokens: source this field directly from the decrypted transaction credentials.
sourceOfFunds.provided.card.devicePayment.paymentToken String = OPTIONAL
For Apple Pay - this is the PKPaymentToken.paymentData value.
For Google - this is PaymentMethodToken.getToken().
Note 1: The gateway API considers this value to be a string, NOT JSON itself. Therefore when using the JSON gateway API, this field will typically look like:
"sourceOfFunds": {
"provided": {
"card": {
"devicePayment": {
"paymentToken": "{\"data\":\"869ss19ew ....
Note 2: The gateway will ignore the currency and amount information in the payment token, and will instead use the values passed on the amount and currency fields. For normal usage, you should populate those fields with the exact same values as you got from the SDK.
sourceOfFunds.provided.card.emvRequest String = OPTIONAL
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 = OPTIONAL
sourceOfFunds.provided.card.expiry.month Digits = OPTIONAL
sourceOfFunds.provided.card.expiry.year Digits = OPTIONAL
sourceOfFunds.provided.card.maskedFpan Masked digits = OPTIONAL
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 = OPTIONAL
sourceOfFunds.provided.card.maskedFpanExpiry.month Digits = OPTIONAL
sourceOfFunds.provided.card.maskedFpanExpiry.year Digits = OPTIONAL
sourceOfFunds.provided.card.mobileWallet = OPTIONAL
sourceOfFunds.provided.card.mobileWallet.3DSecure = OPTIONAL
sourceOfFunds.provided.card.mobileWallet.3DSecure.eciIndicator Digits = OPTIONAL
sourceOfFunds.provided.card.mobileWallet.3DSecure.onlinePaymentCryptogram Base64 = OPTIONAL
sourceOfFunds.provided.card.mobileWallet.cryptogramFormat Enumeration = OPTIONAL
sourceOfFunds.provided.card.nameOnCard String = OPTIONAL
sourceOfFunds.provided.card.number Digits = OPTIONAL
sourceOfFunds.provided.card.provided.card.p2pe = OPTIONAL
sourceOfFunds.provided.card.provided.card.p2pe.cardBin Digits = OPTIONAL
If you do not provided this, the gateway will not perform this check.
sourceOfFunds.provided.card.provided.card.p2pe.encryptionState String = OPTIONAL
sourceOfFunds.provided.card.provided.card.p2pe.initializationVector Hex = OPTIONAL
sourceOfFunds.provided.card.provided.card.p2pe.keySerialNumber Hex = OPTIONAL
sourceOfFunds.provided.card.provided.card.p2pe.payload Hex = OPTIONAL
sourceOfFunds.provided.card.provided.card.prefix Digits = OPTIONAL
sourceOfFunds.provided.card.securityCode Digits = OPTIONAL
sourceOfFunds.provided.card.sequenceNumber Digits = OPTIONAL
sourceOfFunds.provided.card.storedOnFile Enumeration = OPTIONAL
sourceOfFunds.provided.directDebitCanada = OPTIONAL
sourceOfFunds.provided.directDebitCanada.accountType Enumeration = OPTIONAL
sourceOfFunds.provided.directDebitCanada.bankAccountHolder String = OPTIONAL
sourceOfFunds.provided.directDebitCanada.bankAccountNumber Alphanumeric + additional characters = OPTIONAL
sourceOfFunds.provided.directDebitCanada.financialInstitutionNumber Digits = OPTIONAL
sourceOfFunds.provided.directDebitCanada.transitNumber Digits = OPTIONAL
sourceOfFunds.provided.ebt = OPTIONAL
sourceOfFunds.provided.ebt.accountType Enumeration = OPTIONAL
sourceOfFunds.provided.ebt.manualAuthorizationCode Digits = OPTIONAL
sourceOfFunds.provided.ebt.merchantFns Digits = OPTIONAL
sourceOfFunds.provided.ebt.voucherNumber Digits = OPTIONAL
sourceOfFunds.provided.enets = OPTIONAL
sourceOfFunds.provided.enets.bankAccountHolder String = OPTIONAL
sourceOfFunds.provided.epsUeberweisung = OPTIONAL
sourceOfFunds.provided.epsUeberweisung.bankAccountCountryCode Alpha = OPTIONAL
sourceOfFunds.provided.epsUeberweisung.bankAccountHolder String = OPTIONAL
sourceOfFunds.provided.giftCard = OPTIONAL
sourceOfFunds.provided.giftCard.expectedLocalBrand String = OPTIONAL
sourceOfFunds.provided.giftCard.number Digits = OPTIONAL
sourceOfFunds.provided.giftCard.pin Digits = OPTIONAL
sourceOfFunds.provided.giropay = OPTIONAL
sourceOfFunds.provided.giropay.bankIdentifier Digits = OPTIONAL
sourceOfFunds.provided.giropay.bic Alphanumeric = OPTIONAL
sourceOfFunds.provided.grabPay = OPTIONAL
sourceOfFunds.provided.grabPay.accountHolder String = OPTIONAL
sourceOfFunds.provided.ideal = OPTIONAL
sourceOfFunds.provided.ideal.bic Alphanumeric = OPTIONAL
sourceOfFunds.provided.klarnaPayLater = OPTIONAL
sourceOfFunds.provided.klarnaPayLater.bankAccountCountryCode Upper case alphabetic text = OPTIONAL
sourceOfFunds.provided.klarnaPayNow = OPTIONAL
sourceOfFunds.provided.klarnaPayNow.bankAccountCountryCode Alpha = OPTIONAL
sourceOfFunds.provided.openBankingBankTransfer = OPTIONAL
sourceOfFunds.provided.openBankingBankTransfer.aspspId String = OPTIONAL
sourceOfFunds.provided.oxxo = OPTIONAL
sourceOfFunds.provided.oxxo.bankAccountHolder String = OPTIONAL
sourceOfFunds.provided.oxxo.dueDate Date = OPTIONAL
sourceOfFunds.provided.payU = OPTIONAL
sourceOfFunds.provided.payU.bankAccountCountryCode Alpha = OPTIONAL
sourceOfFunds.provided.payU.bankAccountHolder String = OPTIONAL
sourceOfFunds.provided.payconiq = OPTIONAL
sourceOfFunds.provided.payconiq.countryCode Alpha = OPTIONAL
sourceOfFunds.provided.paypal = OPTIONAL
sourceOfFunds.provided.paypal.accountEmail Email = OPTIONAL
sourceOfFunds.provided.paypal.accountHolder String = OPTIONAL
sourceOfFunds.provided.paypal.billingAgreement = OPTIONAL
sourceOfFunds.provided.paypal.billingAgreement.cardinality Enumeration = OPTIONAL
sourceOfFunds.provided.paypal.billingAgreement.description String = OPTIONAL
sourceOfFunds.provided.paypal.billingAgreement.id String = OPTIONAL
sourceOfFunds.provided.paypal.billingAgreement.name String = OPTIONAL
sourceOfFunds.provided.paypal.payerId String = OPTIONAL
sourceOfFunds.provided.paysafecard = OPTIONAL
sourceOfFunds.provided.paysafecard.accountEmail Email = OPTIONAL
sourceOfFunds.provided.paysafecard.countryCode Alpha = OPTIONAL
sourceOfFunds.provided.pbba = OPTIONAL
sourceOfFunds.provided.pbba.returnUrl Url = OPTIONAL
sourceOfFunds.provided.poli = OPTIONAL
sourceOfFunds.provided.poli.bankAccountHolder String = OPTIONAL
sourceOfFunds.provided.przelewy24 = OPTIONAL
sourceOfFunds.provided.przelewy24.bankAccountHolder String = OPTIONAL
sourceOfFunds.provided.sepa = OPTIONAL
sourceOfFunds.provided.sepa.bankAccountHolder String = OPTIONAL
sourceOfFunds.provided.sepa.bic Alphanumeric = OPTIONAL
sourceOfFunds.provided.sepa.iban String = OPTIONAL
sourceOfFunds.provided.sofort = OPTIONAL
sourceOfFunds.provided.sofort.bankAccountCountryCode Upper case alphabetic text = OPTIONAL
sourceOfFunds.provided.trustly = OPTIONAL
sourceOfFunds.provided.trustly.bankAccountCountryCode Alpha = OPTIONAL
sourceOfFunds.provided.trustly.bankAccountHolder String = OPTIONAL
sourceOfFunds.provided.weChatPay = OPTIONAL
sourceOfFunds.provided.weChatPay.accountHolder String = OPTIONAL
sourceOfFunds.schemeTokenProvisioningIdentifier ASCII Text = OPTIONAL
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 = 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.tokenRequestorID Alphanumeric = OPTIONAL
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 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 = OPTIONAL
subMerchant.identifier Alphanumeric + additional characters = OPTIONAL
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] = OPTIONAL
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 = OPTIONAL
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 = OPTIONAL
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 = OPTIONAL
subgatewayMerchant.address.countryCode Upper case alphabetic text = OPTIONAL
subgatewayMerchant.address.postcodeZip String = OPTIONAL
subgatewayMerchant.address.stateProvince String = OPTIONAL
For Canadian merchants provide the 2-letter ISO 3166-2 province code.
subgatewayMerchant.address.street1 String = OPTIONAL
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 = OPTIONAL
subgatewayMerchant.id Alphanumeric + additional characters = OPTIONAL
subgatewayMerchant.name String = OPTIONAL
subgatewayMerchant.websiteUrl Url = OPTIONAL
token Alphanumeric = OPTIONAL
On response, the format of the token depends on the token generation strategy configured for your repository. See Tokenization for more details.
transaction = OPTIONAL
transaction.acquirer = OPTIONAL
transaction.acquirer.customData String = OPTIONAL
transaction.acquirer.traceId String = OPTIONAL
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 = OPTIONAL
transaction.amount Decimal = OPTIONAL
transaction.currency Upper case alphabetic text = OPTIONAL
transaction.deferredAuthorization Boolean = OPTIONAL
transaction.discountAmount Decimal = OPTIONAL
transaction.dutyAmount Decimal = OPTIONAL
transaction.id String = OPTIONAL
- 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] = OPTIONAL
transaction.item[n].brand String = OPTIONAL
transaction.item[n].category String = OPTIONAL
transaction.item[n].description String = OPTIONAL
transaction.item[n].detail = OPTIONAL
transaction.item[n].detail.acquirerCustom JSON Text = OPTIONAL
transaction.item[n].detail.commodityCode Digits = OPTIONAL
transaction.item[n].detail.tax[n] = OPTIONAL
transaction.item[n].detail.tax[n].amount Decimal = OPTIONAL
transaction.item[n].detail.tax[n].rate Decimal = OPTIONAL
transaction.item[n].detail.tax[n].type String = OPTIONAL
transaction.item[n].detail.unitDiscountRate Decimal = OPTIONAL
transaction.item[n].detail.unitTaxRate Decimal = OPTIONAL
transaction.item[n].detail.unitTaxType String = OPTIONAL
transaction.item[n].detail.unspsc Digits = OPTIONAL
transaction.item[n].detail.upc Digits = OPTIONAL
transaction.item[n].industryCategory Enumeration = OPTIONAL
(order.item.unitPrice + order.item.tax) * order.item.quantity
transaction.item[n].name String = OPTIONAL
transaction.item[n].quantity Decimal = OPTIONAL
transaction.item[n].sku String = OPTIONAL
transaction.item[n].unitDiscountAmount Decimal = OPTIONAL
transaction.item[n].unitOfMeasure String = OPTIONAL
transaction.item[n].unitPrice Decimal = OPTIONAL
transaction.item[n].unitTaxAmount Decimal = OPTIONAL
transaction.itemAmount Decimal = OPTIONAL
transaction.merchantNote String = OPTIONAL
transaction.payerConsentForStoringCardDetails Enumeration = OPTIONAL
transaction.priorApproval Enumeration = OPTIONAL
transaction.reference String = OPTIONAL
transaction.resubmission Boolean = OPTIONAL
transaction.shippingAndHandlingAmount Decimal = OPTIONAL
transaction.shippingAndHandlingTaxAmount Decimal = OPTIONAL
transaction.shippingAndHandlingTaxRate Decimal = OPTIONAL
transaction.source Enumeration = OPTIONAL
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 = OPTIONAL
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] = OPTIONAL
transaction.tax[n].amount Decimal = OPTIONAL
transaction.tax[n].rate Decimal = OPTIONAL
transaction.tax[n].type String = OPTIONAL
transaction.taxAmount Decimal = OPTIONAL
transaction.taxStatus Enumeration = OPTIONAL
transactionSource Enumeration = OPTIONAL
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 = OPTIONAL
- 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.
wallet.amexExpressCheckout = OPTIONAL
wallet.amexExpressCheckout.authCode String = OPTIONAL
wallet.amexExpressCheckout.selectedCardType String = OPTIONAL
wallet.amexExpressCheckout.transactionId String = OPTIONAL
wallet.amexExpressCheckout.walletId String = OPTIONAL
wallet.masterpass = OPTIONAL
wallet.masterpass.checkoutUrl Url = OPTIONAL
wallet.masterpass.oauthToken String = OPTIONAL
wallet.masterpass.oauthVerifier String = OPTIONAL
wallet.masterpass.originUrl Url = OPTIONAL
wallet.masterpass.secondaryOriginUrl Url = OPTIONAL
wallet.masterpassExpressCheckout = OPTIONAL
wallet.masterpassExpressCheckout.longAccessToken String = OPTIONAL
wallet.masterpassExpressCheckout.masterpassCardId String = OPTIONAL
wallet.masterpassExpressCheckout.masterpassShippingId String = OPTIONAL
wallet.masterpassExpressCheckout.originUrl Url = OPTIONAL
wallet.masterpassExpressCheckout.precheckoutTransactionId String = OPTIONAL
wallet.masterpassExpressCheckout.secondaryOriginUrl Url = OPTIONAL
wallet.visaCheckout = OPTIONAL
wallet.visaCheckout.callId 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
Response parameters are the same as Session: Retrieve Session