Supplementary Data

DirectAPI 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 CommWeb 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 CommWeb 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
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 CommWeb 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 and thereby reduce 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:

  • debtRepayment.indicator: Indicate "true" or "false". 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 DirectAPI.
Healthcare purchases must be made using the payer’s Health Benefit card. Currently, the CommWeb 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 CommWeb 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 CommWeb 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. The CommWeb payment gateway currently does not support approvals for a partial amount for healthcare purchases.

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 CommWeb 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 address
  • Merchant name
  • Phone number of the merchant's business

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]

Copyright © 2020 Commonwealth Bank of Australia