Supplementary Data

Web Services Integration 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 Tyro eCommerce 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.

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 Tyro eCommerce 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 Tyro eCommerce 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]

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 Web Services Integration.

Healthcare purchases must be made using the payer’s Health Benefit card. Currently, the Tyro eCommerce 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 Tyro eCommerce 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 Tyro eCommerce 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 Tyro eCommerce 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]

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 Tyro eCommerce 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 C07

Person to person transfer to card account

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