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,
    "suppressMerchantPassword": false
}

Take note of the following fields.

• posRefId — this should be the posRefId of the purchase transaction that was previously made.
• 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.
• suppressMerchantPassword — we recommend for this value to be false. This will require the merchant to enter their password to approve the refund as a protection against theft.

When using Gecko Bank for testing, if suppressMerchantPassword is false, 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.