Update Session
Request to add or update request fields contained in the session.
URL | https://egenius.unicredit.ro/api/rest/version/57/merchant/{merchantId}/session/{sessionId} |
HTTP Method | PUT |
Authentication |
This operation requires authentication via one of the following methods:
|
Request Parameters
agreement = OPTIONAL
You must provide this data for some types of payments (such as recurring), but you can provide it for any cases where you want to link orders together.
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.
agreement.recurring = OPTIONAL
agreement.recurring.amountVariability Enumeration = OPTIONAL
agreement.recurring.daysBetweenPayments Integer = OPTIONAL
agreement.recurring.numberOfPayments Integer = 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 Alphanumeric = 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
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.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.challengePreference Enumeration = OPTIONAL
If you do not provide a value, the gateway will use NO_PREFERENCE. If there is no payer present (for example, recurring payments), then the gateway will ignore this field and use NO_CHALLENGE.
Note: 'challenge' means requiring the payer to take action to identify themselves, for example, entering a password.
authentication.goodsDescription String = OPTIONAL
authentication.psd2 = OPTIONAL
authentication.psd2.exemption Enumeration = OPTIONAL
- For recurring payments provide the RECURRING_PAYMENT value only if the amount is the same. If the amount varies, provide MERCHANT_INITIATED_TRANSACTION instead.
authentication.redirectResponseUrl Url = OPTIONAL
You must provide this URL, unless you are certain that there will be no interaction with the payer.
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.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.numberOfDeferrals 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
cruise = OPTIONAL
cruise.bookingReference String = OPTIONAL
cruise.company = OPTIONAL
cruise.company.address = OPTIONAL
cruise.company.address.city String = OPTIONAL
cruise.company.address.country Upper case alphabetic text = OPTIONAL
cruise.company.address.postCodeZip Alphanumeric + additional characters = OPTIONAL
cruise.company.address.stateProvince String = OPTIONAL
cruise.company.address.street String = OPTIONAL
cruise.company.address.street2 String = 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.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 provided on subsequent transactions or an order, DCC information 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.provider Enumeration = 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.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.time DateTime = 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.lastName String = OPTIONAL
customer.mobilePhone Telephone Number = OPTIONAL
The number consists of:
- ‘+’
- country code (1, 2 or 3 digits)
- ‘space’
- national number ( which may embed single spaces characters for readability).
customer.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.indicator Boolean = OPTIONAL
debtRepayment.paymentRecipient = OPTIONAL
debtRepayment.paymentRecipient.accountIdentifier String = OPTIONAL
debtRepayment.paymentRecipient.dateOfBirth Date = OPTIONAL
debtRepayment.paymentRecipient.lastName String = OPTIONAL
debtRepayment.paymentRecipient.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
device.mobilePhoneModel String = OPTIONAL
externalTokenProvider = OPTIONAL
externalTokenProvider.customData String = OPTIONAL
gatewayEntryPoint Enumeration = OPTIONAL
lineOfBusiness String = OPTIONAL
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 = 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
The value of this field in the response is zero if payer funds are not transferred.
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.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.invoiceNumber String = OPTIONAL
order.item[n] = OPTIONAL
order.item[n].brand String = OPTIONAL
order.item[n].category String = OPTIONAL
order.item[n].description String = OPTIONAL
order.item[n].detail = OPTIONAL
order.item[n].detail.acquirerCustom JSON Text = OPTIONAL
order.item[n].detail.commodityCode Digits = OPTIONAL
order.item[n].detail.tax[n] = OPTIONAL
order.item[n].detail.tax[n].amount Decimal = OPTIONAL
order.item[n].detail.tax[n].rate Decimal = OPTIONAL
order.item[n].detail.tax[n].type String = OPTIONAL
order.item[n].detail.unitDiscountRate Decimal = OPTIONAL
order.item[n].detail.unitTaxRate Decimal = OPTIONAL
order.item[n].detail.unitTaxType String = OPTIONAL
order.item[n].detail.unspsc Digits = OPTIONAL
order.item[n].detail.upc Digits = OPTIONAL
order.item[n].industryCategory Enumeration = OPTIONAL
(order.item.unitPrice + order.item.tax) * order.item.quantity
order.item[n].name String = OPTIONAL
order.item[n].quantity Decimal = OPTIONAL
order.item[n].sku String = OPTIONAL
order.item[n].unitDiscountAmount Decimal = OPTIONAL
order.item[n].unitOfMeasure String = OPTIONAL
order.item[n].unitPrice Decimal = OPTIONAL
order.item[n].unitTaxAmount Decimal = OPTIONAL
order.itemAmount Decimal = OPTIONAL
order.localTaxRegistrationId String = 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.netAmount Decimal = OPTIONAL
order.notificationUrl Url = OPTIONAL
order.owningEntity String = OPTIONAL
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.statementDescriptor = OPTIONAL
order.statementDescriptor.address = OPTIONAL
order.statementDescriptor.address.city String = OPTIONAL
order.statementDescriptor.address.company String = OPTIONAL
order.statementDescriptor.address.country Upper case alphabetic text = OPTIONAL
order.statementDescriptor.address.postcodeZip Alphanumeric + additional characters = OPTIONAL
order.statementDescriptor.address.stateProvince String = OPTIONAL
order.statementDescriptor.address.street String = OPTIONAL
order.statementDescriptor.address.street2 String = OPTIONAL
order.statementDescriptor.name String = OPTIONAL
order.statementDescriptor.phone String = OPTIONAL
order.subMerchant = OPTIONAL
The sub-merchant's details you provide may be displayed on the payer's cardholder statement.
Note that your acquirer may require you to register with the card scheme(s) before allowing you to submit sub-merchant details with a transaction.
This data must be on the initial transaction of an order, subsequent transactions with sub-merchant will be rejected.
Note: If you are requesting payer authentication using 3-D Secure Version 2 then you must provide values for order.subMerchant.address.country and order.subMerchant.bankIndustryCode.
order.subMerchant.address = OPTIONAL
order.subMerchant.address.city String = OPTIONAL
order.subMerchant.address.company String = OPTIONAL
order.subMerchant.address.country Upper case alphabetic text = OPTIONAL
order.subMerchant.address.postcodeZip Alphanumeric + additional characters = OPTIONAL
order.subMerchant.address.stateProvince String = OPTIONAL
order.subMerchant.address.stateProvinceCode String = OPTIONAL
order.subMerchant.address.street String = OPTIONAL
order.subMerchant.address.street2 String = OPTIONAL
order.subMerchant.authentication[n] = OPTIONAL
order.subMerchant.authentication[n].3DS2 = OPTIONAL
order.subMerchant.authentication[n].3DS2.requestorId String = OPTIONAL
order.subMerchant.authentication[n].3DS2.requestorName String = OPTIONAL
order.subMerchant.authentication[n].protocol Enumeration = OPTIONAL
order.subMerchant.bankIndustryCode Digits = OPTIONAL
order.subMerchant.email Email = OPTIONAL
order.subMerchant.identifier 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.surchargeAmount Decimal = OPTIONAL
If you provide a surcharge amount, you should include it in the total amount for the order.
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
This data may be used to qualify for better interchange rates on corporate purchase card transactions.
This amount is the sum of the tax amount for all the items contained in the order. If you supply both this value and any line item details, then this amount MUST equal the sum of the item.quantity times the item.unitTaxAmount for all the line items.
order.taxRegistrationId String = OPTIONAL
order.taxStatus 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.numberOfDeferrals Digits = OPTIONAL
paymentPlan.numberOfPayments Digits = OPTIONAL
paymentPlan.planId String = OPTIONAL
paymentType Enumeration = OPTIONAL
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.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.3DSecure = OPTIONAL
- • Device payments: if you decrypt the payment token yourself. In this case, you source these fields directly from the decrypted payment token.
You do not need to use this parameter group if you provide the payment token in sourceOfFunds.provided.card.devicePayment.paymentToken. - • Card scheme tokens: if you decrypt the transaction credentials yourself.
sourceOfFunds.provided.card.devicePayment.3DSecure.eciIndicator Digits = OPTIONAL
This field is not applicable for payments using digital wallets or card scheme tokens.
sourceOfFunds.provided.card.devicePayment.3DSecure.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.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.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
If you use Scheme Tokenization services like MDES and store the tokens provided, you have to provide the value STORED and if you pass the token value with out storing them, provide the value NOT_STORED.
If you store yourself, you have to provide the TO_BE_STORED or STORED values for all payments.
sourceOfFunds.provided.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.giftCard = OPTIONAL
sourceOfFunds.provided.giftCard.expectedLocalBrand String = OPTIONAL
sourceOfFunds.provided.giftCard.number Digits = OPTIONAL
sourceOfFunds.provided.giftCard.pin Digits = OPTIONAL
sourceOfFunds.provided.ideal = OPTIONAL
sourceOfFunds.provided.ideal.bic Alphanumeric = 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.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.pbba = OPTIONAL
sourceOfFunds.provided.pbba.returnUrl Url = OPTIONAL
sourceOfFunds.provided.poli = OPTIONAL
sourceOfFunds.provided.poli.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.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
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.
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.amexSafeKey = OPTIONAL
subgatewayMerchant.acquirer[n].3DS1.amexSafeKey.merchantId String = 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].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.state String = OPTIONAL
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
transaction.acquirer.transactionId String = OPTIONAL
transaction.amount Decimal = OPTIONAL
transaction.bancanet = OPTIONAL
transaction.bancanet.merchantPaymentReference String = OPTIONAL
transaction.bancanet.paymentDueDate Date = OPTIONAL
transaction.bancanet.paymentReason String = OPTIONAL
transaction.currency Upper case alphabetic text = OPTIONAL
transaction.discountAmount 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.priorApproval Enumeration = OPTIONAL
transaction.reference String = OPTIONAL
transaction.shippingAndHandlingAmount 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
If you do not provide a target transaction ID the gateway will try to identify a transaction. If no transaction can be found or more than one transaction is identified, the request is rejected.
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
transaction.transit = OPTIONAL
transaction.transit.aggregationStartDate Date = OPTIONAL
transaction.transit.fareCollection Enumeration = OPTIONAL
Use the field to indicate the purpose of this transaction.
transaction.transit.transportationMode 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.
userId String = OPTIONAL
verificationStrategy Enumeration = OPTIONAL
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
{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
Response parameters are the same as Session: Retrieve Session