Overview of transactions

Introduction

An example of a transaction is when a customer uses their card to pay for a meal. They present their card to the EFTPOS terminal which communicates with the POS (via Spice). If the transaction succeeds, money is transferred between the customer and the merchant.

Spice's API provides endpoints for making purchases, refunds, MOTO transactions, cashout-only transactions, and more.

The transaction interface

In the Spice API, all transaction types have a POST request method for making a transaction and a GET request method for retrieving the status of an existing transaction. E.g. for purchases: POST /v1/purchase and GET /v1/purchase.

Each POST request requires a posRefId to be provided in the body. This is the ID of the transaction and hence it must be unique (e.g. you can use a UUID). Note that when retrying a transaction (i.e. after an 'invalid PIN' or 'signature declined'), a new unique posRefId must be used.

The transaction response can be identified by the Response object which contains many standard fields. It contains a success field indicating whether the transaction succeeded or failed. It also contains the host_response_text field with a more specific status, and failed transactions contain an error_reason status.

{
    "Response": {
        "success": true,
        "host_response_text": "APPROVED",
        ...
    }
}

{
    "Response": {
        "success": false,
        "error_reason": "TRANSACTION_FAILED",
        "error_detail": "Transaction failed",
        "host_response_text": "DECLINED\nDO NOT HONOUR",
        ...
    }
}

The transaction workflow

For your Spice integration to make a transaction, it can use logic similar to the following.

1. Perform a ping test.
2. If Spice is ready ...
   1. Perform the transaction, e.g. a purchase transaction.
3. Else, don't proceed.
4. If a signatureRequired object is returned ...
   1. Handle the signature workflow.
5. Else, if a Response object is returned, proceed normally.
6. If the transaction response contains success: true ...
   1. Print and/or store the merchant and customer receipts.
   2. Close the sale on the POS.
7. Else, if the transaction response contains success: false ...
   1. Keep the sale open on the POS.
8. Else, if the transaction response is not returned ...
   1. Try to recover the transaction.

Printing and storing receipts

If a receipt has been printed by the EFTPOS terminal, this information will be contained in the transaction response so your POS can avoid printing the receipt (since it has already been printed). Your integration should use logic similar to the following.

1. If the transaction response contains a merchant_receipt and merchant_receipt_printed: false ...
   1. Print and/or store the merchant_receipt
2. If the transaction response contains a customer_receipt and customer_receipt_printed: false ...
   1. Print and/or store the customer_receipt

📘

Note:

• We recommend storing the receipts even if the receipt is printed. This will allow the merchant or customer to refer to the transaction at a later time, even if they have lost their printed receipt.
• Looking for more answers? See the frequently asked questions about transactions.