Purchase, refund and signature transactions

All transaction types are created using the same endpoint:

POST /v1/transactions

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

Purchase

POST /v1/transactions

{
  "purchase_details": {
    "purchase_amount": 1000,
    "tip_amount": 100,
    "surcharge_amount": 50
  }
}

Refund

{
  "refund_details": {
    "refund_amount": 1000
  }
}

When calculating a refund amount that includes a surcharge, use result_amounts.surcharge_amount from the original transaction - not the amount from your request.

Finalised response

Once status reaches FINALISED, read the following fields:

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

Signature transactions

Some transactions require the customer to sign a receipt, depending on their card or bank. When this occurs, SCI pauses the transaction in an AWAITING_POS state and the Action Framework instructs the POS on what to display and what actions are available.

There are three implementation options. The right choice depends on the UX you want for your merchants.

Option 1 - Auto-print (recommended default)

Set pos_auto_print_signature_receipt: true in the transaction request.

When a signature is required, the API returns PRINT_MERCHANT_RECEIPT in auto_actions. Your POS immediately prints the merchant receipt for the customer to sign. The Action Framework then renders Approve and Decline buttons for the merchant to confirm the signature.

This is the recommended default — most merchants prefer the receipt to print automatically without an extra step.

Option 2 - Manual print

Set pos_auto_print_signature_receipt: false or omit it.

When a signature is required, the Action Framework renders a Print Merchant Receipt button. The merchant clicks it to print the receipt, then clicks Approve or Decline once the customer has signed.

Option 3 - Configurable toggle (recommended implementation)

Expose a setting in your POS that lets the merchant toggle between Option 1 and Option 2. The default state of the toggle should be ON (Option 1).

This provides the most flexibility and is the recommended approach for most integrations.

EFTPOS signature flow

Some terminals support handling signature verification entirely on the terminal rather than the POS. To enable this, set verify_signature_on_terminal: true in the transaction request.

When a signature is required, the terminal automatically prints the receipt and presents Approve / Decline on the terminal screen. The POS receives a "Waiting for signature verification on terminal" message and continues polling until the transaction is finalised - no Action Framework interaction is required from the POS.

You can also expose this as a toggle in your POS settings, allowing the merchant to choose whether signature verification happens on the POS or the terminal, noting that signature verification is mandatory for implementation.

Error reference