Skip to main content

Extra Transaction Data

Purchase Data

The Gateway can be sent advanced purchase information with each transaction, where required.

The Gateway provides a number of fields that you can use to store advanced purchase information about the transaction, including details on individual items purchased. These fields are only sent to the Acquirer if needed. The stored data can be obtained by sending a QUERY request.

The details may also be used for advanced purposes, such as displaying shopping cart information on the Masterpass wallet, or PayPal checkout.

American Express Purchases

Purchases using American Express cards will send a subset of this information to the Card Scheme as appropriate.

With American Express, you can provide tax or discount reason (but not both). If taxAmount is provided, then taxReason is used; if discountAmount is provided, then discountReason is used. If both are provided, then taxReason is used.

Only the description, quantity, and amount of the first six line item details are sent to American Express.

Purchase Orders

These fields together with other advanced fields, as detailed in Custom Data, can be used to send full information relating to a purchase order and related invoice indicating types; quantities; and agreed prices for products or services. Details on the supplier; shipping; delivery can also be included.

At present, this information is not sent to the Acquirer, unless needed, but future enhancements to the Gateway may include sending such information as Level 2 or 3 Purchasing data as defined by the relevant Card Schemes.

Purchase Data Request Fields

The following request fields may be sent to provide more information on the breakdown of the purchase amount:

NameMandatoryDescription
grossAmountNoTotal gross amount of sale.
netAmountNoTotal net amount of sale.
taxRateNoTotal tax rate (percentage).
taxAmountNoTotal tax amount of sale.

Amex/Diners require either tax or discount, not both.
taxReasonNoReason for above tax (eg VAT).

Amex/Diners require either tax or discount, not both.
discountAmountNoTotal discount amount of sale.

Amex/Diners require either tax or discount, not both.
discountReasonNoReason for above discount.

Amex/Diners require either tax or discount, not both.
handlingAmountNoHandling costs.
insuranceAmountNoInsurance costs.

The following request fields may be sent to provide more information on the purchased items:

NameMandatoryDescription
itemXXAmountNoAmount for XXth item purchased.
itemXXDescriptionNoDescription of XXth item purchased.
itemXXDescriptionNoQuantity of XXth item purchased.
itemXXGrossAmountNoGross amount for XXth item purchased.
itemXXNetAmountNoNet amount for XXth item purchased.
itemXXTaxAmountNoTax amount for XXth item purchased.
itemXXTaxRateNoTotal tax rate for XXth item purchased.
itemXXTaxReasonNoTax reason for XXth item purchased.
itemXXDiscountAmountNoTotal discount for XXth item purchased.
itemXXDiscountReasonNoDiscount reason for XXth item purchased.
itemXXProductCodeNoProduct code for XXth item purchased.
itemXXProductURLNoShopping cart URL for XXth item purchased.
itemXXCommodityCodeNoCommodity code for XXth item purchased.
itemXXUnitOfMeasureNoUnit of measure for XXth item purchased.
itemXXUnitAmountNoUnit amount for XXth item purchased.
itemXXImageUrlNoImage of XXth item purchased.
itemXXSizeNoSize of XXth item purchased in the format ‘LengthxWidthxHeight Unit’.
itemXXWeightNoWeight of XXth item purchased in the format ‘Weight Unit’.
itemsNoNested line item records (see below).
tip

XX is a number between 1 and 99.

The purchased items can be passed as either individual itemXXField fields; or as a single items field whose value is a sequential array of nested records as described in the format guide.

Both formats cannot be used together. The presence of an items field will cause the Gateway to ignore any individual fields.

The Gateway does not currently support items to be formatted as a serialised array of records.

Note: no attempt is made to check that any gross, net and tax amounts are correct with respect to each other. It is the sender’s responsibility to ensure alternative amount formats are correct.

Line item fields can either be sent ‘flat’ using field names containing the item row number as a sequential number from 1 to 99; or be sent using nested arrays of the form items[XX][field] where XX is the row number from 1 to 99 and field is the field name from the above table without the itemXX prefix and starting with a lowercase first letter. For example, the tax rate for item 5 can be sent either as item5TaxRate; or as items[5][taxRate]. The two formats should not be mixed. If a request field of items is seen, then the ‘flat’ fields are ignored.

Custom Data

You may send arbitrary data with the request by appending extra fields, which will be returned unmodified in the response. These extra fields are merely ‘echoed’ back and not stored by the Gateway.

Caution should be made to ensure that any extra fields do not match any currently documented fields or possible future fields. One way to do this is to prefix the field names with a value unique to you, the Merchant.

If the request contains a field that is also intended as a response field, then any incoming request value will be overwritten by the correct response value.

The Gateway may add new request and response fields at any time and so your integration must take care not to send request fields that may conflict with future Gateway fields and be able to ignore response fields which it doesn’t yet understand.

You can also use the merchantData field to store custom data with the transaction. This stored data can then be retrieved at a later date, using a QUERY request. Complex data can be stored as per the details for nested records as described in the format guide, however the Gateway does not currently support these fields to be provided in the serialised record format. Alternatively, you can serialise the data before storing and unserialise it on retrieval.

Request Fields

NameMandatoryDescription
merchantDataNoArbitrary data to be stored together with this transaction.

Advanced Data

The Gateway provides a number of fields that you can use to store information about the transaction. These fields are only sent to the Acquirer if needed. The stored data can be obtained by sending a QUERY request.

Customer Request Fields

NameMandatoryDescription
customerNameNoCustomer’s name.
customerCompanyNoCustomer’s company (if applicable).
customerAddressNoCustomer’s address.

Mandatory if AVS checking required.
customerPostcodeNoCustomer’s postcode.

Mandatory if AVS checking required.
customerTownNoCustomer’s town/city.
customerCountyNoCustomer’s county/province.
customerCountryCodeNoCustomer’s country.
customerPhoneNoCustomer’s phone number.
customerMobileNoCustomer’s mobile phone number.
customerFaxNoCustomer’s fax number.
customerEmailNoCustomer’s email address.
customerDateOfBirthNoCustomer’s date of birth.
customerOrderRefNoCustomer’s reference for this order (Purchase Order Reference).
customerMerchantRefNoCustomer’s reference for the Merchant.
customerTaxRefNoCustomer’s tax reference number.

Merchant Request Fields

These fields can be used to store details about the Merchant and any relationship between the Merchant and Customer such as any invoice reference.

NameMandatoryDescription
merchantNameNoMerchant’s contact name.
merchantCompanyNoMerchant’s company name.
merchantAddressNoMerchant’s contact address.
merchantTownNoMerchant’s contact town/city.
merchantCountyNoMerchant’s contact county.
merchantPostcodeNoMerchant’s contact postcode.
merchantCountryCodeNoMerchant’s contact country.
merchantPhoneNoMerchant’s phone number.
merchantMobileNoMerchant’s mobile phone number.
merchantFaxNoMerchant’s fax number.
merchantEmailNoMerchant’s email address.
merchantWebsiteNoMerchant’s website. The website must be a fully qualified URL and include at least the scheme and host components.
merchantOrderRefNoMerchant’s reference for this order (Invoice/Sales Reference).
merchantCustomerRefNoMerchant’s reference for the Customer.
merchantTaxRefNoMerchant’s tax reference number.
merchantOriginalOrderRefNoReference to a back order.
merchantCategoryCodeNoScheme assigned Merchant Category Code (MCC).
merchantTypeNoAcquirer assigned Merchant type code.
merchantAccountNoNoMerchant’s bank account number

Supplier Request Fields

These fields can be used to store details about the Supplier. This is where any purchased goods are being supplied by a third-party and not directly from the Merchant.

NameMandatoryDescription
supplierNameNoSupplier’s contact name.
supplierCompanyNoSupplier’s company name.
supplierAddressNoSupplier’s contact address.
supplierTownNoSupplier’s contact town/city.
supplierCountyNoSupplier’s contact county.
supplierPostcodeNoSupplier’s contact postcode.
supplierCountryCodeNoSupplier’s contact country.
supplierPhoneNoSupplier’s phone number.
supplierMobileNoSupplier’s mobile phone number.
supplierFaxNoSupplier’s fax number.
supplierEmailNoSupplier’s email address.
supplierOrderRefNoSupplier’s reference for this order (Invoice/Sales Reference).
supplierAccountNoNoSupplier’s bank account number.

Delivery Request Fields

These fields can be used to store details about the delivery address. This is where any purchased goods are being delivered to if different from the Customer’s address.

NameMandatoryDescription
deliveryNameNoName of person receiving the delivery.
deliveryCompanyNoName of company receiving the delivery.
deliveryAddressNoDelivery address.
deliveryTownNoDelivery town/city.
deliveryCountyNoDelivery county.
deliveryPostcodeNoDelivery postcode.
deliveryCountryCodeNoDelivery country.
deliveryPhoneNoPhone number of delivery location.
deliveryMobileNoMobile phone number of delivery location.
deliveryFaxNoFax number of delivery location.
deliveryEmailNoDelivery email address.

Receiver Request Fields

These fields can be used to store details about the recipient of the purchased goods where different from the Customer’s and Delivery details. It is most commonly used by Financial Institutions (MCC 6012 Merchants) who need to record the primary recipient of a loan.

NameMandatoryDescription
receiverNameNoReceiver’s contact name.
receiverCompanyNoReceiver’s company name.
receiverAddressNoReceiver’s contact address.
receiverCountyNoReceiver’s contact town/city.
receiverPostcodeNoReceiver’s contact postcode.
receiverCountryCodeNoReceiver’s contact country.
receiverPhoneNoReceiver’s phone.
receiverMobileNoReceiver’s mobile phone number.
receiverFaxNoReceiver’s fax number.
receiverEmailNoReceiver’s email address.
receiverAccountNoNoReceiver’s account number.
receiverDateOfBirthNoReceiver’s date of birth.

Shipping Request Fields

NameMandatoryDescription
shippingTrackingRefNoShipping tracking reference.
shippingMethodNoShipping method (eg Courier, Post, etc.).
shippingAmountNoCost of shipping.
shippingGrossAmountNoGross cost of shipping.
shippingNetAmountNoNet cost of shipping.
shippingTaxRateNoTax rate as percentage to 2 decimal places.
shippingTaxAmountNoTax cost of shipping.
shippingTaxReasonNoTax reason (eg VAT).
shippingDiscountAmountNoDiscount on shipping.
shippingDiscountReasonNoReason for discount.

Note: no attempt is made to check that any gross, net and tax amounts are correct with respect to each other. It is the sender’s responsibility to ensure alternative amount formats are correct.

Device Information Fields

These fields can be used to provide details of the device from which the transaction is being made. Although not strictly mandatory, they may be required for fraud checking or 3-D Secure authentication, in which case it is highly recommended that they be provided.

NameMandatoryDescription
deviceTypeNoType of Consumer’s device.

One of the following values: desktop, laptop, tablet, phone, other.
deviceChannelNoCommunications channel used by the Consumer’s device.

One of the following values: browser, app, other.
deviceIdentityNoContent of the HTTP User-Agent header received from the Consumer’s device.

Truncated to 2048 characters maximum.

This field is mandatory for 3-D Secure unless an alternative is provided via the threeDSOptions field.
deviceTimeZoneNoTime zone offset in minutes between UTC and the Consumer’s device. The offset is positive if the local time zone is behind UTC and negative if it is ahead.

This field is mandatory for 3-D Secure unless an alternative is provided via the threeDSOptions field.
deviceCapabilitiesNoComma separated list of capabilities supported by the Consumer’s device.

One or more of the following values: java, javascript.

This field is mandatory for 3-D Secure unless an alternative is provided via the threeDSOptions field.
deviceAcceptContentNoContent of HTTP Accept header received from the Consumer’s device.

Truncated to 2048 characters maximum.

This field is mandatory for 3-D Secure unless an alternative is provided via the threeDSOptions field.
deviceAcceptCharsetNoContent of HTTP Accept-Charset header received from the Consumer’s device.

Truncated to 2048 characters maximum.

This field is mandatory for 3-D Secure unless an alternative is provided via the threeDSOptions field.
deviceAcceptEncodingNoContent of HTTP Accept-Encoding header received from the Consumer’s device.

Truncated to 2048 characters maximum.

This field is mandatory for 3-D Secure unless an alternative is provided via the threeDSOptions field.
deviceAcceptLanguageNoContent of HTTP Accept-Language header received from the Consumer’s device.

Truncated to 2048 characters maximum.

This field is mandatory for 3-D Secure unless an alternative is provided via the threeDSOptions field.
deviceScreenResolutionNoScreen resolution of the Consumer’s device.

Formatted as [HxWxD] where:
• H – screen height in pixels
• W – screen width in pixels
• D – colour depth in bits

Screen height and width must be between 1 and 999999 pixels.

Colour depth must be one of the following values: 1, 4, 8, 15, 16, 24, 32, 48.

This field is mandatory for 3-D Secure unless an alternative is provided via the threeDSOptions field.
deviceOperatingSystemNoOperating system used by the Consumer’s device.

One of the following values: win, unix, linux, macos, ios, android, other.

Acquirer Data

The Gateway supports the passing of Acquirer specific data where needed by an individual Acquirer to provide additional or non-standard features.

When supported, this data can be passed in the acquirerOptions request field, which must be provided using the record or serialised record format detailed in the format guide.

Please contact our customer support team if you need information about what options can be provided to your Acquirer.

The Gateway also supports the returning of Acquirer specific details in the request in situations where the Gateway considers the data to be of value.

When supported, this data will be returned in the acquirerResponseDetails response field, which will be returned using the record format detailed in the format guide.

In addition to this the Gateway will return the original response code and message received from the Acquirer and any transaction referenced provided by the Acquirer. This later reference can help you identify the transaction when you have access to the Acquirers merchant management portal or need to contact them to query a transaction.

The original Acquirer response code may not be numeric and information on these codes will need to be requested from the Acquirer.

The Gateway may support new acquirer options and return new acquirer details at any time and so your integration must be able to handle such changes and not reject unknown fields.

Request Fields

NameMandatoryDescription
acquirerOptionsNoRecord containing Acquirer specific options.

Response Fields

NameMandatoryDescription
acquirerResponseCodeNoResponse code supplied by the Acquirer, maybe prefixed with ‘G:’ if the Acquirer is itself a payment Gateway.
acquirerResponseMessageNoResponse message supplied the Acquirer.
acquirerResponseDetailsNoRecord containing Acquirer specific response details.
acquirerTransactionIDNoTransaction identifier/reference used to identify the transaction in the Acquirer’s system.