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

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