Overview of transactions
Spice empowers your POS with support for several types of transactions, all with a consistent interface. This guide covers the basics 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.
- Perform a ping test.
- If Spice is ready ...
- Perform the transaction, e.g. a purchase transaction.
- Else, don't proceed.
- If a
signatureRequired
object is returned ...- Handle the signature workflow.
- Else, if a
Response
object is returned, proceed normally. - If the transaction response contains
success: true
...- Print and/or store the merchant and customer receipts.
- Close the sale on the POS.
- Else, if the transaction response contains
success: false
...- Keep the sale open on the POS.
- Else, if the transaction response is not returned ...
- 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.
- If the transaction response contains a
merchant_receipt
andmerchant_receipt_printed: false
...- Print and/or store the
merchant_receipt
- Print and/or store the
- If the transaction response contains a
customer_receipt
andcustomer_receipt_printed: false
...- Print and/or store the
customer_receipt
- Print and/or store the
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.
Updated 12 months ago