Supplementary Data

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.

Contact your payment service provider to check if providing such data is supported for your acquirer. The transaction operations that support the data, and the mandatory data fields required to process the transaction depend on your acquirer.
Airline Data

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.

Airline Data API Reference [REST][NVP]

Customer's Internet Data

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.

Internet Data API Reference [REST][NVP]

Order and Line Item Data

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].brand
  • order.item[n].category
  • order.item[n].description
  • order.item[n].name
  • order.item[n].quantity
    When a decimal quantity is multiplied by amounts (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.
    Ensure you apply this rounding when you provide these amount fields in the request.
  • order.item[n].sku
  • order.item[n].unitPrice

    This 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].unitTaxAmount

    This 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].unitDiscountAmount

    This 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.

All line item data is optional; however, if you provide any line item data on a request, then you MUST provide at least order.item[n].name, order.item[n].quantity, and order.item[n].unitPrice fields for that item.
  • order.currency (mandatory)
  • order.id
  • order.description
  • order.shippingAndHandlingAmount
  • order.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.itemAmount

    If 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.taxAmount

    If 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.

Order Data API Reference [REST][NVP]

Line Item Data API Reference [REST][NVP]

Acquirer Custom Data

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.

Acquirer Custom Data API Reference [REST][NVP]

Level II and Level III Data

See Level II and Level III Data.

Risk Custom Data

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.

Acquirer Custom Data API Reference [REST][NVP]

Merchant Custom Data

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.

Merchant Custom Data API Reference [REST][NVP]

Debt Repayment Data

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.

Debt repayment data only applies to merchants with Merchant Category Code 6012 (Financial Institutions – Merchandise and Services) or 6051 (Non-Financial Institutions – Foreign Currency, Non-Fiat Currency) processing Visa card transactions. You must supply this data to comply with Visa merchant regulations.

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.accountIdentifier
  • debtRepayment.paymentRecipient.dateOfBirth
  • debtRepayment.paymentRecipient.lastName
  • debtRepayment.paymentRecipient.postcodeZip

The submitted data is returned in the transaction response — date of birth and account identifier will be masked.

Debt Repayment Indicator API Reference[REST][NVP]

Healthcare Data

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.

Healthcare data is supported from version 36 of the API.
Healthcare purchases must be made using the payer’s Health Benefit card. Currently, the Mastercard Payment Gateway only processes US Healthcare data using IIAS (Inventory Information Approval System). Based on your acquirer, a healthcare-specific Merchant Category Code (MCC) may need to be configured on your merchant acquirer link with the Mastercard Payment Gateway. For more details, please contact your payment service provider.

If you are required to submit healthcare data, you must provide all of the following information about the healthcare item in the transaction.

  • Industry category: Supported industry categories are: HEALTHCARE_VISION, HEALTHCARE_DENTAL, HEALTHCARE_PRESCRIPTION, or HEALTHCARE_OTHER.
  • Category (optional): The sub-category for the industry category. For example, prescription glasses for HEALTHCARE_VISION
  • Item Name
  • Item Unit price
  • Item Quantity
  • Item Unit Tax Amount

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.

Healthcare Data API Reference[REST][NVP]

Statement Descriptor Data

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.

As a prerequisite, your merchant profile on the Mastercard Payment Gateway must be enabled for the "Statement Descriptor" privilege .

If you are required to submit Statement Descriptor data, you can provide the following contact information about your business in the transaction.

  • Merchant full address
  • Merchant name
  • Phone number of the merchant's business
For merchant and sub-merchant transactions with US as the country code, you must provide the full address and a valid state code. If not, you will be prompted with an error message.

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.

Statement Descriptor Data API Reference[REST][NVP]

Cruise Data

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.bookingReference
  • cruise.company.address.* fields
  • cruise.company.contact.customerServicePhone
  • cruise.company.contact.companyPhone
  • cruise.travelAgentCode
  • cruise.travelAgentName
  • cruise.travelPackageItems
  • cruise.departureDate
  • cruise.returnDate
  • cruise.shipName
  • cruise.passenger[n].* fields

Cruise 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.

Cruise Data API Reference[REST][NVP]

High-Risk Securities and Cryptocurrency Indicator Data

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.

High-risk securities indicator only applies to merchants with Merchant Category Code (MCC) 6211 (Securities—Brokers/Dealers) processing Mastercard or Maestro card transactions.

Cryptocurrency indicator only applies to merchants with Merchant Category Code (MCC) 6051(Quasi Cash—Merchant or Non-Financial Institutions – Foreign Currency, Non-Fiat Currency) processing Mastercard, Maestro or Visa card transactions. High-risk securities indicator only applies to merchants with MCC 6211 (Securities—Brokers/Dealers) processing MasterCard or Maestro transactions.

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]

Account Funding Transactions
This section is applicable only for Mastercard. For Visa, it will be provided in a future release.

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:

  • Person to Person
  • Intra-organizational funds transfers
  • Inter-organizational funds transfers
For merchants processing Mastercard card transactions, the Mastercard MoneySend and Funding Transactions Program applies only to the merchants with specific Merchant Category Codes (MCC). These codes are:
  • 6540 (funding transaction)
  • 4829 (Money transfer), and
  • 6538 (Funding Transactions for MoneySend).

The following MCCs can only only be used for processing code 00 or 20:
  • 6538 (Funding Transactions for MoneySend)
  • 6540 (funding transaction), and
  • 4829 (Money Transfer).

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. If no value is provided, this field takes the default value as FALSE.
  • 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,
    • For an address in the United States, provide the 2-letter ISO 3166-2 state code.
    • For the US military bases, provide one of AE, AA, or AP codes.
    • For an address in Canada, provide the 2-letter ISO 3166-2 province code.
  • 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, Authenticate_Payer, Capture, Create_Checkout_Session, Pay, Refund, Standalone capture, Standalone refund, Update Session operations, and Verify. The submitted data is returned in the transaction response.

Account Funding Transactions Data API Reference[REST][NVP]

If the AFT transaction is processed through the gateway, you must submit the transaction with order.purchaseType=ACCOUNT_FUNDING.
MCC selection for MoneySend

Select the appropriate MCC for the Transaction Type Indicator if the originating institution is registered for the Mastercard MoneySend service and submits the Authorization Request message for funding transactions and funding transaction refunds. For more information, see the Quick Reference Booklet on MC Connect > Technical Resource Center (TRC) or contact your acquiring bank to obtain the recommended MCCs for different transaction types.

Account Funding Transaction integration

Send the correct Transaction Type Indicator while integrating with Account Funding Transactions by ensuring the appropriate MCC and the correct request field in the API. The MSO has enabled you to submit account funding transactions and configured which types of account funding transactions you are allowed to submit. For more information about the MCC, request fields, and MSO configuration, see the MPGS integration documentation or contact MPGS support for further assistance.

This table describes the MCCs for funding transaction initiated by customers.

Transaction Type Identifier

MCC 4829 - Money Transfer

MCC 6540 - Funding Transactions

MCC 6538 - Funding Transactions for MoneySend

General person to person transfer

Valid for F07

Valid for F07

Valid for C07

Person to person transfer to card account

Valid for F08

Valid for F08

-

This table describes the MCCs for transfers initiated by customers or organizations.

Transaction Type Identifier

MCC 4829 - Money Transfer

MCC 6540 - Funding Transactions

MCC 6538 - Funding Transactions for MoneySend

Transfer to own debit or prepaid account

Valid for F64

Valid for F64

-

Payment of own credit card bill

Valid for F54

Valid for F54

Valid for C54

Transfer to own staged Digital Wallet Account

Valid for F61

Valid for F61

-

General transfer to own account

Valid for F52

Valid for F52

Valid for C52

General transfer to own account initiated by organizations

Valid for F52

Valid for F52

Valid for C52

Transfer to own staged Digital Wallet Account initiated by organizations

Valid for F61

Valid for F61

-

Transfer to own debit or prepaid card account initiated by organizations

Valid for F64

Valid for F64

-

Payment of own credit card bill initiated by organizations

Valid for F54

Valid for F54

-

Business disbursement

Valid for F55

Valid for F55

Valid for C55

Government/ non-profit disbursement

-

-

Valid for C56

Rapid merchant settlement

-

-

Valid for C57

General business to business transfer

Valid for F65

Valid for F65

Valid for C65

Copyright © 2023 Mastercard