Capture
Request to capture funds previously reserved by an authorization. A Capture transaction triggers the movement of funds from the payer's account to the merchant's account. Typically, a Capture is linked to the authorization through the orderId - you provide the original orderId, a new transactionId, and the amount you wish to capture. You may provide other fields (such as shipping address) if you want to update their values; however, you must NOT provide sourceOfFunds.
In rare situations, you may want to capture against an authorization that you obtained from elsewhere (see Standalone Capture). In this case, you need to provide all the relevant fields, including the sourceOfFunds and transaction.authorizationCode, in addition to a new orderId.
URL | https://test-nbkpayment.mtf.gateway.mastercard.com/api/nvp/version/81 |
HTTP Method | POST |
Authentication |
This operation requires authentication via one of the following methods:
|
Request Parameters
apiOperation String =CAPTURE FIXED
merchant Alphanumeric + additional characters = COMPULSORY
order.id String = COMPULSORY
transaction = COMPULSORY
transaction.amount Decimal = COMPULSORY
transaction.currency Upper case alphabetic text = COMPULSORY
transaction.id String = COMPULSORY
- Movement of money. For example, payments and refunds.
- Validations. For example, account verification or 3-D Secure authentication of the payer.
- Undoing other transactions. For example, voiding a payment transaction.
- Chargebacks.
- Fees from your payment service provider.
If you attempt an operation and it fails (eg you try to PAY on a card with no funds), then you need a new id for each retry.
accountFunding = OPTIONAL
accountFunding.purpose Enumeration = OPTIONAL
accountFunding.recipient = OPTIONAL
accountFunding.recipient.account = OPTIONAL
accountFunding.recipient.account.fundingMethod Enumeration = OPTIONAL
accountFunding.recipient.account.identifier String = OPTIONAL
accountFunding.recipient.account.identifierType Enumeration = OPTIONAL
accountFunding.recipient.address = OPTIONAL
accountFunding.recipient.address.city String = OPTIONAL
accountFunding.recipient.address.country Upper case alphabetic text = OPTIONAL
accountFunding.recipient.address.postCodeZip String = OPTIONAL
accountFunding.recipient.address.stateProvinceCode String = OPTIONAL
accountFunding.recipient.address.street String = OPTIONAL
accountFunding.recipient.address.street2 String = OPTIONAL
accountFunding.recipient.firstName String = OPTIONAL
accountFunding.recipient.identification = OPTIONAL
accountFunding.recipient.identification.country Upper case alphabetic text = OPTIONAL
accountFunding.recipient.identification.type Enumeration = OPTIONAL
accountFunding.recipient.identification.value String = OPTIONAL
accountFunding.recipient.lastName String = OPTIONAL
accountFunding.recipient.middleName String = OPTIONAL
accountFunding.senderIsRecipient Boolean = OPTIONAL
accountFunding.senderType Enumeration = OPTIONAL
agreement = OPTIONAL
Do not provide this parameter group if you are storing the payment details for subsequent payer-initiated payments only.
See Credential on File, Cardholder, and Merchant Initiated Transactions for details.
agreement.amountVariability Enumeration = OPTIONAL
agreement.customData String = OPTIONAL
agreement.expiryDate Date = OPTIONAL
agreement.id String = OPTIONAL
- Recurring payments: you have an agreement with the payer that authorizes you to automatically debit their account at agreed intervals for fixed or variable amounts. For example, gym membership, phone bills, or magazine subscriptions.
- Installment payments: you have an agreement with the payer that authorizes you to process multiple payments over an agreed period of time for a single purchase. For example, the payer purchases an item for $1000 and pays for it in four monthly installments.
- Unscheduled: you have an agreement with the payer that authorizes you to process future payments when required. For example, the payer authorizes you to process an account top-up transaction for a transit card when the account balance drops below a certain threshold.
- Industry Practice: you have an agreement with the payer that authorizes you to initiate additional transactions to fulfil a standard business practice related to an original payment initiated by the payer. For example, a delayed charge for use of the hotel mini bar after the payer has checked out or a no show penalty charge when the payer fails to show for a booking.
agreement.maximumAmountPerPayment Decimal = OPTIONAL
agreement.minimumAmountPerPayment Decimal = OPTIONAL
agreement.minimumDaysBetweenPayments Integer = OPTIONAL
agreement.numberOfPayments Integer = OPTIONAL
agreement.paymentFrequency Enumeration = OPTIONAL
agreement.retailer = OPTIONAL
agreement.retailer.abbreviatedTradingName String = OPTIONAL
agreement.retailer.merchantCategoryCode String = OPTIONAL
agreement.retailer.tradingName String = OPTIONAL
agreement.startDate Date = OPTIONAL
agreement.type Enumeration = OPTIONAL
The gateway will use the value you specify for subsequent payments in the series.
airline = OPTIONAL
airline.bookingReference Alphanumeric = OPTIONAL
airline.documentType Enumeration = OPTIONAL
airline.itinerary = OPTIONAL
airline.itinerary.leg[n] = OPTIONAL
airline.itinerary.leg[n].carrierCode Regex = OPTIONAL
airline.itinerary.leg[n].conjunctionTicketNumber Alphanumeric = OPTIONAL
airline.itinerary.leg[n].couponNumber Alphanumeric = OPTIONAL
airline.itinerary.leg[n].departureAirport Upper case alphabetic text = OPTIONAL
airline.itinerary.leg[n].departureDate Date = OPTIONAL
airline.itinerary.leg[n].departureTax Decimal = OPTIONAL
airline.itinerary.leg[n].departureTime Time = OPTIONAL
airline.itinerary.leg[n].destinationAirport Upper case alphabetic text = OPTIONAL
airline.itinerary.leg[n].destinationArrivalDate Date = OPTIONAL
airline.itinerary.leg[n].destinationArrivalTime Time = OPTIONAL
airline.itinerary.leg[n].endorsementsRestrictions Alphanumeric = OPTIONAL
airline.itinerary.leg[n].exchangeTicketNumber Alphanumeric = OPTIONAL
airline.itinerary.leg[n].fare Decimal = OPTIONAL
airline.itinerary.leg[n].fareBasis Alphanumeric = OPTIONAL
airline.itinerary.leg[n].fees Decimal = OPTIONAL
airline.itinerary.leg[n].flightNumber Alphanumeric = OPTIONAL
airline.itinerary.leg[n].stopoverPermitted Boolean = OPTIONAL
airline.itinerary.leg[n].taxes Decimal = OPTIONAL
airline.itinerary.leg[n].travelClass Alphanumeric = OPTIONAL
airline.itinerary.numberInParty Digits = OPTIONAL
airline.itinerary.originCountry Upper case alphabetic text = OPTIONAL
airline.passenger[n] = OPTIONAL
airline.passenger[n].firstName String = OPTIONAL
airline.passenger[n].frequentFlyerNumber String = OPTIONAL
airline.passenger[n].lastName String = OPTIONAL
airline.passenger[n].middleName String = OPTIONAL
airline.passenger[n].specificInformation Alphanumeric = OPTIONAL
airline.passenger[n].title String = OPTIONAL
airline.planNumber Alphanumeric = OPTIONAL
airline.ticket = OPTIONAL
airline.ticket.conjunctionTicketIndicator Boolean = OPTIONAL
airline.ticket.eTicket Boolean = OPTIONAL
airline.ticket.exchangedTicketNumber Alphanumeric = OPTIONAL
airline.ticket.issue = OPTIONAL
airline.ticket.issue.address String = OPTIONAL
airline.ticket.issue.carrierCode Regex = OPTIONAL
airline.ticket.issue.carrierName Alphanumeric = OPTIONAL
airline.ticket.issue.city String = OPTIONAL
airline.ticket.issue.country Upper case alphabetic text = OPTIONAL
airline.ticket.issue.date Date = OPTIONAL
airline.ticket.issue.travelAgentCode Alphanumeric = OPTIONAL
airline.ticket.issue.travelAgentName Alphanumeric = OPTIONAL
airline.ticket.restricted Boolean = OPTIONAL
airline.ticket.taxOrFee[n] = OPTIONAL
airline.ticket.taxOrFee[n].amount Decimal = OPTIONAL
airline.ticket.taxOrFee[n].type Alphanumeric = OPTIONAL
airline.ticket.ticketNumber Alphanumeric = OPTIONAL
airline.ticket.totalFare Decimal = OPTIONAL
airline.ticket.totalFees Decimal = OPTIONAL
airline.ticket.totalTaxes Decimal = OPTIONAL
airline.transactionType Enumeration = OPTIONAL
apiOperation String =CAPTURE FIXED
authentication = OPTIONAL
This parameter group include payer authentication options available to you, parameters you need to perform payer authentication for an available method, and the results of payer authentication.
authentication.3ds = OPTIONAL
Parameters in this group apply to both 3-D Secure authentication version 1 and 3-D Secure Authentication version 2.
Depending on the 3-D Secure authentication version applicable you will also need additional parameters:
- 3-D Secure authentication version 1: see the authentication.3ds1 parameter group.
- 3-D Secure authentication version 2: see the authentication.3ds2 parameter group.
authentication.3ds.acsEci Alphanumeric = OPTIONAL
authentication.3ds.authenticationToken Base64 = OPTIONAL
For 3DS version 2, this field corresponds to the Authentication Value.
authentication.3ds.transactionId String = OPTIONAL
For 3DS version 2, this field corresponds to the identifier assigned by the scheme directory server.
This identifier should be used in subsequent operation requests unaltered.
An XID submitted in this field must be in base64 format.
authentication.3ds1 = OPTIONAL
authentication.3ds1.paResStatus Alpha = OPTIONAL
authentication.3ds1.veResEnrolled Alpha = OPTIONAL
This is the value returned in the 'enrolled' field of the Verify Enrollment Response (VERes) message from the card scheme's Directory Server. For example, Y, N, or U. Refer to the relevant documentation for Mastercard SecureCode™, Verified by Visa™, JCB J/Secure™, American Express SafeKey™, or Diners Club ProtectBuy™.
authentication.3ds2 = OPTIONAL
authentication.3ds2.acsReference String = OPTIONAL
authentication.3ds2.acsTransactionId String = OPTIONAL
authentication.3ds2.authenticationScheme Enumeration = OPTIONAL
For example, for externally authenticated Mada co-branded transactions, you must provide either MADA, MASTERCARD or VISA to specify the 3DS directory server.
authentication.3ds2.custom JSON Text = OPTIONAL
authentication.3ds2.dsReference String = OPTIONAL
authentication.3ds2.protocolVersion Alphanumeric + additional characters = OPTIONAL
authentication.3ds2.statusReasonCode String = OPTIONAL
authentication.3ds2.transactionStatus Alpha = OPTIONAL
Refer to the EMVCo specification for 3-D Secure.
authentication.amount Decimal = OPTIONAL
authentication.time DateTime = OPTIONAL
billing = OPTIONAL
billing.address = OPTIONAL
billing.address.city String = OPTIONAL
billing.address.company String = OPTIONAL
billing.address.country Upper case alphabetic text = OPTIONAL
billing.address.postcodeZip Alphanumeric + additional characters = OPTIONAL
billing.address.stateProvince String = OPTIONAL
billing.address.street String = OPTIONAL
billing.address.street2 String = OPTIONAL
correlationId String = OPTIONAL
cruise = OPTIONAL
cruise.bookingReference String = OPTIONAL
cruise.company = OPTIONAL
cruise.company.contact = OPTIONAL
cruise.company.contact.companyPhone Telephone Number = OPTIONAL
cruise.company.contact.customerServicePhone Telephone Number = OPTIONAL
cruise.departureDate Date = OPTIONAL
This field is required when cruise industry data is provided.
cruise.departurePort = OPTIONAL
cruise.departurePort.address = OPTIONAL
cruise.departurePort.address.city String = OPTIONAL
cruise.departurePort.address.country Upper case alphabetic text = OPTIONAL
cruise.departurePort.address.postCodeZip Alphanumeric + additional characters = OPTIONAL
cruise.departurePort.address.stateProvinceCode String = OPTIONAL
cruise.departurePort.address.street String = OPTIONAL
cruise.departurePort.address.street2 String = OPTIONAL
cruise.passenger[n] = OPTIONAL
cruise.passenger[n].firstName String = OPTIONAL
cruise.passenger[n].folioNumber String = OPTIONAL
cruise.passenger[n].lastName String = OPTIONAL
cruise.passenger[n].middleName String = OPTIONAL
cruise.passenger[n].title String = OPTIONAL
cruise.returnDate Date = OPTIONAL
This field is required when cruise.departureDate is provided and the value must be equal to or later than cruise.departureDate.
cruise.shipName String = OPTIONAL
cruise.travelAgentCode Alphanumeric = OPTIONAL
cruise.travelAgentName String = OPTIONAL
cruise.travelPackageItems Comma separated enumeration = OPTIONAL
If the value CRUISE_ONLY is provided then other items are not permitted in the list.
currencyConversion = OPTIONAL
You can only provide DCC information on the initial transaction for an order.
If the initial transaction for an order is a payer authentication transaction with DCC information and the subsequent authorization or pay transaction contains different DCC information, that authorization or pay transaction will be rejected.
If DCC information is provided on subsequent capture or refund for an order, it will be ignored.
currencyConversion.exchangeRateTime DateTime = OPTIONAL
currencyConversion.marginPercentage Decimal = OPTIONAL
currencyConversion.payerAmount Decimal = OPTIONAL
currencyConversion.payerCurrency Upper case alphabetic text = OPTIONAL
currencyConversion.payerExchangeRate Decimal = OPTIONAL
currencyConversion.provider Enumeration = OPTIONAL
currencyConversion.providerReceipt String = OPTIONAL
currencyConversion.requestId String = OPTIONAL
currencyConversion.uptake Enumeration = OPTIONAL
customer = OPTIONAL
customer.email Email = OPTIONAL
customer.firstName String = OPTIONAL
customer.identification = OPTIONAL
customer.identification.country Upper case alphabetic text = OPTIONAL
customer.identification.type Enumeration = OPTIONAL
customer.identification.value String = OPTIONAL
customer.lastName String = OPTIONAL
customer.middleName String = OPTIONAL
customer.mobilePhone Telephone Number = OPTIONAL
The number consists of:
- ‘+’
- country code (1, 2 or 3 digits)
- ‘space’
- national number ( which may embed single spaces characters for readability).
customer.phone Telephone Number = OPTIONAL
The number consists of:
- ‘+’
- country code (1, 2 or 3 digits)
- ‘space’
- national number ( which may embed single spaces characters for readability).
customer.taxRegistrationId String = OPTIONAL
device = OPTIONAL
device.ani String = OPTIONAL
device.aniCallType String = OPTIONAL
device.browser String = OPTIONAL
device.fingerprint String = OPTIONAL
device.hostname String = OPTIONAL
device.ipAddress String = OPTIONAL
IPv6 address will only be used in EMV 3DS authentication. Supplied IPv6 address will not be used for any other purposes.
initiator.userId String = OPTIONAL
merchant Alphanumeric + additional characters = COMPULSORY
order = OPTIONAL
order.acceptPartialAmount Boolean = OPTIONAL
Unless you have been advised by your payment service provider that the gateway supports partial approvals for your acquirer, you can ignore this field.
If the gateway supports partial approvals for your acquirer you must set this field to TRUE else the transaction is rejected by the gateway.
order.custom String = OPTIONAL
order.customerNote String = OPTIONAL
order.customerOrderDate Date = OPTIONAL
order.customerReference ASCII Text = OPTIONAL
order.description String = OPTIONAL
order.expectedNumberOfCaptures Digits = OPTIONAL
The field indicates the total number of Capture requests you intend to submit for an order. For example, if you intend to deliver the goods in two shipments and will capture part of the total authorized amount when you make each shipment, set the value of this field to 2.
If the value equals or drops below the actual number of successful Captures, then the gateway will prevent further Captures and void the outstanding Authorization amount (depending on your merchant profile configuration). If you are unsure of the number of Captures, set the value to 99, and to one on your last Capture.
If you do not provided a value for this field, but had previously provided one, the previous value is applied. For example, if you provide a value 2 on the first Capture for the order and then submit a second Capture without a value, the gateway assumes that the value is still 2.
order.industryPracticePaymentReason Enumeration = OPTIONAL
A merchant initiated industry practice transaction must also contain the 'scheme transaction Id' from the associated cardholder initiated transaction.
You can provide the referenceOrderId of the relevant cardholder initiated transaction and the gateway will include the 'scheme transaction Id' on the industry practice transaction. For example, when you submit a 'delayed charge', you should provide the referenceOrderId of the cardholder-initiated transaction that resulted in the delayed charge.
Alternatively, you can provide the 'scheme transaction Id' of the cardholder initiated transaction in the industry practice transaction using the field transaction.acquirer.traceId.
You must have obtained the payer's consent prior to submitting industry practice transactions.
order.invoiceNumber String = OPTIONAL
order.localTaxRegistrationId String = OPTIONAL
order.marketplace = OPTIONAL
order.marketplace.retailerLocation Enumeration = OPTIONAL
order.merchantCategoryCode Digits = OPTIONAL
order.notificationUrl Url = OPTIONAL
order.owningEntity String = OPTIONAL
order.purchaseType Enumeration = OPTIONAL
order.reference String = OPTIONAL
order.requestorName String = OPTIONAL
order.statementDescriptor = OPTIONAL
order.statementDescriptor.address = OPTIONAL
order.statementDescriptor.address.city String = OPTIONAL
order.statementDescriptor.address.company String = OPTIONAL
order.statementDescriptor.address.country Upper case alphabetic text = OPTIONAL
order.statementDescriptor.address.postcodeZip Alphanumeric + additional characters = OPTIONAL
order.statementDescriptor.address.stateProvince String = OPTIONAL
For an address in Canada provide the 2-letter ISO 3166-2 province code.
order.statementDescriptor.address.street String = OPTIONAL
order.statementDescriptor.address.street2 String = OPTIONAL
order.statementDescriptor.name String = OPTIONAL
order.statementDescriptor.phone String = OPTIONAL
order.subMerchant = OPTIONAL
order.subMerchant.address = OPTIONAL
order.subMerchant.address.city String = OPTIONAL
order.subMerchant.address.company String = OPTIONAL
order.subMerchant.address.country Upper case alphabetic text = OPTIONAL
order.subMerchant.address.postcodeZip Alphanumeric + additional characters = OPTIONAL
order.subMerchant.address.stateProvince String = OPTIONAL
For an address in Canada provide the 2-letter ISO 3166-2 province code.
order.subMerchant.address.street String = OPTIONAL
order.subMerchant.address.street2 String = OPTIONAL
order.subMerchant.bankIndustryCode Digits = OPTIONAL
order.subMerchant.disputeContactPhone Telephone Number = OPTIONAL
order.subMerchant.email Email = OPTIONAL
order.subMerchant.governmentCountryCode Upper case alphabetic text = OPTIONAL
order.subMerchant.identifier String = COMPULSORY
order.subMerchant.marketplaceId String = OPTIONAL
order.subMerchant.phone String = OPTIONAL
order.subMerchant.registeredName String = OPTIONAL
order.subMerchant.tradingName String = COMPULSORY
order.taxRegistrationId String = OPTIONAL
order.taxStatus Enumeration = OPTIONAL
order.walletIndicator String = OPTIONAL
order.walletProvider Enumeration = OPTIONAL
- • Device payment methods such as Apple Pay, Android Pay, Samsung Pay, or Google Pay.
- • Digital wallets such as Masterpass, Visa Checkout or Amex Express Checkout.
order.cashbackAmount Decimal = OPTIONAL
This field corresponds to EMV tag 9F03
order.gratuityAmount Decimal = OPTIONAL
order.id String = COMPULSORY
order.merchantCharge = OPTIONAL
order.merchantCharge.amount Decimal = OPTIONAL
order.merchantCharge.type Enumeration = COMPULSORY
partnerSolutionId String = OPTIONAL
posTerminal = OPTIONAL
posTerminal.address = OPTIONAL
posTerminal.address.city String = OPTIONAL
posTerminal.address.company String = OPTIONAL
posTerminal.address.country Upper case alphabetic text = OPTIONAL
posTerminal.address.postcodeZip Alphanumeric + additional characters = OPTIONAL
posTerminal.address.stateProvince String = OPTIONAL
posTerminal.address.street String = OPTIONAL
posTerminal.address.street2 String = OPTIONAL
posTerminal.attended Enumeration = OPTIONAL
You must provide a value for this field for chip transactions with UK acquirers.
This field corresponds to EMV tag 9F35
posTerminal.cardPresenceCapability Enumeration = OPTIONAL
posTerminal.cardholderActivated Enumeration = OPTIONAL
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
posTerminal.inputCapability Enumeration = OPTIONAL
This field corresponds to EMV tag 9F33
posTerminal.lane String = OPTIONAL
This field corresponds to EMV tag 9F1C
posTerminal.location Enumeration = OPTIONAL
posTerminal.mobile = OPTIONAL
posTerminal.mobile.cardInputDevice Enumeration = OPTIONAL
posTerminal.onlineReasonCode Enumeration = OPTIONAL
Where more than one reason applies, then the order of priority used for the enumeration list applies.
posTerminal.panEntryMode Enumeration = OPTIONAL
posTerminal.pinEntryCapability Enumeration = OPTIONAL
posTerminal.pinLengthCapability Integer = OPTIONAL
posTerminal.serialNumber ASCII Text = OPTIONAL
posTerminal.store = OPTIONAL
posTerminal.store.id String = OPTIONAL
posTerminal.store.name String = OPTIONAL
responseControls = OPTIONAL
responseControls.sensitiveData String = OPTIONAL
risk = OPTIONAL
risk.custom String = OPTIONAL
Field: risk.custom.headOfficeLocation
Value: London UK
session.id ASCII Text = OPTIONAL
session.version ASCII Text = OPTIONAL
To use optimistic locking, record session.version when you make your decisions, and then pass that value in session.version when you submit your request operation to the gateway.
If session.version provided by you does not match that stored against the session, the gateway will reject the operation with error.cause=INVALID_REQUEST.
See Making Business Decisions Based on Session Content.
shipping = OPTIONAL
shipping.address = OPTIONAL
shipping.address.city String = OPTIONAL
shipping.address.company String = OPTIONAL
shipping.address.country Upper case alphabetic text = OPTIONAL
shipping.address.postcodeZip Alphanumeric + additional characters = OPTIONAL
shipping.address.source Enumeration = OPTIONAL
shipping.address.stateProvince String = OPTIONAL
shipping.address.stateProvinceCode String = OPTIONAL
shipping.address.street String = OPTIONAL
shipping.address.street2 String = OPTIONAL
shipping.contact = OPTIONAL
shipping.contact.email Email = OPTIONAL
shipping.contact.firstName String = OPTIONAL
shipping.contact.lastName String = OPTIONAL
shipping.contact.mobilePhone Telephone Number = OPTIONAL
The number consists of:
- ‘+’
- country code (1, 2 or 3 digits)
- ‘space’
- national number ( which may embed single spaces characters for readability).
shipping.contact.phone Telephone Number = OPTIONAL
The number consists of:
- ‘+’
- country code (1, 2 or 3 digits)
- ‘space’
- national number ( which may embed single spaces characters for readability).
shipping.method Enumeration = OPTIONAL
shipping.origin.postcodeZip Alphanumeric + additional characters = OPTIONAL
sourceOfFunds = OPTIONAL
For card payments the source of funds information may be represented by combining one or more of the following: explicitly provided card details, a session identifier which the gateway will use to look up the card details and/or a card token. Precedence rules will be applied in that explicitly provided card details will override session card details which will override card token details. Each of these may represent partial card details, however the combination must result in a full and complete set of card details. See Using Multiple Sources of Card Details for examples.
sourceOfFunds.provided = OPTIONAL
sourceOfFunds.provided.card = OPTIONAL
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 = OPTIONAL
sourceOfFunds.provided.card.emvRequest String = OPTIONAL
For the list of field tags to include (if provided by the terminal), see Card Present Payments. Requests with any other tags are rejected by the gateway.
Some of the tags represent data that can occur on explicit fields in this API. You can submit the value either in this field, or in both places. For example, the PAN can be presented as EMV tag 5A in this field, or included both the sourceOfFunds.provided.card.number API field and in EMV tag 5A in this field.
If you specify the EMV tag only, we can populate the explicit field in the API. Fields where this is supported have the text "This field corresponds to EMV tag <tag name>" in their field descriptions.
If you specify both places, there will be no population of the explicit field or validation that the data matches.
The API response will not contain PCI sensitive fields.
sourceOfFunds.provided.card.expiry = OPTIONAL
sourceOfFunds.provided.card.expiry.month Digits = COMPULSORY
sourceOfFunds.provided.card.expiry.year Digits = COMPULSORY
sourceOfFunds.provided.card.maskedFpan Masked digits = OPTIONAL
RequestNormally you do not need to populate this field, as the gateway will populate this field in the session, and populate it into the payment request when you submit the payment using the session. You would only provide this value, if you had access to FPAN information that was not available to the gateway. On responses, the gateway populates it with a form that the payer would recognize (also explained in more detail below).
Retrieve session response
The gateway always populates this field with its best understanding of the masked FPAN.If you are showing PAN data from the session to the payer, then use this field rather than sourceOfFunds.provided.card.number from the session. This is because this field contains a PAN that the payer will recognize whereas sourceOfFunds.provided.card.number could contain a scheme token, or device PAN which the payer will not recognize. After the payment is processed, the gateway will populate the sourceOfFunds.provided.card.number in the payment response with its best understanding of the masked FPAN. You can show this value to the payer after the payment is complete. This logic also applies to the maskedFpanExpiry field.
sourceOfFunds.provided.card.maskedFpanExpiry = OPTIONAL
sourceOfFunds.provided.card.maskedFpanExpiry.month Digits = OPTIONAL
sourceOfFunds.provided.card.maskedFpanExpiry.year Digits = OPTIONAL
sourceOfFunds.provided.card.nameOnCard String = OPTIONAL
sourceOfFunds.provided.card.number Digits = OPTIONAL
- Request
On request, populate this field based on the payment method you are using for the payment:- • Card: the account number embossed onto the card. 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.p2pe = OPTIONAL
sourceOfFunds.provided.card.p2pe.cardBin Digits = OPTIONAL
If you do not provided this, the gateway will not perform this check.
sourceOfFunds.provided.card.p2pe.encryptionState String = OPTIONAL
sourceOfFunds.provided.card.p2pe.initializationVector Hex = OPTIONAL
sourceOfFunds.provided.card.p2pe.keySerialNumber Hex = COMPULSORY
sourceOfFunds.provided.card.p2pe.payload Hex = COMPULSORY
sourceOfFunds.provided.card.pin = OPTIONAL
sourceOfFunds.provided.card.pin.encryptionState Enumeration = OPTIONAL
sourceOfFunds.provided.card.pin.keySerialNumber Hex = COMPULSORY
sourceOfFunds.provided.card.pin.payload Hex = COMPULSORY
sourceOfFunds.provided.card.securityCode Digits = OPTIONAL
sourceOfFunds.provided.card.sequenceNumber Digits = OPTIONAL
sourceOfFunds.provided.card.storedOnFile Enumeration = OPTIONAL
sourceOfFunds.provided.card.track1 Track 1 Data = OPTIONAL
Provide this for stripe and EMV fallback to stripe cases.
This field corresponds to EMV tag 56
Data may consist of the characters: ? @ A B C D E F G H I J K L M N O P Q R S T U V W X Y Z [ \ ] ^ _ ]]>
sourceOfFunds.provided.card.track2 Track 2 Data = OPTIONAL
Provide this for stripe and EMV fallback to stripe cases.
The contents of this field must match the PAN and expiry fields included in the Transaction Request.
This field corresponds to EMV tag 57
Data may consist of the characters: ? ]]>
sourceOfFunds.provided.ebt = OPTIONAL
sourceOfFunds.provided.ebt.accountType Enumeration = OPTIONAL
sourceOfFunds.provided.ebt.manualAuthorizationCode Digits = OPTIONAL
sourceOfFunds.provided.ebt.merchantFns Digits = OPTIONAL
sourceOfFunds.provided.ebt.voucherNumber Digits = OPTIONAL
sourceOfFunds.provided.giftCard = OPTIONAL
sourceOfFunds.provided.giftCard.expectedLocalBrand String = OPTIONAL
sourceOfFunds.provided.giftCard.number Digits = OPTIONAL
sourceOfFunds.provided.giftCard.pin Digits = OPTIONAL
sourceOfFunds.token Alphanumeric = OPTIONAL
If account identifier details are also contained in the request, or the request contains a session with account identifier details, these take precedence over the details stored against the token.
sourceOfFunds.tokenRequestorID Alphanumeric = OPTIONAL
sourceOfFunds.type Enumeration = OPTIONAL
If you are making a payment with a gateway token, then you can leave this field unset, and only populate the sourceOfFunds.token field. However you can set this to CARD if you want to overwrite or augment the token data with a card security code, expiry date, or cardholder name.
transaction = COMPULSORY
transaction.acquirer = OPTIONAL
transaction.acquirer.customData String = OPTIONAL
transaction.acquirer.transactionId String = OPTIONAL
transaction.amount Decimal = COMPULSORY
transaction.currency Upper case alphabetic text = COMPULSORY
transaction.deferredAuthorization Boolean = OPTIONAL
transaction.discountAmount Decimal = OPTIONAL
transaction.dutyAmount Decimal = OPTIONAL
transaction.item[n] = OPTIONAL
transaction.item[n].brand String = OPTIONAL
transaction.item[n].category String = OPTIONAL
transaction.item[n].description String = OPTIONAL
transaction.item[n].detail = OPTIONAL
transaction.item[n].detail.acquirerCustom JSON Text = OPTIONAL
transaction.item[n].detail.commodityCode Digits = OPTIONAL
transaction.item[n].detail.tax[n] = OPTIONAL
transaction.item[n].detail.tax[n].amount Decimal = OPTIONAL
transaction.item[n].detail.tax[n].rate Decimal = OPTIONAL
transaction.item[n].detail.tax[n].type String = OPTIONAL
transaction.item[n].detail.unitDiscountRate Decimal = OPTIONAL
transaction.item[n].detail.unitTaxRate Decimal = OPTIONAL
transaction.item[n].detail.unitTaxType String = OPTIONAL
transaction.item[n].detail.unspsc Digits = OPTIONAL
transaction.item[n].detail.upc Digits = OPTIONAL
transaction.item[n].industryCategory Enumeration = OPTIONAL
(order.item.unitPrice + order.item.tax) * order.item.quantity
transaction.item[n].name String = COMPULSORY
transaction.item[n].quantity Decimal = COMPULSORY
transaction.item[n].sku String = OPTIONAL
transaction.item[n].unitDiscountAmount Decimal = OPTIONAL
transaction.item[n].unitOfMeasure String = OPTIONAL
transaction.item[n].unitPrice Decimal = COMPULSORY
transaction.item[n].unitTaxAmount Decimal = OPTIONAL
transaction.itemAmount Decimal = OPTIONAL
transaction.merchantNote String = OPTIONAL
transaction.reference String = OPTIONAL
transaction.resubmission Boolean = OPTIONAL
transaction.shippingAndHandlingAmount Decimal = OPTIONAL
transaction.shippingAndHandlingTaxAmount Decimal = OPTIONAL
transaction.shippingAndHandlingTaxRate Decimal = OPTIONAL
transaction.source Enumeration = OPTIONAL
If you have an existing agreement with the payer that authorizes you to process this payment (for example, a recurring payment) then set this value to MERCHANT.You only need to provide transaction.source if you want to override the default value configured for your acquirer link.
Note:
- You can only override the default value if you have the requisite permission.
- The value you provide must match one of those configured by your payment service provider.
- You can only set the transaction source on the initial transaction on an order. It cannot be changed on subsequent transactions.
transaction.tax[n] = OPTIONAL
transaction.tax[n].amount Decimal = OPTIONAL
transaction.tax[n].rate Decimal = OPTIONAL
transaction.tax[n].type String = OPTIONAL
transaction.taxAmount Decimal = OPTIONAL
transaction.taxStatus Enumeration = OPTIONAL
transaction.id String = COMPULSORY
- Movement of money. For example, payments and refunds.
- Validations. For example, account verification or 3-D Secure authentication of the payer.
- Undoing other transactions. For example, voiding a payment transaction.
- Chargebacks.
- Fees from your payment service provider.
If you attempt an operation and it fails (eg you try to PAY on a card with no funds), then you need a new id for each retry.
Response Parameters
browserPayment = CONDITIONAL
browserPayment.redirectUrl Url = CONDITIONAL
merchant Alphanumeric + additional characters = Always Provided
order = Always Provided
order.amount Decimal = Always Provided
order.creationTime DateTime = Always Provided
order.currency Upper case alphabetic text = Always Provided
order.id String = Always Provided
order.lastUpdatedTime DateTime = Always Provided
order.merchantAmount Decimal = Always Provided
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.
order.totalAuthorizedAmount Decimal = Always Provided
order.totalCapturedAmount Decimal = Always Provided
order.totalDisbursedAmount Decimal = Always Provided
order.totalRefundedAmount Decimal = Always Provided
response = Always Provided
response.gatewayCode Enumeration = Always Provided
result Enumeration = Always Provided
transaction = Always Provided
transaction.amount Decimal = Always Provided
transaction.currency Upper case alphabetic text = Always Provided
transaction.id String = Always Provided
- Movement of money. For example, payments and refunds.
- Validations. For example, account verification or 3-D Secure authentication of the payer.
- Undoing other transactions. For example, voiding a payment transaction.
- Chargebacks.
- Fees from your payment service provider.
If you attempt an operation and it fails (eg you try to PAY on a card with no funds), then you need a new id for each retry.
transaction.type Enumeration = Always Provided
Response parameters are the same as Transaction: Retrieve Transaction