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
}

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.

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
}

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.

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.