API allows you to pass additional data in transactions. It may include industry data relating to airline, healthcare, or data related to the transaction (internet, order, or even custom data). The supplementary data you pass for a transaction is stored on the Mastercard Payment Gateway against that transaction.
Airline data includes details about (a set of) flights, booking reference, itinerary, passenger details, ticket details, etc.
You may specify details on multiple passengers and multiple trip legs associated with the ticket. The numbering for passenger data and trip leg data begins with 0. For example, airline.itinerary.leg[0].<fieldname>. You must use consecutive numbers for the legs and passenger data and must not skip a number or repeat numbers.
Airline data is applicable to Authorize, Pay, Capture, and Refund operations. If you submit airline data on an initial transaction and the same airline data applies to subsequent transactions for the order, you must submit the same airline data on each subsequent transaction.
Internet data includes information on the source of transaction for e-commerce transactions. For example, customer's email, IP address, hostname, etc. This helps the authorization process for Card-Not-Present transactions as the issuer can use it to assess the risk of the transaction.
Internet data is applicable only to Authorize and Pay operations.
Order and line item data includes information about the order and the items contained in the order, which you can provide in the request and choose to display to the payer (via Hosted Checkout or browser payments) before confirming the payment. Certain order and line item data when provided in a transaction may qualify the transaction for better interchange rates with corporate, business, or purchase card cardholders. For more information, see Level II and Level III Data.
order.item[n].brandorder.item[n].categoryorder.item[n].descriptionorder.item[n].nameorder.item[n].quantity
order.item[n].unitPrice, order.item[n].unitTaxAmount, or order.item[n].unitDiscountAmount), and if the decimal places in the computed value exceed the minor units of the payer's currency the gateway will round the total using the "round half to even" algorithm. For example, if 2.555 (quantity) times 3 (unit price) totals 7.665, and if the payer's currency (USD) has 2 minor units, then the rounded item amount will equal 7.66.order.item[n].skuorder.item[n].unitPriceThis amount is multiplied with order.item[n].quantity to compute the total item amount for the line item. If order.itemAmount is provided, then the sum of the total item amount for all the line items MUST equal the value in order.itemAmount.
order.item[n].unitTaxAmountThis amount is multiplied with order.item[n].quantity to compute the total tax amount for the line item. If order.taxAmount is provided, then the sum of the total tax amount for all the line items MUST equal the value in order.taxAmount.
order.item[n].unitDiscountAmountThis amount is multiplied with the order.item[n].quantity to compute the total discount amount for the line item. If order.discount.amount is provided, then the sum of the total discount amount for all the line items MUST equal the value in order.discount.amount.
order.item[n].name, order.item[n].quantity, and order.item[n].unitPrice fields for that item.order.currency (mandatory)order.idorder.descriptionorder.shippingAndHandlingAmountorder.amount (mandatory)If you do not provide this field but provide any of the sub-total amounts (order.itemAmount, order.shippingAndHandlingAmount, order.taxAmount, order.gratuityAmount, order.cashbackAmount) and order.discount.amount then this amount is computed as the sum of the sub-total amounts minus the discount amount. If you provide both this field and any sub-total amounts then the value in this field MUST equal the computed value.
order.itemAmountIf you do not provide this field but provide any line item data, then this amount is computed as the sum of the total item amount (order.item[n].unitPrice x order.item[n].quantity) for all the line items. If you provide both this field and any line item data then the value in this field MUST equal the computed value.
order.taxAmountIf you do not provide this field but provide any line item data, then this amount is computed as the sum of the total tax amount (order.item[n].unitTaxAmount x order.item[n].quantity) for all the line items. If you provide both this field and any line item data then the value in this field MUST equal the computed value.
order.discount.amount
If you do not provide this field but provide any line item data, then this amount is computed as the sum of the total discount amount (order.item[n].unitDiscountAmount x order.item[n].quantity) for all the line items. If you provide both this field and any line item data then the value in this field MUST equal the computed value.
order.gratuityAmount: The amount the payer has chosen to provide as a gratuity or tip in addition to the amount they are paying for the goods or services they are purchasing from you. The gratuity amount is included in the total amount of the order you provide in order.amount.order.cashbackAmount: The amount the payer has chosen to receive as cash in addition to the amount they are paying for the goods or services they are purchasing from you. The cash back amount is included in the total amount of the order you provide in order.amount.Order and line item data is applicable to Authorize, Pay, Initiate Browser Payment, Confirm Browser Payment, Open Wallet, and Hosted Checkout requests.
order.cashbackAmount and order.gratuityAmount are only applicable to Authorize and Pay requests.
Acquirer custom data includes any additional information requested by the acquirer, which cannot be passed using other available data fields. The custom data is stored in the database, which may be used in creating reports external to the Mastercard Payment Gateway. This field must not contain sensitive data.
Acquirer custom data is applicable to Authorize, Capture, Pay, Refund, and Void operations.
Risk custom data includes any additional information requested by third-party risk assessment providers which cannot be passed using other available data fields. The names of the risk custom fields must be entered as agreed with your third-party risk assessment provider. Risk custom data fields are returned in the response and can be used for reporting and analysis purposes as required. Sensitive data must not be included in any of the risk custom data fields.
Risk custom data is applicable to Authorize, Capture, Pay, Verify operations.
Merchant custom data includes any additional information of interest to you which cannot be passed using other available data fields. For example you can pass merchant custom data relating to a sales region by using order.custom.salesRegion, where 'salesRegion' can be any field defined by you. Custom data fields are returned in the response and can be used for reporting and analysis purposes as required.
This data is not needed by the Mastercard Payment Gateway or the acquirer to process the transaction and you must not include sensitive data in any of the merchant custom data fields.
Merchant custom data is applicable to Authorize, Capture, Pay, Refund, Void, Verify, Referral, Update Authorization, Initiate Browser Payment, Confirm Browser Payment and Hosted Checkout operations.
You can submit debt transactions to the gateway if your payment service provider has enabled you for debt repayments for at least one funding method (CREDIT, DEBIT, or CHARGE). Where the gateway is unable determine the funding method for a debt repayment transaction, the transaction will be rejected.
When submitting a debt repayment transaction to the gateway you must provide a debt indicator and may have to provide additional information about the payment recipient. Payment Recipient data includes additional information about the person receiving the funds. This data may be submitted to the acquirer and is used to assess payment risk thereby reducing fraudulent transactions.
In addition to the standard fields for a Verify, Authorize, or Pay transaction, provide the following fields to initiate a debt repayment transaction:
order.purchaseType: Set this field to DEBT_REPAYMENT. This field is mandatory.debtRepayment.paymentRecipient.accountIdentifierdebtRepayment.paymentRecipient.dateOfBirthdebtRepayment.paymentRecipient.lastNamedebtRepayment.paymentRecipient.postcodeZipThe submitted data is returned in the transaction response — date of birth and account identifier will be masked.
You can provide healthcare data as line item data for an order. Healthcare data includes item details for healthcare purchases such as approved vision, dental, prescription, or other (clinic-related purchases). You must provide this data only if it applies to you, and is accepted by your acquirer.
If you are required to submit healthcare data, you must provide all of the following information about the healthcare item in the transaction.
The Mastercard Payment Gateway sends the sum of the amounts for all the line items having the same industry category, to the acquirer. The amount of a line item is:
(Item Unit Price + Item Unit Tax Amount) * Item Quantity. Only one record for each industry category will be sent to the acquirer.
The sum of all the industry category values will be sent as the item amount for the order. If the order amount differs from the item amount, the transaction will decline.
Healthcare data can be submitted in Authorize, Pay, Capture, and Refund transactions.
Statement Descriptor data (also known as dynamic descriptor data) includes contact information provided by you for printing on payer’s account statements. This data is submitted to the acquirer, and it overrides the descriptor data registered at the acquirer. If you provide partial statement descriptor data on a transaction, the acquirer will complete the statement data using the descriptor data as registered at the acquirer.
If you are required to submit Statement Descriptor data, you can provide the following contact information about your business in the transaction.
The submitted data is returned in the transaction response.
Statement Descriptor data can be submitted in Authorize, Pay, Capture, Refund, Verify, Update Session, and Pay with Session operations only.
Cruise data includes information about the cruise, passengers on the cruise, and may also include data relating to other industries such as airline or car hire if they have been purchased as part of a cruise package.
If you are required to submit cruise data, you can provide the following information about the cruise in the transaction.
cruise.bookingReferencecruise.company.address.* fieldscruise.company.contact.customerServicePhonecruise.company.contact.companyPhonecruise.travelAgentCodecruise.travelAgentNamecruise.travelPackageItemscruise.departureDatecruise.returnDatecruise.shipNamecruise.passenger[n].* fieldsCruise data can be submitted in Authorize, Pay, Capture, Refund, Create Checkout Session, and Update Session operations.
The submitted data is returned in the transaction response.
If you are a merchant who submits transactions that involve the purchase of cryptocurrencies or high-risk securities, you must inform the issuer by providing certain indicators in your transaction request to the gateway.
In addition to the standard fields for a Verify, Authorize, Pay transaction, provide the order.purchaseType field to indicate a high-risk securities or a cryptocurrency transaction. You can set the field to either of the following values:
CRYPTOCURRENCY: If you are a merchant with MCC 6051 (Quasi Cash—Merchant or Non-Financial Institutions–Foreign Currency, Non-Fiat Currency) and this transaction is for the purchase of cryptocurrency.HIGH_RISK_SECURITIES: If you are a merchant with MCC 6211 (Securities – Brokers/Dealers) and this transaction is for the purchase of high-risk securities.High-Risk Securities and Cryptocurrency Indicator Data API Reference[REST][NVP]
Transactions that involve debiting money from one account to credit another account are termed as account funding transactions in Mastercard Payment Gateway parlance. The recipient may be the same person, another person, or an organization. If you are enabled by your Merchant Service Organization (MSO) for this functionality, you can facilitate the following account funding transaction types for your customers:
Account Funding Transaction(AFT) data includes information about the sender type, recipient type, recipient account type, account funding method, and funding purpose. It may also include other recipient details. When you are required to submit account funding transaction data, depending upon the type of transaction you are submitting, you must provide some or all of the following information about the transaction.
accountFunding.senderType:This field can take values as PERSON, COMMERCIAL_ORGANIZATION, NON_PROFIT_ORGANIZATION, and GOVERNMENT.accountFunding.senderIsRecipient: Defines if the sender and recipient in the account funding transaction are same or different.accountFunding.recipient.account.fundingMethod: This field can take values as CHARGE, CREDIT, and DEBIT. If no value is provided, this field takes the default value, UNKNOWN.accountFunding.recipient.stateProvinceCode: The state or province code of the recipient. The value must match the second part of the ISO 3166-2 code. For example,
accountFunding.recipient.account: Details about the account of recipient who will subsequently receive the funds that you debit from the sender in this transaction.accountFunding.purpose: This field can take values as CRYPTOCURRENCY_PURCHASE, MERCHANT_SETTLEMENT, and PAYROLL. If no value is provided, takes the default value, OTHER.accountFunding.recipient: Details about the recipient who will receive the funds.accountFunding.recipient.account.identifierType: This field can take values as CARD_NUMBER, BANK_ACCOUNT_NATIONAL, BANK_ACCOUNT_BIC, BANK_ACCOUNT_IBAN, EMAIL_ADDRESS, PHONE_NUMBER, SOCIAL_NETWORK_PROFILE_ID, and STAGED_WALLET_USER_ID. If no value is provided, takes the default value, OTHER.accountFunding.recipient.account.identifier: The payment recipient's account identifier, for example, card number or bank account number.accountFunding.recipient.firstName: Payment recipient's first name.accountFunding.recipient.lastName: Payment recipient's last name.accountFunding.recipient.country: Payment recipient's country.accountFunding.recipient.postCodeZip: Post code or zip code of the payment recipient.accountFunding.recipient.dateOfBirth: Date of birth of the payment recipient in yyyy-mm-dd format.accountFunding.reference: Reference for the account funding transaction. This reference is generated by Mastercard Payment Gateway.Account Funding Transactions data can be submitted in Authorize, Pay, Verify, Standalone capture, Standalone refund, Authenticate_Payer, Authorize, Capture, Refund, Create_Checkout_Session, and Update Session operations. The submitted data is returned in the transaction response.
Copyright © 2022 Mastercard