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, best practice is to present this field 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

Metadata Field

Type

Description

authorization_tracking_id

String

An ID returned by the card scheme, best practice is to present this field 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

{
    "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"
      }
}