Purchases and refunds

Purchases

An example of a purchase is when a customer buys a candle from a candle shop and pays for it using their card.

To make a purchase, use the POST /v1/purchase endpoint. For a simple purchase, try using the following request body.

{
    "posRefId": "aa2bc19f-c546-421c-sa82-2294fc25a13e",
    "purchaseAmount": 1000,
    "promptForCashout": false,
    "posId": "T1" // Only required when using multiple terminals, such as for Pay at Table; a unique 		                      string that identifies the paired EFTPOS terminal
}

Take note of the following fields.

• posRefId — this must be a unique string. Usually, spaces and special characters are not used.
• purchaseAmount — this amount is specified in cents, so 1000 means $10.
• posId— this unique string identifies the paired EFTPOS terminal. Recommended when using multiple terminals.

When using Gecko Bank for testing, it will ask you to select the method of card entry: Tap, Insert, or Swipe. Then, enter a PIN if necessary, and it will approve the transaction. It doesn't ask you to present a card since it is a virtual terminal, and this makes testing easier since no test card is needed.

📘

Note:

• View the details of a purchase and previous purchases on the Transactions page of the UI.
• Tips and surcharges can be added to purchases.
• This endpoint is also used for making cashout-only transactions.

Refunds

An example of a refund is when a customer purchases a candle but then decides to return it to the candle shop a week later. The candle shop returns the money to the customer’s card.

To give a refund, use the POST /v1/refund endpoint. For a simple refund, try using the following request body.

{
    "posRefId": "aa2bc19f-c546-421c-sa82-2294fc25a13e",
    "refundAmount": 1000,
    "posId": "T1" // Only required when using multiple terminals, such as for Pay at Table; a unique 		                      string that identifies the paired EFTPOS terminal
}

Take note of the following fields.

• posRefId — this should be a unique string to initiate the Refund transaction.
• refundAmount — for a full refund, use the same amount as that of the purchase, or for a partial refund, use a lesser amount. It is also possible to use a greater amount.
• posId— this unique string identifies the paired EFTPOS terminal. Recommended when using multiple terminals.

When using Gecko Bank for testing, it will first ask you to authenticate by entering the Manager passcode. After this, select the card entry method (as with a purchase transaction), then enter a PIN and the refund will be approved.

📘

Note:

• View the details of a refund and previous refunds on the Transactions page of the UI.
• In your POS, there must be a button for making a purchase and a separate button for making a refund. This makes your POS quick and easy to use, especially by merchants in fast-paced environments.