Retrieve Order
Request to retrieve the details of an order and all transactions associated with this order.
URL | https://evopaymentsmexico.gateway.mastercard.com/api/nvp/version/58 |
HTTP Method | POST |
Authentication |
This operation requires authentication via one of the following methods:
|
Request Parameters
apiOperation String =RETRIEVE_ORDER FIXED
merchant Alphanumeric + additional characters = COMPULSORY
order.id String = COMPULSORY
apiOperation String =RETRIEVE_ORDER FIXED
correlationId String = OPTIONAL
merchant Alphanumeric + additional characters = COMPULSORY
order.id String = COMPULSORY
responseControls = OPTIONAL
responseControls.sensitiveData String = OPTIONAL
Response Parameters
amount Decimal = Always Provided
The value of this field in the response is zero if payer funds are not transferred.
creationTime DateTime = Always Provided
currency Upper case alphabetic text = Always Provided
id String = Always Provided
lastUpdatedTime DateTime = Always Provided
merchant Alphanumeric + additional characters = Always Provided
merchantAmount Decimal = Always Provided
merchantCurrency Upper case alphabetic text = Always Provided
If there is FX on this order, this is based on the rate quote you provided on the payment transactions, if not then this is the order.currency.
result Enumeration = Always Provided
totalAuthorizedAmount Decimal = Always Provided
totalCapturedAmount Decimal = Always Provided
totalRefundedAmount Decimal = Always Provided
acceptPartialAmount Boolean = CONDITIONAL
Unless you have been advised by your payment service provider that the gateway supports partial approvals for your acquirer, you can ignore this field.
If the gateway supports partial approvals for your acquirer you must set this field to TRUE else the transaction is rejected by the gateway.
agreement = CONDITIONAL
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 = CONDITIONAL
agreement.id String = CONDITIONAL
- Recurring payments: you have an agreement with the payer that authorizes you to automatically debit their account at agreed intervals for fixed or variable amounts. For example, gym membership, phone bills, or magazine subscriptions.
- Installment payments: you have an agreement with the payer that authorizes you to process multiple payments over an agreed period of time for a single purchase. For example, the payer purchases an item for $1000 and pays for it in four monthly installments.
- Unscheduled: you have an agreement with the payer that authorizes you to process future payments when required. For example, the payer authorizes you to process an account top-up transaction for a transit card when the account balance drops below a certain threshold.
agreement.recurring = CONDITIONAL
agreement.recurring.amountVariability Enumeration = CONDITIONAL
agreement.recurring.daysBetweenPayments Integer = CONDITIONAL
agreement.recurring.numberOfPayments Integer = CONDITIONAL
agreement.type Enumeration = CONDITIONAL
The gateway will use the value you specify for subsequent payments in the series.
airline = CONDITIONAL
airline.bookingReference Alphanumeric = CONDITIONAL
airline.documentType Enumeration = CONDITIONAL
airline.itinerary = CONDITIONAL
airline.itinerary.leg[n] = CONDITIONAL
airline.itinerary.leg[n].carrierCode Regex = CONDITIONAL
airline.itinerary.leg[n].conjunctionTicketNumber Alphanumeric = CONDITIONAL
airline.itinerary.leg[n].couponNumber Alphanumeric = CONDITIONAL
airline.itinerary.leg[n].departureAirport Upper case alphabetic text = CONDITIONAL
airline.itinerary.leg[n].departureDate Date = CONDITIONAL
airline.itinerary.leg[n].departureTax Decimal = CONDITIONAL
airline.itinerary.leg[n].departureTime Time = CONDITIONAL
airline.itinerary.leg[n].destinationAirport Upper case alphabetic text = CONDITIONAL
airline.itinerary.leg[n].destinationArrivalDate Date = CONDITIONAL
airline.itinerary.leg[n].destinationArrivalTime Time = CONDITIONAL
airline.itinerary.leg[n].endorsementsRestrictions Alphanumeric = CONDITIONAL
airline.itinerary.leg[n].exchangeTicketNumber Alphanumeric = CONDITIONAL
airline.itinerary.leg[n].fare Decimal = CONDITIONAL
airline.itinerary.leg[n].fareBasis Alphanumeric = CONDITIONAL
airline.itinerary.leg[n].fees Decimal = CONDITIONAL
airline.itinerary.leg[n].flightNumber Alphanumeric = CONDITIONAL
airline.itinerary.leg[n].stopoverPermitted Boolean = CONDITIONAL
airline.itinerary.leg[n].taxes Decimal = CONDITIONAL
airline.itinerary.leg[n].travelClass Alphanumeric = CONDITIONAL
airline.itinerary.numberInParty Digits = CONDITIONAL
airline.itinerary.originCountry Upper case alphabetic text = CONDITIONAL
airline.passenger[n] = CONDITIONAL
airline.passenger[n].firstName String = CONDITIONAL
airline.passenger[n].frequentFlyerNumber String = CONDITIONAL
airline.passenger[n].lastName String = CONDITIONAL
airline.passenger[n].middleName String = CONDITIONAL
airline.passenger[n].specificInformation Alphanumeric = CONDITIONAL
airline.passenger[n].title String = CONDITIONAL
airline.planNumber Alphanumeric = CONDITIONAL
airline.ticket = CONDITIONAL
airline.ticket.conjunctionTicketIndicator Boolean = CONDITIONAL
airline.ticket.eTicket Boolean = CONDITIONAL
airline.ticket.exchangedTicketNumber Alphanumeric = CONDITIONAL
airline.ticket.issue = CONDITIONAL
airline.ticket.issue.address String = CONDITIONAL
airline.ticket.issue.carrierCode Regex = CONDITIONAL
airline.ticket.issue.carrierName Alphanumeric = CONDITIONAL
airline.ticket.issue.city Alphanumeric = CONDITIONAL
airline.ticket.issue.country Upper case alphabetic text = CONDITIONAL
airline.ticket.issue.date Date = CONDITIONAL
airline.ticket.issue.travelAgentCode Alphanumeric = CONDITIONAL
airline.ticket.issue.travelAgentName Alphanumeric = CONDITIONAL
airline.ticket.restricted Boolean = CONDITIONAL
airline.ticket.taxOrFee[n] = CONDITIONAL
airline.ticket.taxOrFee[n].amount Decimal = CONDITIONAL
airline.ticket.taxOrFee[n].type Alphanumeric = CONDITIONAL
airline.ticket.ticketNumber Alphanumeric = CONDITIONAL
airline.ticket.totalFare Decimal = CONDITIONAL
airline.ticket.totalFees Decimal = CONDITIONAL
airline.ticket.totalTaxes Decimal = CONDITIONAL
airline.transactionType Enumeration = CONDITIONAL
amount Decimal = Always Provided
The value of this field in the response is zero if payer funds are not transferred.
authentication = CONDITIONAL
This parameter group include payer authentication options available to you, parameters you need to perform payer authentication for an available method, and the results of payer authentication.
authentication.3ds = CONDITIONAL
Depending on the 3-D Secure authentication version applicable you will also need additional parameters:
- 3-D Secure authentication version 1: see the authentication.3ds1 parameter group.
- 3-D Secure authentication version 2: see the authentication.3ds2 parameter group.
authentication.3ds.acsEci Alphanumeric = CONDITIONAL
authentication.3ds.authenticationToken Base64 = CONDITIONAL
For 3DS version 2, this field corresponds to the Authentication Value.
authentication.3ds.transactionId String = CONDITIONAL
For 3DS version 2, this field corresponds to the identifier assigned by the scheme directory server.
This identifier should be used in subsequent operation requests unaltered.
An XID submitted in this field must be in base64 format.
authentication.3ds1 = CONDITIONAL
authentication.3ds1.paResStatus Alpha = CONDITIONAL
authentication.3ds1.veResEnrolled Alpha = Always Provided
This is the value returned in the 'enrolled' field of the Verify Enrollment Response (VERes) message from the card scheme's Directory Server. For example, Y, N, or U. Refer to the relevant documentation for Mastercard SecureCode™, Verified by Visa™, JCB J/Secure™, American Express SafeKey™, or Diners Club ProtectBuy™.
authenticationStatus Enumeration = CONDITIONAL
authenticationVersion Enumeration = CONDITIONAL
This parameter group include payer authentication options available to you, parameters you need to perform payer authentication for an available method, and the results of payer authentication.
billing = CONDITIONAL
billing.address = CONDITIONAL
billing.address.city String = CONDITIONAL
billing.address.company String = CONDITIONAL
billing.address.country Upper case alphabetic text = CONDITIONAL
billing.address.postcodeZip Alphanumeric + additional characters = CONDITIONAL
billing.address.stateProvince String = CONDITIONAL
billing.address.stateProvinceCode String = CONDITIONAL
billing.address.street String = CONDITIONAL
billing.address.street2 String = CONDITIONAL
cashAdvance Boolean = CONDITIONAL
cashbackAmount Decimal = CONDITIONAL
certainty Enumeration = CONDITIONAL
chargeback = CONDITIONAL
chargeback.amount Decimal = Always Provided
chargeback.currency String = Always Provided
correlationId String = CONDITIONAL
creationTime DateTime = Always Provided
currency Upper case alphabetic text = Always Provided
currencyConversion = CONDITIONAL
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 = CONDITIONAL
currencyConversion.marginPercentage Decimal = CONDITIONAL
currencyConversion.payerAmount Decimal = CONDITIONAL
currencyConversion.payerCurrency Upper case alphabetic text = CONDITIONAL
currencyConversion.payerExchangeRate Decimal = CONDITIONAL
currencyConversion.payerReceiptText String = CONDITIONAL
currencyConversion.provider Enumeration = CONDITIONAL
currencyConversion.providerReceipt String = CONDITIONAL
currencyConversion.uptake Enumeration = Always Provided
custom String = CONDITIONAL
customer = CONDITIONAL
customer.account.id String = CONDITIONAL
customer.email Email = CONDITIONAL
customer.firstName String = CONDITIONAL
customer.lastName String = CONDITIONAL
customer.mobilePhone String = CONDITIONAL
customer.phone String = CONDITIONAL
customer.taxRegistrationId String = CONDITIONAL
customerNote String = CONDITIONAL
customerOrderDate Date = CONDITIONAL
customerReference ASCII Text = CONDITIONAL
debtRepayment = CONDITIONAL
debtRepayment.paymentRecipient = CONDITIONAL
debtRepayment.paymentRecipient.accountIdentifier String = Always Provided
debtRepayment.paymentRecipient.dateOfBirth Date = Always Provided
debtRepayment.paymentRecipient.lastName String = Always Provided
debtRepayment.paymentRecipient.postcodeZip String = Always Provided
description String = CONDITIONAL
device = CONDITIONAL
device.ani String = CONDITIONAL
device.aniCallType String = CONDITIONAL
device.browser String = CONDITIONAL
device.hostname String = CONDITIONAL
device.ipAddress String = CONDITIONAL
device.mobilePhoneModel String = CONDITIONAL
discount = CONDITIONAL
discount.amount Decimal = CONDITIONAL
discount.code String = CONDITIONAL
discount.description String = CONDITIONAL
expectedNumberOfCaptures Integer = CONDITIONAL
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.
funding = CONDITIONAL
funding.amount Decimal = Always Provided
See order.fundingStatus to determine the certainty of this value.
funding.currency Upper case alphabetic text = Always Provided
fundingStatus Enumeration = CONDITIONAL
When considering funding status, the gateway only examines transactions that can move funds. For example, it ignores Authorizations and declined Captures. This is because fundingStatus reflects the movement of the money for the commercial transaction, it does not reflect the movement of money for fees associated with the transaction.
gratuityAmount Decimal = CONDITIONAL
id String = Always Provided
invoiceNumber String = CONDITIONAL
item[n] = CONDITIONAL
item[n].brand String = CONDITIONAL
item[n].category String = CONDITIONAL
item[n].description String = CONDITIONAL
item[n].detail = CONDITIONAL
item[n].detail.acquirerCustom JSON Text = CONDITIONAL
item[n].detail.commodityCode Integer = CONDITIONAL
item[n].detail.tax[n] = CONDITIONAL
item[n].detail.tax[n].amount Decimal = CONDITIONAL
item[n].detail.tax[n].rate Decimal = CONDITIONAL
item[n].detail.tax[n].type String = CONDITIONAL
item[n].detail.unitDiscountRate Decimal = CONDITIONAL
item[n].detail.unitTaxRate Decimal = CONDITIONAL
item[n].detail.unitTaxType String = CONDITIONAL
item[n].detail.unspsc Integer = CONDITIONAL
item[n].detail.upc Integer = CONDITIONAL
item[n].industryCategory Enumeration = CONDITIONAL
(order.item.unitPrice + order.item.tax) * order.item.quantity
item[n].name String = Always Provided
item[n].quantity Decimal = Always Provided
item[n].sku String = CONDITIONAL
item[n].unitDiscountAmount Decimal = CONDITIONAL
item[n].unitOfMeasure String = CONDITIONAL
item[n].unitPrice Decimal = Always Provided
item[n].unitTaxAmount Decimal = CONDITIONAL
itemAmount Decimal = CONDITIONAL
lastUpdatedTime DateTime = Always Provided
lineOfBusiness String = CONDITIONAL
For example, lineOfBusiness = TICKET_SALES can have a different bank account from lineOfBusiness = MERCHANDISING. One line of business on your profile might be "null". To use that, do not provide the lineOfBusiness field.
localTaxRegistrationId String = CONDITIONAL
merchant Alphanumeric + additional characters = Always Provided
merchantAmount Decimal = Always Provided
merchantCategoryCode Digits = CONDITIONAL
merchantCurrency Upper case alphabetic text = Always Provided
If there is FX on this order, this is based on the rate quote you provided on the payment transactions, if not then this is the order.currency.
netAmount Decimal = CONDITIONAL
notificationUrl Url = CONDITIONAL
paymentPlan = CONDITIONAL
paymentPlan.finalAmount Decimal = Always Provided
paymentPlan.interestRate Decimal = Always Provided
paymentPlan.numberOfDeferrals Integer = Always Provided
paymentPlan.numberOfPayments Integer = Always Provided
paymentPlan.paymentAmount Decimal = Always Provided
paymentPlan.planId String = Always Provided
purchaseType Enumeration = CONDITIONAL
6051 (Quasi Cash – Merchant or Non-Financial Institutions – Foreign Currency, Non-Fiat Currency) and this transaction is for the purchase of cryptocurrency. Set the value to CRYPTOCURRENCY.
6211 (Securities – Brokers/Dealers) and this transaction is for the purchase of high-risk securities. Set the value to HIGH_RISK_SECURITIES.
6012 (Merchandise and Services—Customer Financial Institutions) or 6051 (Non-Financial Institutions – Foreign Currency, Non-Fiat Currency) and this transaction is for debt repayment. Set the value to DEBT_REPAYMENT.
You may set purchase type to OTHER for any other type of payment.
reference String = CONDITIONAL
requestedAmount Decimal = CONDITIONAL
requestorName String = CONDITIONAL
result Enumeration = Always Provided
reward = CONDITIONAL
reward.amount Decimal = CONDITIONAL
reward.availableBalance = CONDITIONAL
reward.availableBalance.amount Decimal = CONDITIONAL
reward.availableBalance.points Decimal = CONDITIONAL
reward.points Decimal = Always Provided
reward.previousBalance = CONDITIONAL
reward.previousBalance.amount Decimal = CONDITIONAL
reward.previousBalance.points Decimal = CONDITIONAL
reward.program Enumeration = CONDITIONAL
risk = CONDITIONAL
risk.custom String = CONDITIONAL
Field: risk.custom.headOfficeLocation
Value: London UK
risk.response = CONDITIONAL
risk.response.gatewayCode Enumeration = CONDITIONAL
risk.response.reversalResult Enumeration = CONDITIONAL
risk.response.review = CONDITIONAL
risk.response.review.decision Enumeration = CONDITIONAL
risk.response.review.decisionReason String = CONDITIONAL
risk.response.review.note String = CONDITIONAL
risk.response.review.timeOfDecision DateTime = CONDITIONAL
risk.response.review.userId String = CONDITIONAL
risk.response.rule[n] = CONDITIONAL
risk.response.rule[n].data String = CONDITIONAL
risk.response.rule[n].id String = CONDITIONAL
risk.response.rule[n].name String = CONDITIONAL
risk.response.rule[n].recommendation Enumeration = CONDITIONAL
risk.response.rule[n].score Integer = CONDITIONAL
risk.response.rule[n].type Enumeration = CONDITIONAL
risk.response.totalScore Integer = CONDITIONAL
shipping = CONDITIONAL
shipping.address = CONDITIONAL
shipping.address.city String = CONDITIONAL
shipping.address.company String = CONDITIONAL
shipping.address.country Upper case alphabetic text = CONDITIONAL
shipping.address.postcodeZip Alphanumeric + additional characters = CONDITIONAL
shipping.address.source Enumeration = CONDITIONAL
shipping.address.stateProvince String = CONDITIONAL
shipping.address.stateProvinceCode String = CONDITIONAL
shipping.address.street String = CONDITIONAL
shipping.address.street2 String = CONDITIONAL
shipping.address.sameAsBilling Enumeration = CONDITIONAL
The default value for this field is:
SAME - if the shipping and billing address are supplied, and all fields are the same (ignoring non-alphanumerics).
DIFFERENT - if the shipping and billing address are supplied, and at least one field is different (ignoring non-alphanumerics).
UNKNOWN - either shipping address or billing address is absent.
shipping.contact = CONDITIONAL
shipping.contact.email Email = CONDITIONAL
shipping.contact.firstName String = CONDITIONAL
shipping.contact.lastName String = CONDITIONAL
shipping.contact.mobilePhone Telephone Number = CONDITIONAL
The number consists of:
- ‘+’
- country code (1, 2 or 3 digits)
- ‘space’
- national number ( which may embed single spaces characters for readability).
shipping.contact.phone Telephone Number = CONDITIONAL
The number consists of:
- ‘+’
- country code (1, 2 or 3 digits)
- ‘space’
- national number ( which may embed single spaces characters for readability).
shipping.method Enumeration = CONDITIONAL
shipping.origin.postcodeZip Alphanumeric + additional characters = CONDITIONAL
shippingAndHandlingAmount Decimal = CONDITIONAL
sourceOfFunds = CONDITIONAL
sourceOfFunds.provided = CONDITIONAL
sourceOfFunds.provided.ach = CONDITIONAL
sourceOfFunds.provided.ach.accountType Enumeration = CONDITIONAL
- Consumer (checking or savings), or
- Business
For pre-arranged payments (sourceOfFunds.provided.ach.secCode=PPD) retrieve this information from the payer.
If payments were telephone-initiated (sourceOfFunds.provided.ach.secCode=TEL) or internet-initiated (sourceOfFunds.provided.ach.secCode=WEB) you may choose to limit the payer's options (e.g. only support consumer checking accounts), depending on your type of business (e.g. B2C online webshop).
sourceOfFunds.provided.ach.bankAccountHolder String = CONDITIONAL
sourceOfFunds.provided.ach.bankAccountNumber Alphanumeric + additional characters = CONDITIONAL
sourceOfFunds.provided.ach.routingNumber Digits = CONDITIONAL
- Routing number,
- Transit number, or
- ABA number
Retrieve this information from the payer.
See also http://en.wikipedia.org/wiki/Routing_transit_number.
sourceOfFunds.provided.ach.secCode Enumeration = CONDITIONAL
sourceOfFunds.provided.boletoBancario = CONDITIONAL
sourceOfFunds.provided.boletoBancario.actionType Enumeration = CONDITIONAL
sourceOfFunds.provided.boletoBancario.bankAccountHolder String = Always Provided
sourceOfFunds.provided.boletoBancario.customerType Enumeration = CONDITIONAL
sourceOfFunds.provided.boletoBancario.daysBeforeAction Digits = CONDITIONAL
sourceOfFunds.provided.boletoBancario.dueDate Date = CONDITIONAL
sourceOfFunds.provided.boletoBancario.slipUrl Url = CONDITIONAL
sourceOfFunds.provided.card = CONDITIONAL
Cards: the card details entered directly or collected using a Point of Sale (POS) terminal.
Device payment methods such as Apple Pay, Android Pay, Samsung Pay or Google Pay.
Digital wallets such as Masterpass, Visa Checkout or Amex Express Checkout.
Card scheme tokens where the card was tokenized using a card scheme tokenization service such as Mastercard Digital Enablement Service (MDES).
sourceOfFunds.provided.card.accountType Enumeration = CONDITIONAL
sourceOfFunds.provided.card.brand Enumeration = Always Provided
You may use this information to support surcharging decisions. This information is gathered from 3rd party sources and may not be accurate in all circumstances.
sourceOfFunds.provided.card.devicePayment = CONDITIONAL
sourceOfFunds.provided.card.devicePayment.cryptogramFormat Enumeration = CONDITIONAL
You do not need to provide the cryptogram format if you provide the payment token in sourceOfFunds.provided.card.devicePayment.paymentToken
sourceOfFunds.provided.card.deviceSpecificExpiry = CONDITIONAL
- • Device payments: the expiry date for the Device Primary Account Number (DPAN).
- • Digital wallets: the expiry date for the Token PAN.
- • Card scheme tokens: the expiry date for the Token PAN.
sourceOfFunds.provided.card.deviceSpecificExpiry.month Digits = Always Provided
sourceOfFunds.provided.card.deviceSpecificExpiry.year Digits = Always Provided
sourceOfFunds.provided.card.deviceSpecificNumber Masked digits = Always Provided
- • Device payments: the payers's account number associated with the mobile device used for the payment. This is also known as the Device Primary Account Number (DPAN).
- • Digital wallets: the Token PAN returned by a digital wallet. The gateway only returns this value for Amex Express Checkout.
- • Card scheme tokens: the token generated by a card scheme tokenization service such as Mastercard Digital Enablement Service (MDES). The token is used as an identifier of the payer's Primary Account Number (PAN) securely stored by the service. For MDES, this token is referred to as the Token PAN. For VTS, this is the Token
sourceOfFunds.provided.card.emvRequest String = CONDITIONAL
For the list of field tags to include (if provided by the terminal), see Card Present Payments. Requests with any other tags are rejected by the gateway.
Some of the tags represent data that can occur on explicit fields in this API. You can submit the value either in this field, or in both places. For example, the PAN can be presented as EMV tag 5A in this field, or included both the sourceOfFunds.provided.card.number API field and in EMV tag 5A in this field.
If you specify the EMV tag only, we can populate the explicit field in the API. Fields where this is supported have the text "This field corresponds to EMV tag <tag name>" in their field descriptions.
If you specify both places, there will be no population of the explicit field or validation that the data matches.
The API response will not contain PCI sensitive fields.
sourceOfFunds.provided.card.emvResponse String = CONDITIONAL
The card/terminal uses data returned from the issuer to make the final decision to accept or decline the transaction.
sourceOfFunds.provided.card.encryption Enumeration = CONDITIONAL
sourceOfFunds.provided.card.expiry = CONDITIONAL
sourceOfFunds.provided.card.expiry.month Digits = Always Provided
sourceOfFunds.provided.card.expiry.year Digits = Always Provided
sourceOfFunds.provided.card.fundingMethod Enumeration = Always Provided
sourceOfFunds.provided.card.issuer String = CONDITIONAL
sourceOfFunds.provided.card.localBrand String = CONDITIONAL
You may use this information to support surcharging decisions. This information is gathered from 3rd party sources and may not be accurate in all circumstances.
sourceOfFunds.provided.card.nameOnCard String = CONDITIONAL
sourceOfFunds.provided.card.number Masked digits = Always Provided
- Request
On request, populate this field based on the payment method you are using for the payment:- • Card: the account number embossed onto the card. This field corresponds to EMV tag 5A.
- • Device payment methods such as Apple Pay, Android Pay, Samsung Pay, or Google Pay. Normally for device payments, you would populate sourceOfFunds.provided.card.devicePayment.paymentToken and the gateway will decrypt and extract this field. However, you can populate this field if you decrypt the payment token yourself. In this case use the Device PAN (DPAN) provided in the payment token.
- • Digital wallets such as Masterpass, Visa Checkout or Amex Express Checkout. In this case, provide the PAN retrieved from the wallet.
- • Scheme tokens such as MDES (Mastercard Digital Enablement Service) or Visa Token Service (VTS). For MDES tokens, supply the value called the "Token PAN". For VTS tokens, supply the value called "Token"
- Response
On return, the card number will be populated in 6.4 masking format, for example, 000000xxxxxx0000. If you wish to return unmasked card numbers, you must have the requisite permission, set responseControls.sensitiveData field to UNMASK, and authenticate your call to the API using certificate authentication.
When a DPAN or scheme token was provided in the transaction request, then this field will represent the PAN of the associated payer's account (when supported by the acquirer). This is also referred to as the Funding PAN (FPAN).
sourceOfFunds.provided.card.paymentAccountReference String = CONDITIONAL
sourceOfFunds.provided.card.pin = CONDITIONAL
sourceOfFunds.provided.card.pin.encryptionState Enumeration = CONDITIONAL
sourceOfFunds.provided.card.pin.keySerialNumber Hex = Always Provided
sourceOfFunds.provided.card.scheme Enumeration = Always Provided
sourceOfFunds.provided.card.sequenceNumber Digits = CONDITIONAL
sourceOfFunds.provided.card.storedOnFile Enumeration = CONDITIONAL
If you use Scheme Tokenization services like MDES and store the tokens provided, you have to provide the value STORED and if you pass the token value with out storing them, provide the value NOT_STORED.
If you store yourself, you have to provide the TO_BE_STORED or STORED values for all payments.
sourceOfFunds.provided.card.trackDataProvided Boolean = CONDITIONAL
sourceOfFunds.provided.ebt = CONDITIONAL
sourceOfFunds.provided.ebt.accountType Enumeration = CONDITIONAL
sourceOfFunds.provided.ebt.manualAuthorizationCode Digits = CONDITIONAL
sourceOfFunds.provided.ebt.merchantFns Digits = CONDITIONAL
sourceOfFunds.provided.ebt.voucherNumber Digits = CONDITIONAL
sourceOfFunds.provided.enets = CONDITIONAL
sourceOfFunds.provided.enets.bankAccountHolder String = Always Provided
sourceOfFunds.provided.giftCard = CONDITIONAL
sourceOfFunds.provided.giftCard.brand Enumeration = Always Provided
sourceOfFunds.provided.giftCard.localBrand String = Always Provided
sourceOfFunds.provided.giftCard.number Masked digits = Always Provided
sourceOfFunds.provided.giftCard.pin Masked digits = CONDITIONAL
sourceOfFunds.provided.giftCard.scheme Enumeration = Always Provided
sourceOfFunds.provided.giropay = CONDITIONAL
sourceOfFunds.provided.giropay.bankIdentifier Digits = CONDITIONAL
sourceOfFunds.provided.giropay.bic Alphanumeric = CONDITIONAL
sourceOfFunds.provided.giropay.iban String = CONDITIONAL
sourceOfFunds.provided.ideal = CONDITIONAL
sourceOfFunds.provided.ideal.bankAccountHolder String = CONDITIONAL
sourceOfFunds.provided.ideal.bic Alphanumeric = CONDITIONAL
sourceOfFunds.provided.ideal.iban String = CONDITIONAL
sourceOfFunds.provided.openBankingBankTransfer = CONDITIONAL
sourceOfFunds.provided.openBankingBankTransfer.aspspId String = Always Provided
sourceOfFunds.provided.oxxo = CONDITIONAL
sourceOfFunds.provided.oxxo.bankAccountHolder String = Always Provided
sourceOfFunds.provided.oxxo.dueDate Date = CONDITIONAL
sourceOfFunds.provided.paypal = CONDITIONAL
sourceOfFunds.provided.paypal.accountEmail Email = CONDITIONAL
sourceOfFunds.provided.paypal.accountHolder String = CONDITIONAL
sourceOfFunds.provided.paypal.billingAgreement = CONDITIONAL
sourceOfFunds.provided.paypal.billingAgreement.cardinality Enumeration = CONDITIONAL
sourceOfFunds.provided.paypal.billingAgreement.description String = CONDITIONAL
sourceOfFunds.provided.paypal.billingAgreement.id String = CONDITIONAL
sourceOfFunds.provided.paypal.billingAgreement.name String = CONDITIONAL
sourceOfFunds.provided.paypal.payerId String = CONDITIONAL
sourceOfFunds.provided.pbba = CONDITIONAL
sourceOfFunds.provided.pbba.paymentRequestId Digits = CONDITIONAL
sourceOfFunds.provided.pbba.paymentRequestInputCode Upper case alphabetic text = CONDITIONAL
sourceOfFunds.provided.poli = CONDITIONAL
sourceOfFunds.provided.poli.bankAccountHolder String = Always Provided
sourceOfFunds.provided.sepa = CONDITIONAL
sourceOfFunds.provided.sepa.bankAccountHolder String = Always Provided
sourceOfFunds.provided.sepa.bic Alphanumeric = CONDITIONAL
sourceOfFunds.provided.sepa.iban String = Always Provided
sourceOfFunds.provided.sofort = CONDITIONAL
sourceOfFunds.provided.sofort.bankAccountHolder String = CONDITIONAL
sourceOfFunds.provided.sofort.bankAccountNumber String = CONDITIONAL
sourceOfFunds.provided.sofort.bankIdentifier String = CONDITIONAL
sourceOfFunds.provided.sofort.bic String = CONDITIONAL
sourceOfFunds.provided.sofort.country Upper case alphabetic text = CONDITIONAL
sourceOfFunds.provided.sofort.iban String = CONDITIONAL
sourceOfFunds.provided.weChatPay = CONDITIONAL
sourceOfFunds.provided.weChatPay.accountHolder String = Always Provided
sourceOfFunds.token Alphanumeric = CONDITIONAL
sourceOfFunds.tokenRequestorID Alphanumeric = CONDITIONAL
sourceOfFunds.type Enumeration = CONDITIONAL
If you are making a payment with a gateway token, then you can leave this field unset, and only populate the 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.
status Enumeration = CONDITIONAL
subMerchant = CONDITIONAL
subMerchant.address = CONDITIONAL
subMerchant.address.city String = CONDITIONAL
subMerchant.address.company String = CONDITIONAL
subMerchant.address.country Upper case alphabetic text = CONDITIONAL
subMerchant.address.postcodeZip Alphanumeric + additional characters = CONDITIONAL
subMerchant.address.stateProvince String = CONDITIONAL
subMerchant.address.street String = CONDITIONAL
subMerchant.address.street2 String = CONDITIONAL
subMerchant.bankIndustryCode Digits = CONDITIONAL
subMerchant.email Email = CONDITIONAL
subMerchant.identifier String = CONDITIONAL
subMerchant.phone String = CONDITIONAL
subMerchant.registeredName String = CONDITIONAL
subMerchant.tradingName String = CONDITIONAL
surchargeAmount Decimal = CONDITIONAL
surchargeSource Enumeration = CONDITIONAL
tax[n] = CONDITIONAL
tax[n].amount Decimal = CONDITIONAL
tax[n].rate Decimal = CONDITIONAL
tax[n].type String = CONDITIONAL
taxAmount Decimal = CONDITIONAL
taxRegistrationId String = CONDITIONAL
taxStatus String = CONDITIONAL
totalAuthorizedAmount Decimal = Always Provided
totalCapturedAmount Decimal = Always Provided
totalRefundedAmount Decimal = Always Provided
transaction[n] = CONDITIONAL
transaction[n].action = CONDITIONAL
transaction[n].action.refundAuthorization Boolean = CONDITIONAL
transaction[n].agreement = CONDITIONAL
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.
transaction[n].agreement.expiryDate Date = CONDITIONAL
transaction[n].agreement.id String = CONDITIONAL
- Recurring payments: you have an agreement with the payer that authorizes you to automatically debit their account at agreed intervals for fixed or variable amounts. For example, gym membership, phone bills, or magazine subscriptions.
- Installment payments: you have an agreement with the payer that authorizes you to process multiple payments over an agreed period of time for a single purchase. For example, the payer purchases an item for $1000 and pays for it in four monthly installments.
- Unscheduled: you have an agreement with the payer that authorizes you to process future payments when required. For example, the payer authorizes you to process an account top-up transaction for a transit card when the account balance drops below a certain threshold.
transaction[n].agreement.recurring = CONDITIONAL
transaction[n].agreement.recurring.amountVariability Enumeration = CONDITIONAL
transaction[n].agreement.recurring.daysBetweenPayments Integer = CONDITIONAL
transaction[n].agreement.recurring.numberOfPayments Integer = CONDITIONAL
transaction[n].agreement.type Enumeration = CONDITIONAL
The gateway will use the value you specify for subsequent payments in the series.
transaction[n].airline = CONDITIONAL
transaction[n].airline.bookingReference Alphanumeric = CONDITIONAL
transaction[n].airline.documentType Enumeration = CONDITIONAL
transaction[n].airline.itinerary = CONDITIONAL
transaction[n].airline.itinerary.leg[n] = CONDITIONAL
transaction[n].airline.itinerary.leg[n].carrierCode Regex = CONDITIONAL
transaction[n].airline.itinerary.leg[n].conjunctionTicketNumber Alphanumeric = CONDITIONAL
transaction[n].airline.itinerary.leg[n].couponNumber Alphanumeric = CONDITIONAL
transaction[n].airline.itinerary.leg[n].departureAirport Upper case alphabetic text = CONDITIONAL
transaction[n].airline.itinerary.leg[n].departureDate Date = CONDITIONAL
transaction[n].airline.itinerary.leg[n].departureTax Decimal = CONDITIONAL
transaction[n].airline.itinerary.leg[n].departureTime Time = CONDITIONAL
transaction[n].airline.itinerary.leg[n].destinationAirport Upper case alphabetic text = CONDITIONAL
transaction[n].airline.itinerary.leg[n].destinationArrivalDate Date = CONDITIONAL
transaction[n].airline.itinerary.leg[n].destinationArrivalTime Time = CONDITIONAL
transaction[n].airline.itinerary.leg[n].endorsementsRestrictions Alphanumeric = CONDITIONAL
transaction[n].airline.itinerary.leg[n].exchangeTicketNumber Alphanumeric = CONDITIONAL
transaction[n].airline.itinerary.leg[n].fare Decimal = CONDITIONAL
transaction[n].airline.itinerary.leg[n].fareBasis Alphanumeric = CONDITIONAL
transaction[n].airline.itinerary.leg[n].fees Decimal = CONDITIONAL
transaction[n].airline.itinerary.leg[n].flightNumber Alphanumeric = CONDITIONAL
transaction[n].airline.itinerary.leg[n].stopoverPermitted Boolean = CONDITIONAL
transaction[n].airline.itinerary.leg[n].taxes Decimal = CONDITIONAL
transaction[n].airline.itinerary.leg[n].travelClass Alphanumeric = CONDITIONAL
transaction[n].airline.itinerary.numberInParty Digits = CONDITIONAL
transaction[n].airline.itinerary.originCountry Upper case alphabetic text = CONDITIONAL
transaction[n].airline.passenger[n] = CONDITIONAL
transaction[n].airline.passenger[n].firstName String = CONDITIONAL
transaction[n].airline.passenger[n].frequentFlyerNumber String = CONDITIONAL
transaction[n].airline.passenger[n].lastName String = CONDITIONAL
transaction[n].airline.passenger[n].middleName String = CONDITIONAL
transaction[n].airline.passenger[n].specificInformation Alphanumeric = CONDITIONAL
transaction[n].airline.passenger[n].title String = CONDITIONAL
transaction[n].airline.planNumber Alphanumeric = CONDITIONAL
transaction[n].airline.ticket = CONDITIONAL
transaction[n].airline.ticket.conjunctionTicketIndicator Boolean = CONDITIONAL
transaction[n].airline.ticket.eTicket Boolean = CONDITIONAL
transaction[n].airline.ticket.exchangedTicketNumber Alphanumeric = CONDITIONAL
transaction[n].airline.ticket.issue = CONDITIONAL
transaction[n].airline.ticket.issue.address String = CONDITIONAL
transaction[n].airline.ticket.issue.carrierCode Regex = CONDITIONAL
transaction[n].airline.ticket.issue.carrierName Alphanumeric = CONDITIONAL
transaction[n].airline.ticket.issue.city Alphanumeric = CONDITIONAL
transaction[n].airline.ticket.issue.country Upper case alphabetic text = CONDITIONAL
transaction[n].airline.ticket.issue.date Date = CONDITIONAL
transaction[n].airline.ticket.issue.travelAgentCode Alphanumeric = CONDITIONAL
transaction[n].airline.ticket.issue.travelAgentName Alphanumeric = CONDITIONAL
transaction[n].airline.ticket.restricted Boolean = CONDITIONAL
transaction[n].airline.ticket.taxOrFee[n] = CONDITIONAL
transaction[n].airline.ticket.taxOrFee[n].amount Decimal = CONDITIONAL
transaction[n].airline.ticket.taxOrFee[n].type Alphanumeric = CONDITIONAL
transaction[n].airline.ticket.ticketNumber Alphanumeric = CONDITIONAL
transaction[n].airline.ticket.totalFare Decimal = CONDITIONAL
transaction[n].airline.ticket.totalFees Decimal = CONDITIONAL
transaction[n].airline.ticket.totalTaxes Decimal = CONDITIONAL
transaction[n].airline.transactionType Enumeration = CONDITIONAL
transaction[n].authentication = CONDITIONAL
This parameter group include payer authentication options available to you, parameters you need to perform payer authentication for an available method, and the results of payer authentication.
transaction[n].authentication.3ds = CONDITIONAL
Depending on the 3-D Secure authentication version applicable you will also need additional parameters:
- 3-D Secure authentication version 1: see the authentication.3ds1 parameter group.
- 3-D Secure authentication version 2: see the authentication.3ds2 parameter group.
transaction[n].authentication.3ds.acsEci Alphanumeric = CONDITIONAL
transaction[n].authentication.3ds.authenticationToken Base64 = CONDITIONAL
For 3DS version 2, this field corresponds to the Authentication Value.
transaction[n].authentication.3ds.transactionId String = CONDITIONAL
For 3DS version 2, this field corresponds to the identifier assigned by the scheme directory server.
This identifier should be used in subsequent operation requests unaltered.
An XID submitted in this field must be in base64 format.
transaction[n].authentication.3ds1 = CONDITIONAL
transaction[n].authentication.3ds1.paResStatus Alpha = CONDITIONAL
transaction[n].authentication.3ds1.veResEnrolled Alpha = Always Provided
This is the value returned in the 'enrolled' field of the Verify Enrollment Response (VERes) message from the card scheme's Directory Server. For example, Y, N, or U. Refer to the relevant documentation for Mastercard SecureCode™, Verified by Visa™, JCB J/Secure™, American Express SafeKey™, or Diners Club ProtectBuy™.
transaction[n].authentication.3ds2 = CONDITIONAL
transaction[n].authentication.3ds2.acsTransactionId String = CONDITIONAL
transaction[n].authentication.3ds2.directoryServerId String = CONDITIONAL
In this case, provide this value in the directoryServerId field on the createTransaction method request message sent from the app on the payer's device to the 3-D Secure Software Development Kit (SDK).
transaction[n].authentication.3ds2.dsTransactionId String = CONDITIONAL
transaction[n].authentication.3ds2.methodCompleted Boolean = Always Provided
transaction[n].authentication.3ds2.methodSupported Enumeration = Always Provided
transaction[n].authentication.3ds2.protocolVersion Alphanumeric + additional characters = CONDITIONAL
transaction[n].authentication.3ds2.requestorId String = Always Provided
transaction[n].authentication.3ds2.requestorName String = Always Provided
transaction[n].authentication.3ds2.sdk = CONDITIONAL
transaction[n].authentication.3ds2.sdk.interface Enumeration = CONDITIONAL
You only need to provide this value if you only support one of these formats.
This field corresponds to EMVCo data element sdkInterface in the field deviceRenderOptions.
transaction[n].authentication.3ds2.sdk.timeout Integer = CONDITIONAL
This field corresponds to EMVCo field sdkMaxTimeout
transaction[n].authentication.3ds2.sdk.uiType Comma separated enumeration = CONDITIONAL
You only need to provide this value if all of these values are not supported.
Note: OTHER_HTML is only supported when authentication.3ds2.sdk.interface allows a HTML UI format.
This field corresponds to EMVCo data element sdkUiType in the field deviceRenderOptions.
transaction[n].authentication.3ds2.statusReasonCode String = CONDITIONAL
transaction[n].authentication.3ds2.transactionStatus Alpha = CONDITIONAL
Refer to the EMVCo specification for 3-D Secure.
transaction[n].authentication.acceptVersions Comma Separated Enumeration = CONDITIONAL
You only need to provide a value if you want to restrict the authentication methods you will accept.
If you do not specify a value, then the gateway treats it as if you will accept all available authentication methods.
If you accept both 3DS2 and 3DS1, then the gateway will use 3-D Secure version 2 if supported by the issuer and fallback to use 3-D Secure version 1 if it is not.
transaction[n].authentication.method Enumeration = CONDITIONAL
transaction[n].authentication.payerInteraction Enumeration = CONDITIONAL
transaction[n].authentication.psd2 = CONDITIONAL
transaction[n].authentication.psd2.exemption Enumeration = CONDITIONAL
- For recurring payments provide the RECURRING_PAYMENT value only if the amount is the same. If the amount varies, provide MERCHANT_INITIATED_TRANSACTION instead.
transaction[n].authentication.psd2.whitelistStatus Enumeration = CONDITIONAL
transaction[n].authentication.redirect.domainName String = CONDITIONAL
transaction[n].authentication.transactionId String = CONDITIONAL
transaction[n].authentication.version Enumeration = CONDITIONAL
transaction[n].availableBalance = CONDITIONAL
transaction[n].availableBalance.ebt[n] = CONDITIONAL
transaction[n].availableBalance.ebt[n].amount Decimal = CONDITIONAL
transaction[n].availableBalance.ebt[n].currency Upper case alphabetic text = CONDITIONAL
transaction[n].availableBalance.ebt[n].type Enumeration = CONDITIONAL
transaction[n].availableBalance.funds = CONDITIONAL
transaction[n].availableBalance.funds.amount Decimal = CONDITIONAL
transaction[n].availableBalance.funds.currency Upper case alphabetic text = CONDITIONAL
transaction[n].billing = CONDITIONAL
transaction[n].billing.address = CONDITIONAL
transaction[n].billing.address.city String = CONDITIONAL
transaction[n].billing.address.company String = CONDITIONAL
transaction[n].billing.address.country Upper case alphabetic text = CONDITIONAL
transaction[n].billing.address.postcodeZip Alphanumeric + additional characters = CONDITIONAL
transaction[n].billing.address.stateProvince String = CONDITIONAL
transaction[n].billing.address.stateProvinceCode String = CONDITIONAL
transaction[n].billing.address.street String = CONDITIONAL
transaction[n].billing.address.street2 String = CONDITIONAL
transaction[n].browserPayment = CONDITIONAL
transaction[n].browserPayment.interaction = CONDITIONAL
transaction[n].browserPayment.interaction.status Enumeration = Always Provided
transaction[n].browserPayment.interaction.timeCompleted ASCII Text = CONDITIONAL
transaction[n].browserPayment.interaction.timeInitiated ASCII Text = CONDITIONAL
transaction[n].browserPayment.interaction.timeRedirected ASCII Text = CONDITIONAL
transaction[n].browserPayment.interaction.timeReturned ASCII Text = CONDITIONAL
transaction[n].browserPayment.operation Enumeration = CONDITIONAL
transaction[n].browserPayment.paypal = CONDITIONAL
transaction[n].browserPayment.paypal.displayShippingAddress Boolean = CONDITIONAL
transaction[n].browserPayment.paypal.overrideShippingAddress Boolean = CONDITIONAL
transaction[n].browserPayment.paypal.paymentConfirmation Enumeration = CONDITIONAL
transaction[n].browserPayment.preferredLanguage String = CONDITIONAL
transaction[n].browserPayment.redirectUrl Url = CONDITIONAL
transaction[n].browserPayment.returnUrl Url = CONDITIONAL
transaction[n].constraints = CONDITIONAL
transaction[n].constraints.paymentPlans = CONDITIONAL
transaction[n].constraints.paymentPlans.numberOfDeferrals Integer = CONDITIONAL
transaction[n].constraints.paymentPlans.numberOfPayments Integer = CONDITIONAL
transaction[n].constraints.paymentPlans.supported[n] String = CONDITIONAL
See Payment Plans for the supported payment plans and their identifiers.
transaction[n].cruise = CONDITIONAL
transaction[n].cruise.bookingReference String = CONDITIONAL
transaction[n].cruise.company = CONDITIONAL
transaction[n].cruise.company.address = CONDITIONAL
transaction[n].cruise.company.address.city String = CONDITIONAL
transaction[n].cruise.company.address.country Upper case alphabetic text = CONDITIONAL
transaction[n].cruise.company.address.postCodeZip Alphanumeric + additional characters = CONDITIONAL
transaction[n].cruise.company.address.stateProvince String = CONDITIONAL
transaction[n].cruise.company.address.street String = CONDITIONAL
transaction[n].cruise.company.address.street2 String = CONDITIONAL
transaction[n].cruise.company.contact = CONDITIONAL
transaction[n].cruise.company.contact.companyPhone Telephone Number = CONDITIONAL
transaction[n].cruise.company.contact.customerServicePhone Telephone Number = CONDITIONAL
transaction[n].cruise.departureDate Date = CONDITIONAL
This field is required when cruise industry data is provided.
transaction[n].cruise.passenger[n] = CONDITIONAL
transaction[n].cruise.passenger[n].firstName String = CONDITIONAL
transaction[n].cruise.passenger[n].folioNumber String = CONDITIONAL
transaction[n].cruise.passenger[n].lastName String = CONDITIONAL
transaction[n].cruise.passenger[n].middleName String = CONDITIONAL
transaction[n].cruise.passenger[n].title String = CONDITIONAL
transaction[n].cruise.returnDate Date = CONDITIONAL
This field is required when cruise.departureDate is provided and the value must be equal to or later than cruise.departureDate.
transaction[n].cruise.shipName String = CONDITIONAL
transaction[n].cruise.travelAgentCode Alphanumeric = CONDITIONAL
transaction[n].cruise.travelAgentName String = CONDITIONAL
transaction[n].cruise.travelPackageItems Comma separated enumeration = CONDITIONAL
If the value CRUISE_ONLY is provided then other items are not permitted in the list.
transaction[n].currencyConversion = CONDITIONAL
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.
transaction[n].currencyConversion.exchangeRateTime DateTime = CONDITIONAL
transaction[n].currencyConversion.marginPercentage Decimal = CONDITIONAL
transaction[n].currencyConversion.payerAmount Decimal = CONDITIONAL
transaction[n].currencyConversion.payerCurrency Upper case alphabetic text = CONDITIONAL
transaction[n].currencyConversion.payerExchangeRate Decimal = CONDITIONAL
transaction[n].currencyConversion.payerReceiptText String = CONDITIONAL
transaction[n].currencyConversion.provider Enumeration = CONDITIONAL
transaction[n].currencyConversion.providerReceipt String = CONDITIONAL
transaction[n].currencyConversion.uptake Enumeration = Always Provided
transaction[n].customer = CONDITIONAL
transaction[n].customer.account = CONDITIONAL
transaction[n].customer.account.authentication = CONDITIONAL
transaction[n].customer.account.authentication.cardAssociation = CONDITIONAL
transaction[n].customer.account.authentication.cardAssociation.action Enumeration = CONDITIONAL
transaction[n].customer.account.authentication.cardAssociation.status Enumeration = CONDITIONAL
transaction[n].customer.account.authentication.data String = CONDITIONAL
transaction[n].customer.account.authentication.method Enumeration = CONDITIONAL
transaction[n].customer.account.authentication.time DateTime = CONDITIONAL
transaction[n].customer.account.history = CONDITIONAL
transaction[n].customer.account.history.addCardAttempts Integer = CONDITIONAL
transaction[n].customer.account.history.annualActivity Integer = CONDITIONAL
transaction[n].customer.account.history.creationDate Date = CONDITIONAL
transaction[n].customer.account.history.issuerAuthentication = CONDITIONAL
transaction[n].customer.account.history.issuerAuthentication.acsTransactionId String = CONDITIONAL
transaction[n].customer.account.history.issuerAuthentication.time DateTime = CONDITIONAL
transaction[n].customer.account.history.issuerAuthentication.type Enumeration = CONDITIONAL
transaction[n].customer.account.history.lastUpdated Date = CONDITIONAL
transaction[n].customer.account.history.passwordLastChanged Date = CONDITIONAL
transaction[n].customer.account.history.recentActivity Integer = CONDITIONAL
transaction[n].customer.account.history.shippingAddressDate Date = CONDITIONAL
transaction[n].customer.account.history.suspiciousActivity Boolean = CONDITIONAL
transaction[n].customer.account.id String = Always Provided
transaction[n].customer.email Email = CONDITIONAL
transaction[n].customer.firstName String = CONDITIONAL
transaction[n].customer.lastName String = CONDITIONAL
transaction[n].customer.mobilePhone String = CONDITIONAL
transaction[n].customer.phone String = CONDITIONAL
transaction[n].customer.taxRegistrationId String = CONDITIONAL
transaction[n].debtRepayment = CONDITIONAL
transaction[n].debtRepayment.paymentRecipient = CONDITIONAL
transaction[n].debtRepayment.paymentRecipient.accountIdentifier String = Always Provided
transaction[n].debtRepayment.paymentRecipient.dateOfBirth Date = Always Provided
transaction[n].debtRepayment.paymentRecipient.lastName String = Always Provided
transaction[n].debtRepayment.paymentRecipient.postcodeZip String = Always Provided
transaction[n].device = CONDITIONAL
transaction[n].device.ani String = CONDITIONAL
transaction[n].device.aniCallType String = CONDITIONAL
transaction[n].device.browser String = CONDITIONAL
transaction[n].device.hostname String = CONDITIONAL
transaction[n].device.ipAddress String = CONDITIONAL
transaction[n].device.mobilePhoneModel String = CONDITIONAL
transaction[n].gatewayEntryPoint Enumeration = CONDITIONAL
transaction[n].merchant Alphanumeric + additional characters = Always Provided
transaction[n].order = Always Provided
transaction[n].order.acceptPartialAmount Boolean = CONDITIONAL
Unless you have been advised by your payment service provider that the gateway supports partial approvals for your acquirer, you can ignore this field.
If the gateway supports partial approvals for your acquirer you must set this field to TRUE else the transaction is rejected by the gateway.
transaction[n].order.amount Decimal = Always Provided
The value of this field in the response is zero if payer funds are not transferred.
transaction[n].order.authenticationStatus Enumeration = CONDITIONAL
transaction[n].order.cashAdvance Boolean = CONDITIONAL
transaction[n].order.cashbackAmount Decimal = CONDITIONAL
transaction[n].order.certainty Enumeration = CONDITIONAL
transaction[n].order.chargeback = CONDITIONAL
transaction[n].order.chargeback.amount Decimal = Always Provided
transaction[n].order.chargeback.currency String = Always Provided
transaction[n].order.creationTime DateTime = Always Provided
transaction[n].order.currency Upper case alphabetic text = Always Provided
transaction[n].order.custom String = CONDITIONAL
transaction[n].order.customerNote String = CONDITIONAL
transaction[n].order.customerOrderDate Date = CONDITIONAL
transaction[n].order.customerReference ASCII Text = CONDITIONAL
transaction[n].order.description String = CONDITIONAL
transaction[n].order.discount = CONDITIONAL
transaction[n].order.discount.amount Decimal = CONDITIONAL
transaction[n].order.discount.code String = CONDITIONAL
transaction[n].order.discount.description String = CONDITIONAL
transaction[n].order.expectedNumberOfCaptures Integer = CONDITIONAL
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.
transaction[n].order.funding = CONDITIONAL
transaction[n].order.funding.amount Decimal = Always Provided
See order.fundingStatus to determine the certainty of this value.
transaction[n].order.funding.currency Upper case alphabetic text = Always Provided
transaction[n].order.fundingStatus Enumeration = CONDITIONAL
When considering funding status, the gateway only examines transactions that can move funds. For example, it ignores Authorizations and declined Captures. This is because fundingStatus reflects the movement of the money for the commercial transaction, it does not reflect the movement of money for fees associated with the transaction.
transaction[n].order.gratuityAmount Decimal = CONDITIONAL
transaction[n].order.id String = Always Provided
transaction[n].order.invoiceNumber String = CONDITIONAL
transaction[n].order.item[n] = CONDITIONAL
transaction[n].order.item[n].brand String = CONDITIONAL
transaction[n].order.item[n].category String = CONDITIONAL
transaction[n].order.item[n].description String = CONDITIONAL
transaction[n].order.item[n].detail = CONDITIONAL
transaction[n].order.item[n].detail.acquirerCustom JSON Text = CONDITIONAL
transaction[n].order.item[n].detail.commodityCode Integer = CONDITIONAL
transaction[n].order.item[n].detail.tax[n] = CONDITIONAL
transaction[n].order.item[n].detail.tax[n].amount Decimal = CONDITIONAL
transaction[n].order.item[n].detail.tax[n].rate Decimal = CONDITIONAL
transaction[n].order.item[n].detail.tax[n].type String = CONDITIONAL
transaction[n].order.item[n].detail.unitDiscountRate Decimal = CONDITIONAL
transaction[n].order.item[n].detail.unitTaxRate Decimal = CONDITIONAL
transaction[n].order.item[n].detail.unitTaxType String = CONDITIONAL
transaction[n].order.item[n].detail.unspsc Integer = CONDITIONAL
transaction[n].order.item[n].detail.upc Integer = CONDITIONAL
transaction[n].order.item[n].industryCategory Enumeration = CONDITIONAL
(order.item.unitPrice + order.item.tax) * order.item.quantity
transaction[n].order.item[n].name String = Always Provided
transaction[n].order.item[n].quantity Decimal = Always Provided
transaction[n].order.item[n].sku String = CONDITIONAL
transaction[n].order.item[n].unitDiscountAmount Decimal = CONDITIONAL
transaction[n].order.item[n].unitOfMeasure String = CONDITIONAL
transaction[n].order.item[n].unitPrice Decimal = Always Provided
transaction[n].order.item[n].unitTaxAmount Decimal = CONDITIONAL
transaction[n].order.itemAmount Decimal = CONDITIONAL
transaction[n].order.lastUpdatedTime DateTime = Always Provided
transaction[n].order.localTaxRegistrationId String = CONDITIONAL
transaction[n].order.merchantAmount Decimal = Always Provided
transaction[n].order.merchantCategoryCode Digits = CONDITIONAL
transaction[n].order.merchantCurrency Upper case alphabetic text = Always Provided
If there is FX on this order, this is based on the rate quote you provided on the payment transactions, if not then this is the order.currency.
transaction[n].order.netAmount Decimal = CONDITIONAL
transaction[n].order.notificationUrl Url = CONDITIONAL
transaction[n].order.owningEntity String = CONDITIONAL
transaction[n].order.purchaseType Enumeration = CONDITIONAL
6051 (Quasi Cash – Merchant or Non-Financial Institutions – Foreign Currency, Non-Fiat Currency) and this transaction is for the purchase of cryptocurrency. Set the value to CRYPTOCURRENCY.
6211 (Securities – Brokers/Dealers) and this transaction is for the purchase of high-risk securities. Set the value to HIGH_RISK_SECURITIES.
6012 (Merchandise and Services—Customer Financial Institutions) or 6051 (Non-Financial Institutions – Foreign Currency, Non-Fiat Currency) and this transaction is for debt repayment. Set the value to DEBT_REPAYMENT.
You may set purchase type to OTHER for any other type of payment.
transaction[n].order.reference String = CONDITIONAL
transaction[n].order.requestorName String = CONDITIONAL
transaction[n].order.reward = CONDITIONAL
transaction[n].order.reward.amount Decimal = CONDITIONAL
transaction[n].order.reward.availableBalance = CONDITIONAL
transaction[n].order.reward.availableBalance.amount Decimal = CONDITIONAL
transaction[n].order.reward.availableBalance.points Decimal = CONDITIONAL
transaction[n].order.reward.points Decimal = Always Provided
transaction[n].order.reward.previousBalance = CONDITIONAL
transaction[n].order.reward.previousBalance.amount Decimal = CONDITIONAL
transaction[n].order.reward.previousBalance.points Decimal = CONDITIONAL
transaction[n].order.reward.program Enumeration = CONDITIONAL
transaction[n].order.shippingAndHandlingAmount Decimal = CONDITIONAL
transaction[n].order.statementDescriptor = CONDITIONAL
transaction[n].order.statementDescriptor.address = CONDITIONAL
transaction[n].order.statementDescriptor.address.city String = CONDITIONAL
transaction[n].order.statementDescriptor.address.company String = CONDITIONAL
transaction[n].order.statementDescriptor.address.country Upper case alphabetic text = CONDITIONAL
transaction[n].order.statementDescriptor.address.postcodeZip Alphanumeric + additional characters = CONDITIONAL
transaction[n].order.statementDescriptor.address.stateProvince String = CONDITIONAL
transaction[n].order.statementDescriptor.address.street String = CONDITIONAL
transaction[n].order.statementDescriptor.address.street2 String = CONDITIONAL
transaction[n].order.statementDescriptor.name String = CONDITIONAL
transaction[n].order.statementDescriptor.phone String = CONDITIONAL
transaction[n].order.status Enumeration = CONDITIONAL
transaction[n].order.subMerchant = CONDITIONAL
transaction[n].order.subMerchant.address = CONDITIONAL
transaction[n].order.subMerchant.address.city String = CONDITIONAL
transaction[n].order.subMerchant.address.company String = CONDITIONAL
transaction[n].order.subMerchant.address.country Upper case alphabetic text = CONDITIONAL
transaction[n].order.subMerchant.address.postcodeZip Alphanumeric + additional characters = CONDITIONAL
transaction[n].order.subMerchant.address.stateProvince String = CONDITIONAL
transaction[n].order.subMerchant.address.street String = CONDITIONAL
transaction[n].order.subMerchant.address.street2 String = CONDITIONAL
transaction[n].order.subMerchant.bankIndustryCode Digits = CONDITIONAL
transaction[n].order.subMerchant.email Email = CONDITIONAL
transaction[n].order.subMerchant.identifier String = CONDITIONAL
transaction[n].order.subMerchant.phone String = CONDITIONAL
transaction[n].order.subMerchant.registeredName String = CONDITIONAL
transaction[n].order.subMerchant.tradingName String = CONDITIONAL
transaction[n].order.supply = CONDITIONAL
transaction[n].order.supply.preorder Boolean = CONDITIONAL
transaction[n].order.supply.preorderAvailabilityDate Date = CONDITIONAL
transaction[n].order.supply.reorder Boolean = CONDITIONAL
transaction[n].order.surchargeAmount Decimal = CONDITIONAL
transaction[n].order.surchargeSource Enumeration = CONDITIONAL
transaction[n].order.tax[n] = CONDITIONAL
transaction[n].order.tax[n].amount Decimal = CONDITIONAL
transaction[n].order.tax[n].rate Decimal = CONDITIONAL
transaction[n].order.tax[n].type String = CONDITIONAL
transaction[n].order.taxAmount Decimal = CONDITIONAL
transaction[n].order.taxRegistrationId String = CONDITIONAL
transaction[n].order.taxStatus String = CONDITIONAL
transaction[n].order.totalAuthorizedAmount Decimal = Always Provided
transaction[n].order.totalCapturedAmount Decimal = Always Provided
transaction[n].order.totalRefundedAmount Decimal = Always Provided
transaction[n].order.valueTransfer = CONDITIONAL
transaction[n].order.valueTransfer.accountType Enumeration = CONDITIONAL
transaction[n].order.valueTransfer.amount Decimal = CONDITIONAL
transaction[n].order.valueTransfer.currency Upper case alphabetic text = CONDITIONAL
The default value is order.currency.
transaction[n].order.valueTransfer.numberOfCards Integer = CONDITIONAL
transaction[n].order.wallet = CONDITIONAL
transaction[n].order.wallet.visaCheckout = CONDITIONAL
transaction[n].order.wallet.visaCheckout.callId String = CONDITIONAL
transaction[n].order.walletIndicator String = CONDITIONAL
transaction[n].order.walletProvider Enumeration = CONDITIONAL
transaction[n].partnerSolutionId String = CONDITIONAL
transaction[n].paymentPlan = CONDITIONAL
transaction[n].paymentPlan.finalAmount Decimal = Always Provided
transaction[n].paymentPlan.interestRate Decimal = Always Provided
transaction[n].paymentPlan.numberOfDeferrals Integer = Always Provided
transaction[n].paymentPlan.numberOfPayments Integer = Always Provided
transaction[n].paymentPlan.paymentAmount Decimal = Always Provided
transaction[n].paymentPlan.planId String = Always Provided
transaction[n].posTerminal = CONDITIONAL
transaction[n].posTerminal.address = CONDITIONAL
transaction[n].posTerminal.address.city String = CONDITIONAL
transaction[n].posTerminal.address.company String = CONDITIONAL
transaction[n].posTerminal.address.country Upper case alphabetic text = CONDITIONAL
transaction[n].posTerminal.address.postcodeZip Alphanumeric + additional characters = CONDITIONAL
transaction[n].posTerminal.address.stateProvince String = CONDITIONAL
transaction[n].posTerminal.address.street String = CONDITIONAL
transaction[n].posTerminal.address.street2 String = CONDITIONAL
transaction[n].posTerminal.attended Enumeration = CONDITIONAL
You must provide a value for this field for chip transactions with UK acquirers.
This field corresponds to EMV tag 9F35
transaction[n].posTerminal.cardPresenceCapability Enumeration = CONDITIONAL
transaction[n].posTerminal.cardholderActivated Enumeration = CONDITIONAL
There are seven types (levels) of CAT devices. Each level has specific card scheme requirements.
If you do not provide a value for this field for a Card Present payment the gateway defaults the value to NOT_CARDHOLDER_ACTIVATED.
This field corresponds to EMV tag 9F35
transaction[n].posTerminal.inputCapability Enumeration = CONDITIONAL
This field corresponds to EMV tag 9F33
transaction[n].posTerminal.lane String = CONDITIONAL
This field corresponds to EMV tag 9F1C
transaction[n].posTerminal.location Enumeration = CONDITIONAL
transaction[n].posTerminal.mobile = CONDITIONAL
transaction[n].posTerminal.mobile.cardInputDevice Enumeration = CONDITIONAL
transaction[n].posTerminal.onlineReasonCode Enumeration = CONDITIONAL
Where more than one reason applies, then the order of priority used for the enumeration list applies.
transaction[n].posTerminal.panEntryMode Enumeration = CONDITIONAL
transaction[n].posTerminal.pinEntryCapability Enumeration = CONDITIONAL
transaction[n].posTerminal.pinLengthCapability Integer = CONDITIONAL
transaction[n].posTerminal.serialNumber ASCII Text = CONDITIONAL
transaction[n].posTerminal.store = CONDITIONAL
transaction[n].posTerminal.store.id String = CONDITIONAL
transaction[n].posTerminal.store.name String = CONDITIONAL
transaction[n].posTerminal.terminalId Alphanumeric = CONDITIONAL
transaction[n].response = Always Provided
transaction[n].response.acquirerCode ASCII Text = CONDITIONAL
transaction[n].response.acquirerMessage ASCII Text = CONDITIONAL
transaction[n].response.cardSecurityCode = CONDITIONAL
transaction[n].response.cardSecurityCode.acquirerCode ASCII Text = CONDITIONAL
transaction[n].response.cardSecurityCode.gatewayCode Enumeration = CONDITIONAL
transaction[n].response.cardholderVerification = CONDITIONAL
transaction[n].response.cardholderVerification.avs = CONDITIONAL
transaction[n].response.cardholderVerification.avs.acquirerCode ASCII Text = CONDITIONAL
transaction[n].response.cardholderVerification.avs.gatewayCode Enumeration = CONDITIONAL
transaction[n].response.cardholderVerification.detailedVerification[n] = CONDITIONAL
transaction[n].response.cardholderVerification.detailedVerification[n].gatewayCode Enumeration = CONDITIONAL
transaction[n].response.cardholderVerification.detailedVerification[n].type Enumeration = CONDITIONAL
transaction[n].response.debugInformation String = CONDITIONAL
transaction[n].response.gatewayCode Enumeration = Always Provided
transaction[n].response.gatewayRecommendation Enumeration = CONDITIONAL
transaction[n].response.onBehalfOfOperation Enumeration = CONDITIONAL
transaction[n].response.recurringPaymentAdvice = CONDITIONAL
transaction[n].response.recurringPaymentAdvice.acquirerCode Digits = CONDITIONAL
transaction[n].result Enumeration = Always Provided
transaction[n].risk = CONDITIONAL
transaction[n].risk.custom String = CONDITIONAL
Field: risk.custom.headOfficeLocation
Value: London UK
transaction[n].risk.response = CONDITIONAL
transaction[n].risk.response.gatewayCode Enumeration = CONDITIONAL
transaction[n].risk.response.reversalResult Enumeration = CONDITIONAL
transaction[n].risk.response.review = CONDITIONAL
transaction[n].risk.response.review.decision Enumeration = CONDITIONAL
transaction[n].risk.response.review.decisionReason String = CONDITIONAL
transaction[n].risk.response.review.note String = CONDITIONAL
transaction[n].risk.response.review.timeOfDecision DateTime = CONDITIONAL
transaction[n].risk.response.review.userId String = CONDITIONAL
transaction[n].risk.response.rule[n] = CONDITIONAL
transaction[n].risk.response.rule[n].data String = CONDITIONAL
transaction[n].risk.response.rule[n].id String = CONDITIONAL
transaction[n].risk.response.rule[n].name String = CONDITIONAL
transaction[n].risk.response.rule[n].recommendation Enumeration = CONDITIONAL
transaction[n].risk.response.rule[n].score Integer = CONDITIONAL
transaction[n].risk.response.rule[n].type Enumeration = CONDITIONAL
transaction[n].risk.response.totalScore Integer = CONDITIONAL
transaction[n].shipping = CONDITIONAL
transaction[n].shipping.address = CONDITIONAL
transaction[n].shipping.address.city String = CONDITIONAL
transaction[n].shipping.address.company String = CONDITIONAL
transaction[n].shipping.address.country Upper case alphabetic text = CONDITIONAL
transaction[n].shipping.address.postcodeZip Alphanumeric + additional characters = CONDITIONAL
transaction[n].shipping.address.source Enumeration = CONDITIONAL
transaction[n].shipping.address.stateProvince String = CONDITIONAL
transaction[n].shipping.address.stateProvinceCode String = CONDITIONAL
transaction[n].shipping.address.street String = CONDITIONAL
transaction[n].shipping.address.street2 String = CONDITIONAL
transaction[n].shipping.address.sameAsBilling Enumeration = CONDITIONAL
The default value for this field is:
SAME - if the shipping and billing address are supplied, and all fields are the same (ignoring non-alphanumerics).
DIFFERENT - if the shipping and billing address are supplied, and at least one field is different (ignoring non-alphanumerics).
UNKNOWN - either shipping address or billing address is absent.
transaction[n].shipping.contact = CONDITIONAL
transaction[n].shipping.contact.email Email = CONDITIONAL
transaction[n].shipping.contact.firstName String = CONDITIONAL
transaction[n].shipping.contact.lastName String = CONDITIONAL
transaction[n].shipping.contact.mobilePhone Telephone Number = CONDITIONAL
The number consists of:
- ‘+’
- country code (1, 2 or 3 digits)
- ‘space’
- national number ( which may embed single spaces characters for readability).
transaction[n].shipping.contact.phone Telephone Number = CONDITIONAL
The number consists of:
- ‘+’
- country code (1, 2 or 3 digits)
- ‘space’
- national number ( which may embed single spaces characters for readability).
transaction[n].shipping.contact.sameAsBilling Enumeration = CONDITIONAL
Default value is UNKNOWN
transaction[n].shipping.method Enumeration = CONDITIONAL
transaction[n].shipping.origin.postcodeZip Alphanumeric + additional characters = CONDITIONAL
transaction[n].sourceOfFunds = CONDITIONAL
For card payments the source of funds information may be represented by combining one or more of the following: explicitly provided card details, a session identifier which the gateway will use to look up the card details and/or a card token. Precedence rules will be applied in that explicitly provided card details will override session card details which will override card token details. Each of these may represent partial card details, however the combination must result in a full and complete set of card details. See Using Multiple Sources of Card Details for examples.
transaction[n].sourceOfFunds.provided = CONDITIONAL
transaction[n].sourceOfFunds.provided.ach = CONDITIONAL
transaction[n].sourceOfFunds.provided.ach.accountType Enumeration = CONDITIONAL
- Consumer (checking or savings), or
- Business
For pre-arranged payments (sourceOfFunds.provided.ach.secCode=PPD) retrieve this information from the payer.
If payments were telephone-initiated (sourceOfFunds.provided.ach.secCode=TEL) or internet-initiated (sourceOfFunds.provided.ach.secCode=WEB) you may choose to limit the payer's options (e.g. only support consumer checking accounts), depending on your type of business (e.g. B2C online webshop).
transaction[n].sourceOfFunds.provided.ach.bankAccountHolder String = CONDITIONAL
transaction[n].sourceOfFunds.provided.ach.bankAccountNumber Alphanumeric + additional characters = CONDITIONAL
transaction[n].sourceOfFunds.provided.ach.routingNumber Digits = CONDITIONAL
- Routing number,
- Transit number, or
- ABA number
Retrieve this information from the payer.
See also http://en.wikipedia.org/wiki/Routing_transit_number.
transaction[n].sourceOfFunds.provided.ach.secCode Enumeration = CONDITIONAL
transaction[n].sourceOfFunds.provided.boletoBancario = CONDITIONAL
transaction[n].sourceOfFunds.provided.boletoBancario.actionType Enumeration = CONDITIONAL
transaction[n].sourceOfFunds.provided.boletoBancario.bankAccountHolder String = Always Provided
transaction[n].sourceOfFunds.provided.boletoBancario.customerType Enumeration = CONDITIONAL
transaction[n].sourceOfFunds.provided.boletoBancario.daysBeforeAction Digits = CONDITIONAL
transaction[n].sourceOfFunds.provided.boletoBancario.dueDate Date = CONDITIONAL
transaction[n].sourceOfFunds.provided.boletoBancario.slipUrl Url = CONDITIONAL
transaction[n].sourceOfFunds.provided.card = CONDITIONAL
Cards: the card details entered directly or collected using a Point of Sale (POS) terminal.
Device payment methods such as Apple Pay, Android Pay, Samsung Pay or Google Pay.
Digital wallets such as Masterpass, Visa Checkout or Amex Express Checkout.
Card scheme tokens where the card was tokenized using a card scheme tokenization service such as Mastercard Digital Enablement Service (MDES).
transaction[n].sourceOfFunds.provided.card.accountType Enumeration = CONDITIONAL
transaction[n].sourceOfFunds.provided.card.brand Enumeration = Always Provided
You may use this information to support surcharging decisions. This information is gathered from 3rd party sources and may not be accurate in all circumstances.
transaction[n].sourceOfFunds.provided.card.devicePayment = CONDITIONAL
transaction[n].sourceOfFunds.provided.card.devicePayment.cryptogramFormat Enumeration = CONDITIONAL
You do not need to provide the cryptogram format if you provide the payment token in sourceOfFunds.provided.card.devicePayment.paymentToken
transaction[n].sourceOfFunds.provided.card.deviceSpecificExpiry = CONDITIONAL
- • Device payments: the expiry date for the Device Primary Account Number (DPAN).
- • Digital wallets: the expiry date for the Token PAN.
- • Card scheme tokens: the expiry date for the Token PAN.
transaction[n].sourceOfFunds.provided.card.deviceSpecificExpiry.month Digits = Always Provided
transaction[n].sourceOfFunds.provided.card.deviceSpecificExpiry.year Digits = Always Provided
transaction[n].sourceOfFunds.provided.card.deviceSpecificNumber Masked digits = Always Provided
- • Device payments: the payers's account number associated with the mobile device used for the payment. This is also known as the Device Primary Account Number (DPAN).
- • Digital wallets: the Token PAN returned by a digital wallet. The gateway only returns this value for Amex Express Checkout.
- • Card scheme tokens: the token generated by a card scheme tokenization service such as Mastercard Digital Enablement Service (MDES). The token is used as an identifier of the payer's Primary Account Number (PAN) securely stored by the service. For MDES, this token is referred to as the Token PAN. For VTS, this is the Token
transaction[n].sourceOfFunds.provided.card.emvRequest String = CONDITIONAL
For the list of field tags to include (if provided by the terminal), see Card Present Payments. Requests with any other tags are rejected by the gateway.
Some of the tags represent data that can occur on explicit fields in this API. You can submit the value either in this field, or in both places. For example, the PAN can be presented as EMV tag 5A in this field, or included both the sourceOfFunds.provided.card.number API field and in EMV tag 5A in this field.
If you specify the EMV tag only, we can populate the explicit field in the API. Fields where this is supported have the text "This field corresponds to EMV tag <tag name>" in their field descriptions.
If you specify both places, there will be no population of the explicit field or validation that the data matches.
The API response will not contain PCI sensitive fields.
transaction[n].sourceOfFunds.provided.card.emvResponse String = CONDITIONAL
The card/terminal uses data returned from the issuer to make the final decision to accept or decline the transaction.
transaction[n].sourceOfFunds.provided.card.encryption Enumeration = CONDITIONAL
transaction[n].sourceOfFunds.provided.card.expiry = CONDITIONAL
transaction[n].sourceOfFunds.provided.card.expiry.month Digits = Always Provided
transaction[n].sourceOfFunds.provided.card.expiry.year Digits = Always Provided
transaction[n].sourceOfFunds.provided.card.fundingMethod Enumeration = Always Provided
transaction[n].sourceOfFunds.provided.card.issuer String = CONDITIONAL
transaction[n].sourceOfFunds.provided.card.localBrand String = CONDITIONAL
You may use this information to support surcharging decisions. This information is gathered from 3rd party sources and may not be accurate in all circumstances.
transaction[n].sourceOfFunds.provided.card.nameOnCard String = CONDITIONAL
transaction[n].sourceOfFunds.provided.card.number Masked digits = Always Provided
- Request
On request, populate this field based on the payment method you are using for the payment:- • Card: the account number embossed onto the card. This field corresponds to EMV tag 5A.
- • Device payment methods such as Apple Pay, Android Pay, Samsung Pay, or Google Pay. Normally for device payments, you would populate sourceOfFunds.provided.card.devicePayment.paymentToken and the gateway will decrypt and extract this field. However, you can populate this field if you decrypt the payment token yourself. In this case use the Device PAN (DPAN) provided in the payment token.
- • Digital wallets such as Masterpass, Visa Checkout or Amex Express Checkout. In this case, provide the PAN retrieved from the wallet.
- • Scheme tokens such as MDES (Mastercard Digital Enablement Service) or Visa Token Service (VTS). For MDES tokens, supply the value called the "Token PAN". For VTS tokens, supply the value called "Token"
- Response
On return, the card number will be populated in 6.4 masking format, for example, 000000xxxxxx0000. If you wish to return unmasked card numbers, you must have the requisite permission, set responseControls.sensitiveData field to UNMASK, and authenticate your call to the API using certificate authentication.
When a DPAN or scheme token was provided in the transaction request, then this field will represent the PAN of the associated payer's account (when supported by the acquirer). This is also referred to as the Funding PAN (FPAN).
transaction[n].sourceOfFunds.provided.card.paymentAccountReference String = CONDITIONAL
transaction[n].sourceOfFunds.provided.card.pin = CONDITIONAL
transaction[n].sourceOfFunds.provided.card.pin.encryptionState Enumeration = CONDITIONAL
transaction[n].sourceOfFunds.provided.card.pin.keySerialNumber Hex = Always Provided
transaction[n].sourceOfFunds.provided.card.scheme Enumeration = Always Provided
transaction[n].sourceOfFunds.provided.card.sequenceNumber Digits = CONDITIONAL
transaction[n].sourceOfFunds.provided.card.storedOnFile Enumeration = CONDITIONAL
If you use Scheme Tokenization services like MDES and store the tokens provided, you have to provide the value STORED and if you pass the token value with out storing them, provide the value NOT_STORED.
If you store yourself, you have to provide the TO_BE_STORED or STORED values for all payments.
transaction[n].sourceOfFunds.provided.card.trackDataProvided Boolean = CONDITIONAL
transaction[n].sourceOfFunds.provided.ebt = CONDITIONAL
transaction[n].sourceOfFunds.provided.ebt.accountType Enumeration = CONDITIONAL
transaction[n].sourceOfFunds.provided.ebt.manualAuthorizationCode Digits = CONDITIONAL
transaction[n].sourceOfFunds.provided.ebt.merchantFns Digits = CONDITIONAL
transaction[n].sourceOfFunds.provided.ebt.voucherNumber Digits = CONDITIONAL
transaction[n].sourceOfFunds.provided.enets = CONDITIONAL
transaction[n].sourceOfFunds.provided.enets.bankAccountHolder String = Always Provided
transaction[n].sourceOfFunds.provided.giftCard = CONDITIONAL
transaction[n].sourceOfFunds.provided.giftCard.brand Enumeration = Always Provided
transaction[n].sourceOfFunds.provided.giftCard.localBrand String = Always Provided
transaction[n].sourceOfFunds.provided.giftCard.number Masked digits = Always Provided
transaction[n].sourceOfFunds.provided.giftCard.pin Masked digits = CONDITIONAL
transaction[n].sourceOfFunds.provided.giftCard.scheme Enumeration = Always Provided
transaction[n].sourceOfFunds.provided.giropay = CONDITIONAL
transaction[n].sourceOfFunds.provided.giropay.bankIdentifier Digits = CONDITIONAL
transaction[n].sourceOfFunds.provided.giropay.bic Alphanumeric = CONDITIONAL
transaction[n].sourceOfFunds.provided.giropay.iban String = CONDITIONAL
transaction[n].sourceOfFunds.provided.ideal = CONDITIONAL
transaction[n].sourceOfFunds.provided.ideal.bankAccountHolder String = CONDITIONAL
transaction[n].sourceOfFunds.provided.ideal.bic Alphanumeric = CONDITIONAL
transaction[n].sourceOfFunds.provided.ideal.iban String = CONDITIONAL
transaction[n].sourceOfFunds.provided.openBankingBankTransfer = CONDITIONAL
transaction[n].sourceOfFunds.provided.openBankingBankTransfer.aspspId String = Always Provided
transaction[n].sourceOfFunds.provided.oxxo = CONDITIONAL
transaction[n].sourceOfFunds.provided.oxxo.bankAccountHolder String = Always Provided
transaction[n].sourceOfFunds.provided.oxxo.dueDate Date = CONDITIONAL
transaction[n].sourceOfFunds.provided.paypal = CONDITIONAL
transaction[n].sourceOfFunds.provided.paypal.accountEmail Email = CONDITIONAL
transaction[n].sourceOfFunds.provided.paypal.accountHolder String = CONDITIONAL
transaction[n].sourceOfFunds.provided.paypal.billingAgreement = CONDITIONAL
transaction[n].sourceOfFunds.provided.paypal.billingAgreement.cardinality Enumeration = CONDITIONAL
transaction[n].sourceOfFunds.provided.paypal.billingAgreement.description String = CONDITIONAL
transaction[n].sourceOfFunds.provided.paypal.billingAgreement.id String = CONDITIONAL
transaction[n].sourceOfFunds.provided.paypal.billingAgreement.name String = CONDITIONAL
transaction[n].sourceOfFunds.provided.paypal.payerId String = CONDITIONAL
transaction[n].sourceOfFunds.provided.pbba = CONDITIONAL
transaction[n].sourceOfFunds.provided.pbba.paymentRequestId Digits = CONDITIONAL
transaction[n].sourceOfFunds.provided.pbba.paymentRequestInputCode Upper case alphabetic text = CONDITIONAL
transaction[n].sourceOfFunds.provided.poli = CONDITIONAL
transaction[n].sourceOfFunds.provided.poli.bankAccountHolder String = Always Provided
transaction[n].sourceOfFunds.provided.sepa = CONDITIONAL
transaction[n].sourceOfFunds.provided.sepa.bankAccountHolder String = Always Provided
transaction[n].sourceOfFunds.provided.sepa.bic Alphanumeric = CONDITIONAL
transaction[n].sourceOfFunds.provided.sepa.iban String = Always Provided
transaction[n].sourceOfFunds.provided.sofort = CONDITIONAL
transaction[n].sourceOfFunds.provided.sofort.bankAccountHolder String = CONDITIONAL
transaction[n].sourceOfFunds.provided.sofort.bankAccountNumber String = CONDITIONAL
transaction[n].sourceOfFunds.provided.sofort.bankIdentifier String = CONDITIONAL
transaction[n].sourceOfFunds.provided.sofort.bic String = CONDITIONAL
transaction[n].sourceOfFunds.provided.sofort.country Upper case alphabetic text = CONDITIONAL
transaction[n].sourceOfFunds.provided.sofort.iban String = CONDITIONAL
transaction[n].sourceOfFunds.provided.weChatPay = CONDITIONAL
transaction[n].sourceOfFunds.provided.weChatPay.accountHolder String = Always Provided
transaction[n].sourceOfFunds.token Alphanumeric = CONDITIONAL
transaction[n].sourceOfFunds.tokenRequestorID Alphanumeric = CONDITIONAL
transaction[n].sourceOfFunds.type Enumeration = CONDITIONAL
If you are making a payment with a gateway token, then you can leave this field unset, and only populate the sourceOfFunds.token field. However you can set this to CARD if you want to overwrite or augment the token data with a card security code, expiry date, or cardholder name.
transaction[n].subgatewayMerchant = CONDITIONAL
- operate a gateway, and
- you are not boarding your merchants onto the gateway, and
- you are enabled for this capability on the gateway.
If you are such a gateway, use these fields to provide information about your merchant, so that our gateway can process their transaction on your behalf.
Note: In these cases, you must also provide a value for field order.merchantCategoryCode
transaction[n].subgatewayMerchant.acquirer[n] = Always Provided
Each record in this group applies to one acquirer. If your gateway knows exactly which acquirer will use for this transaction, then you can provide just that acquirer's data. Alternatively, you can specify a set of acquirers, in which case the gateway will select between them based on the routing rules that configured in our gateway.
In this group, the term 'acquirer' includes banks acquiring scheme cards (such as MasterCard,or Visa), and alternative providers (such as UnionPay, or SEPA)transaction[n].subgatewayMerchant.acquirer[n].3DS1 = CONDITIONAL
transaction[n].subgatewayMerchant.acquirer[n].3DS1.amexSafeKey = CONDITIONAL
transaction[n].subgatewayMerchant.acquirer[n].3DS1.amexSafeKey.merchantId String = CONDITIONAL
transaction[n].subgatewayMerchant.acquirer[n].3DS1.mastercardSecureCode = CONDITIONAL
transaction[n].subgatewayMerchant.acquirer[n].3DS1.mastercardSecureCode.merchantId String = CONDITIONAL
transaction[n].subgatewayMerchant.acquirer[n].3DS1.verifiedByVisa = CONDITIONAL
transaction[n].subgatewayMerchant.acquirer[n].3DS1.verifiedByVisa.cardAcceptorId String = CONDITIONAL
transaction[n].subgatewayMerchant.acquirer[n].3DS1.verifiedByVisa.cardAcceptorTerminalId String = CONDITIONAL
transaction[n].subgatewayMerchant.acquirer[n].acquirerMerchantId String = Always Provided
transaction[n].subgatewayMerchant.acquirer[n].countryCode Upper case alphabetic text = CONDITIONAL
transaction[n].subgatewayMerchant.acquirer[n].fraudRate Integer = CONDITIONAL
transaction[n].subgatewayMerchant.acquirer[n].id String = Always Provided
transaction[n].subgatewayMerchant.acquirer[n].merchantCategoryCode Digits = CONDITIONAL
You only need to provide this value if you are specifying more than one acquirer link, and some acquirers need different MCC values. If the same MCC applies to all acquirers, just specify it as order.merchantCategoryCode.
transaction[n].subgatewayMerchant.address = CONDITIONAL
transaction[n].subgatewayMerchant.address.city String = Always Provided
transaction[n].subgatewayMerchant.address.countryCode Upper case alphabetic text = Always Provided
transaction[n].subgatewayMerchant.address.postcodeZip String = Always Provided
transaction[n].subgatewayMerchant.address.state String = Always Provided
transaction[n].subgatewayMerchant.address.street1 String = Always Provided
transaction[n].subgatewayMerchant.address.street2 String = CONDITIONAL
transaction[n].subgatewayMerchant.authentication[n] = CONDITIONAL
transaction[n].subgatewayMerchant.authentication[n].3DS2 = CONDITIONAL
This API assumes that a merchant has only one registration for a each 3DS2 scheme across all the acquirers. If your merchant has more than one 3DS2 registration that could apply to this transaction, then you need to provide a lineOfBusiness field to narrow to one registration.
transaction[n].subgatewayMerchant.authentication[n].3DS2.requestorId String = CONDITIONAL
transaction[n].subgatewayMerchant.authentication[n].3DS2.requestorName String = CONDITIONAL
transaction[n].subgatewayMerchant.authentication[n].acquirerBIN Digits = CONDITIONAL
transaction[n].subgatewayMerchant.authentication[n].protocol Enumeration = Always Provided
transaction[n].subgatewayMerchant.id Alphanumeric + additional characters = Always Provided
transaction[n].subgatewayMerchant.name String = Always Provided
transaction[n].subgatewayMerchant.websiteUrl Url = Always Provided
transaction[n].timeOfLastUpdate DateTime = CONDITIONAL
transaction[n].timeOfRecord DateTime = CONDITIONAL
transaction[n].transaction = Always Provided
transaction[n].transaction.acquirer = Always Provided
transaction[n].transaction.acquirer.additionalResponseData JSON Text = CONDITIONAL
transaction[n].transaction.acquirer.batch Integer = CONDITIONAL
transaction[n].transaction.acquirer.customData String = CONDITIONAL
transaction[n].transaction.acquirer.date String = CONDITIONAL
transaction[n].transaction.acquirer.id String = CONDITIONAL
transaction[n].transaction.acquirer.merchantId String = CONDITIONAL
transaction[n].transaction.acquirer.settlementDate Date = CONDITIONAL
transaction[n].transaction.acquirer.time String = CONDITIONAL
transaction[n].transaction.acquirer.timeZone Time Offset = CONDITIONAL
transaction[n].transaction.acquirer.transactionId String = CONDITIONAL
transaction[n].transaction.amount Decimal = Always Provided
transaction[n].transaction.authenticationStatus Enumeration = CONDITIONAL
transaction[n].transaction.bancanet = CONDITIONAL
transaction[n].transaction.bancanet.merchantPaymentReference String = Always Provided
transaction[n].transaction.bancanet.paymentDueDate Date = CONDITIONAL
transaction[n].transaction.bancanet.paymentReason String = CONDITIONAL
transaction[n].transaction.batchName String = CONDITIONAL
transaction[n].transaction.currency Upper case alphabetic text = Always Provided
transaction[n].transaction.discountAmount Decimal = CONDITIONAL
transaction[n].transaction.dispute = CONDITIONAL
transaction[n].transaction.dispute.dateRecurringPaymentCancelled Date = CONDITIONAL
transaction[n].transaction.dispute.deadlineDate Date = CONDITIONAL
transaction[n].transaction.dispute.event Enumeration = Always Provided
transaction[n].transaction.dispute.eventDate Date = CONDITIONAL
transaction[n].transaction.dispute.eventInformation String = CONDITIONAL
transaction[n].transaction.dispute.match = CONDITIONAL
When transaction.dispute.matchAction = STANDALONE, the gateway will create a new order containing the chargeback transaction and does not attempt to match it to the original transaction.
When transaction.dispute.matchAction = MATCHED_FALLBACK, then the gateway will first attempt to match this chargeback transaction to an existing financial transaction with these parameters. If it cannot be matched, the gateway will create a new order containing the chargeback transaction. When the chargeback transaction can be matched to more than one merchant gateway profile, a new order will be created against each profile. When this occurs it will be noted in order.description.
transaction[n].transaction.dispute.match.RRN ASCII Text = CONDITIONAL
transaction[n].transaction.dispute.match.acquirerTransactionId String = CONDITIONAL
transaction[n].transaction.dispute.match.date Date = CONDITIONAL
transaction[n].transaction.dispute.match.stan Digits = CONDITIONAL
transaction[n].transaction.dispute.matchAction Enumeration = Always Provided
transaction[n].transaction.dispute.reason ASCII Text = CONDITIONAL
transaction[n].transaction.dispute.reasonCode ASCII Text = CONDITIONAL
transaction[n].transaction.funding = CONDITIONAL
transaction[n].transaction.funding.acquirerEventDescription String = CONDITIONAL
transaction[n].transaction.funding.amount Decimal = CONDITIONAL
This value is provided if transaction.funding.status is FUNDED. It might be provided if transaction.funding.status is FUNDING_ASSURED or FUNDING_ON_HOLD.
transaction[n].transaction.funding.currency Upper case alphabetic text = CONDITIONAL
transaction[n].transaction.funding.date Date = CONDITIONAL
This value is only populated if the date is known with certainty.
transaction[n].transaction.funding.estimatedDate Date = CONDITIONAL
The date is defined in the acquirer's time zone (see transaction.acquirer.timeZone).
transaction[n].transaction.funding.fee[n] = CONDITIONAL
transaction[n].transaction.funding.fee[n].acquirerFeeName String = CONDITIONAL
transaction[n].transaction.funding.fee[n].amount Decimal = CONDITIONAL
transaction[n].transaction.funding.fee[n].date Date = CONDITIONAL
The date is defined in the acquirer's time zone (see transaction.acquirer.timeZone).
transaction[n].transaction.funding.fee[n].estimatedDate Date = CONDITIONAL
The date is defined in the acquirer's time zone (see transaction.acquirer.timeZone).
transaction[n].transaction.funding.fee[n].initiatedDate Date = CONDITIONAL
The date is defined in the acquirer's time zone (see transaction.acquirer.timeZone).
transaction[n].transaction.funding.fee[n].rate Decimal = CONDITIONAL
transaction[n].transaction.funding.fee[n].type Enumeration = CONDITIONAL
transaction[n].transaction.funding.feeAmount Decimal = CONDITIONAL
A breakdown of the fees is shown in the transaction.funding.fee[n] parameter group if this information was provided by your acquirer.
transaction[n].transaction.funding.feeCurrency Upper case alphabetic text = CONDITIONAL
transaction[n].transaction.funding.initiatedDate Date = CONDITIONAL
The date is defined in the acquirer's time zone (see transaction.acquirer.timeZone).
transaction[n].transaction.funding.settlementIdentifier String = CONDITIONAL
transaction[n].transaction.funding.status Enumeration = Always Provided
transaction[n].transaction.id String = Always Provided
- Movement of money. For example, payments and refunds.
- Validations. For example, account verification or 3-D Secure authentication of the payer.
- Undoing other transactions. For example, voiding a payment transaction.
- Chargebacks.
- Fees from your payment service provider.
If you attempt an operation and it fails (eg you try to PAY on a card with no funds), then you need a new id for each retry.
transaction[n].transaction.item[n] = CONDITIONAL
transaction[n].transaction.item[n].brand String = CONDITIONAL
transaction[n].transaction.item[n].category String = CONDITIONAL
transaction[n].transaction.item[n].description String = CONDITIONAL
transaction[n].transaction.item[n].detail = CONDITIONAL
transaction[n].transaction.item[n].detail.acquirerCustom JSON Text = CONDITIONAL
transaction[n].transaction.item[n].detail.commodityCode Integer = CONDITIONAL
transaction[n].transaction.item[n].detail.tax[n] = CONDITIONAL
transaction[n].transaction.item[n].detail.tax[n].amount Decimal = CONDITIONAL
transaction[n].transaction.item[n].detail.tax[n].rate Decimal = CONDITIONAL
transaction[n].transaction.item[n].detail.tax[n].type String = CONDITIONAL
transaction[n].transaction.item[n].detail.unitDiscountRate Decimal = CONDITIONAL
transaction[n].transaction.item[n].detail.unitTaxRate Decimal = CONDITIONAL
transaction[n].transaction.item[n].detail.unitTaxType String = CONDITIONAL
transaction[n].transaction.item[n].detail.unspsc Integer = CONDITIONAL
transaction[n].transaction.item[n].detail.upc Integer = CONDITIONAL
transaction[n].transaction.item[n].industryCategory Enumeration = CONDITIONAL
(order.item.unitPrice + order.item.tax) * order.item.quantity
transaction[n].transaction.item[n].name String = Always Provided
transaction[n].transaction.item[n].quantity Decimal = Always Provided
transaction[n].transaction.item[n].sku String = CONDITIONAL
transaction[n].transaction.item[n].unitDiscountAmount Decimal = CONDITIONAL
transaction[n].transaction.item[n].unitOfMeasure String = CONDITIONAL
transaction[n].transaction.item[n].unitPrice Decimal = Always Provided
transaction[n].transaction.item[n].unitTaxAmount Decimal = CONDITIONAL
transaction[n].transaction.itemAmount Decimal = CONDITIONAL
transaction[n].transaction.merchantNote String = CONDITIONAL
transaction[n].transaction.receipt ASCII Text = CONDITIONAL
transaction[n].transaction.reference String = CONDITIONAL
transaction[n].transaction.requestedAmount Decimal = CONDITIONAL
transaction[n].transaction.shippingAndHandlingAmount Decimal = CONDITIONAL
transaction[n].transaction.source Enumeration = CONDITIONAL
If you have an existing agreement with the payer that authorizes you to process this payment (for example, a recurring payment) then set this value to MERCHANT.You only need to provide transaction.source if you want to override the default value configured for your acquirer link.
Note:
- You can only override the default value if you have the requisite permission.
- The value you provide must match one of those configured by your payment service provider.
- You can only set the transaction source on the initial transaction on an order. It cannot be changed on subsequent transactions.