Purchases

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

Purchase

Response format

FieldTypeDescription
authorizationStringAuthorization number
idStringId of the purchase
card_numberStringThe obfuscated card number
card_holderStringThe name of the card holder
card_expiryString / Date YYYY-MM-DDThe expiry date of the card
card_tokenStringA token representing the saved credit card
card_typeStringSchema of the card
card_categoryStringType of the card: credit or debit
card_subcategoryStringThe subcategory of the card
amountIntegerAmount of the purchase in the smallest unit for the currency e.g. cents
decimal_amountFloatAmount of the purchase as a decimal
successfulBooleanIf the operation was successful or not
messageStringA message giving context to the outcome of the request
referenceStringA unique reference from the switch
currencyString / ISO 4217The currency of the purchase
transaction_idStringA unique reference for each action against a purchase
settlement_dateString / Date YYYY-MM-DDThe date of settlement
transaction_dateString / Date ISO 8601The date the transaction was created
response_codeStringThe response code received from the switch
capturedBooleanWhether the purchase was partly or fully captured
captured_amountIntegerAmount captured in the smallest unit for the currency e.g. cents
rrnStringThe receipt number of the purchase
cvv_matchStringWhether 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_codeIntegerIndicates the result of the AVS check if AVS fields were provided.

Refer to the documentation on AVS for more details.
metadataObjectMetadata of the purchase
addendum_dataObjectAddendum data of the purchase. Described below.
merchant_advice_codeStringAdvice 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 FieldTypeDescription
authorization_tracking_idStringAn 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_numberStringA number indicating the sequence number of the card presented in the transaction
least_cost_routedBooleanIndicates 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.

FieldTypeDescription
cardmember_referenceString. Max length: 20. Alphanumeric and Spaces onlyThe card member's reference number, such as a store order number or customer PO Number
description_1 - description_4String. Max length: 40. Alphanumeric and Spaces onlyThe description for up to four line items. These should be descriptive and avoid generic terms such as 'Merchandise'
quantity_1 - quantity_4Unsigned integer. Maximum value: 999.The quantity of items for the line items
total_1 - total_4Unsigned 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_postcodeString. Max length: 15. Alphanumeric and Spaces onlyThe 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"
      }
}