Cashout

Introduction

With cashout, a customer can withdraw cash as part of a card transaction. For example, a customer paying for a $20 shirt may also want to withdraw $10 cash. The merchant adds a $10 cashout to the transaction and hands the customer $10 in cash. The merchant receives $30 from the customer's card - $20 for the purchase and $10 for the cashout.

Cashout can be offered as a standalone withdrawal or combined with a purchase.

Limitations

Cashout cannot be used on refunds - this is not permitted by law in many areas
Cashout cannot be used with a credit card - the customer must select a Savings or Cheque account
Cashout and tipping cannot be used in the same transaction

📘
In your POS, the button for initiating a cashout transaction must be separate from the button for making a standard purchase.

Enabling cashout

Cashout must be enabled on the terminal before it can be used. When testing with Gecko Bank, open the MXA Settings app and enable the relevant setting:

For cashout only transactions: enable Cashout
For purchase with cashout transactions: enable Purchase with cashout

Cashout only

A cashout-only transaction lets the customer withdraw cash without making a purchase.

POST /v1/transactions

{
  "cashout_details": {
    "cashout_amount": 5000
  }
}

Field	Required	Description
`cashout_amount`	Yes	Cashout amount in cents
`surcharge_amount`	No	See Tipping & surcharges

Purchase with cashout

The most common cashout method - the customer receives cash as part of an existing purchase transaction.

POST /v1/transactions

{
  "purchase_with_cashout_details": {
    "purchase_amount": 2000,
    "cashout_amount": 1000
  }
}

Field	Required	Description
`purchase_amount`	Yes	Purchase amount in cents
`cashout_amount`	Yes	Cashout amount in cents
`surcharge_amount`	No	See Tipping & surcharges

Terminal-based cashout prompt

When cashout_amount is omitted from the request, the terminal will prompt the customer to enter their desired cashout amount directly on the terminal screen:

POST /v1/transactions

{
  "purchase_with_cashout_details": {
    "purchase_amount": 1337,
    "surcharge_amount": 0
  }
}

Field	Required	Description
`purchase_amount`	Yes	Purchase amount in cents
`cashout_amount`	No	Omit to let the terminal prompt the customer for the cashout amount
`surcharge_amount`	No	See Tipping & surcharges

Polling

Once created, follow the polling loop described in Transactions overview until the transaction reaches FINALISED.

Finalised response

Once status reaches FINALISED, read the following fields:

Field	Values	Description
`result_financial_status`	`APPROVED`, `DECLINED`, `CANCELLED`, `UNKNOWN`	The financial outcome of the transaction
`result_amounts`	object	Final applied amounts in cents - source of truth. Includes `cashout_amount` reflecting the actual cashout dispensed
`merchant_receipt`	string \| null	Merchant receipt data for printing
`customer_receipt`	string \| null	Customer receipt data for printing

UNKNOWN means the outcome could not be determined - handle this via the override flow in Transaction recovery.