Purchases

A purchase represents a capture, authorization or void against a payment method.

Purchase

Response format

Field	Type	Description
authorization	String	Authorization number
id	String	Id of the purchase
card_number	String	The obfuscated card number
card_holder	String	The name of the card holder
card_expiry	String / Date YYYY-MM-DD	The expiry date of the card
card_token	String	A token representing the saved credit card
card_type	String	Scheme of the card
card_category	String	Type of the card: credit or debit
card_subcategory	String	The subcategory of the card
amount	Integer	Amount of the purchase in the smallest unit for the currency e.g. cents
decimal_amount	Float	Amount of the purchase as a decimal
successful	Boolean	If the operation was successful or not
message	String	A message giving context to the outcome of the request
reference	String	A unique reference from the switch
currency	String / ISO 4217	The currency of the purchase
transaction_id	String	A unique reference for each action against a purchase
settlement_date	String / Date YYYY-MM-DD	The date of settlement
transaction_date	String / Date ISO 8601	The date the transaction was created
response_code	String	The response code received from the switch
captured	Boolean	Whether the purchase was partly or fully captured
captured_amount	Integer	Amount captured in the smallest unit for the currency e.g. cents
rrn	String	The receipt number of the purchase
cvv_match	String	Whether the CVV match status from the issuer. Possible values are: M - Matched Y - Matched N - Not Matched P - Not Processed S - Suspicious U - Unknown (response from network unclear) Merchants should use this to determine whether they are comfortable processing risky transactions.
avs_result_code	Integer	Indicates the result of the AVS check if AVS fields were provided. Refer to the documentation on AVS for more details.
metadata	Object	Metadata of the purchase
addendum_data	Object	Addendum data of the purchase. Described below.
merchant_advice_code	String	Advice code for how merchants should retry failed transactions. Only present when a transaction is declined. Details on the possible codes are documented Merchant Advice Codes (Retries)

Metadata

Some switching paths and acquirers will return additional data that can be found in the metadata field of a purchase response. This includes:

Metadata Field	Type	Description
authorization_tracking_id	String	An ID returned by the card scheme that is required to be presented on subsequent recurring or instalment transactions. Note that if this is not provided in any wallet transactions, the transaction will be rejected. For example Apple Pay recurring or installment transactions.
card_sequence_number	String	A number indicating the sequence number of the card presented in the transaction
least_cost_routed	Boolean	Indicates if the transaction was least cost routed via the Debit network. Only applicable to transactions using a dual branded card and routed via specific switches. Please note that this field may return one of three values: - true: the transaction was least cost routed - false: the switch used supports least cost routing, but the transaction was not eligible for least cost routing - Key not present: the switch used does not support least cost routing

Addendum Data

For some switching paths and acquirers it may be possible to include addendum data which is passed onto the card issuer - this is primarily used for corporate purchasing cards, American Express cards etc.

To include this data with your transactions the field addendum_data should be added to the request payload with the appropriate data payload for the transaction type included - these different payload types are detailed below.

If addendum data was presented with the original transaction (such as for a pre-auth) the data will be merged, with the most recent data overwriting the older data.

Corporate Purchasing Level 2 Data

Level 2 data for corporate purchase cards may be included which can detail the order reference, purchase order numbers, line item details etc.

Field	Type	Description
cardmember_reference	String. Max length: 20. Alphanumeric and Spaces only	The card member's reference number, such as a store order number or customer PO Number
description_1 - description_4	String. Max length: 40. Alphanumeric and Spaces only	The description for up to four line items. These should be descriptive and avoid generic terms such as 'Merchandise'
quantity_1 - quantity_4	Unsigned integer. Maximum value: 999.	The quantity of items for the line items
total_1 - total_4	Unsigned integer. Maximum value: 99999.	The total for the line item as a whole number in the smallest unit (e.g. $155.60 will be 15560)
shipping_postcode	String. Max length: 15. Alphanumeric and Spaces only	The post code for the shipping address

Example

JSON

{
    "corp_l2": {
        "cardmember_reference": "ORD 123456 PO 08789",
        "description_1": "Box of paper",
        "quantity_1": 5,
        "total_1": 5000,
        "description_2": "Pencils",
        "quantity_2": 10,
        "total_2": 1000,         
        "description_3": "Pens",
        "quantity_3": 10,
        "total_3": 1500,
        "description_4": "White Out",
        "quantity_4": 1,
        "total_4": 500,
        "shipping_postcode": "EC1A 1AA"
      }
}