Signature transactions

Introduction

Depending on the customer's bank or card, some transactions may require them to sign a receipt. Spice handles this using a workflow that provides a 'receipt to sign' and then prompts the merchant to either accept or reject the transaction after they observe that the customer has signed the receipt.

📘

Note:

• Learn what causes some transactions to require a signature.
• When the merchant chooses to confirm the signature on the EFTPOS terminal, the terminal handles the signature. Therefore, the POS will receive a regular transaction response instead of a 'signature required' response.

Handle a signature workflow

To integrate with Spice's signature workflow, you can use logic similar to the following.

1. If a transaction returns a signatureRequired response ...
   1. Print the receiptToSign
   2. Get the transaction’s status.
   3. If the response contains host_response_text: "SIGNATURE APPROVED" ...
      1. Proceed normally with the successful transaction.
   4. Else, if the response contains host_response_text: "SIGNATURE DECLINED" ...
      1. Proceed normally with the failed transaction.
2. Else, if a Response object is returned (standard transaction response), proceed normally.

To learn more about this logic, see the following sections.

The 'signature required' response

The signatureRequired response contains a receiptToSign string which must be printed.

{
    "signatureRequired": {
        "receiptToSign": "\r\n     Gecko Bank\r\n 1 Example Street ...",
        ...
    }
}

Retrieve the transaction status

When Spice requires a signature for a transaction, its UI presents the merchant with the option to Accept or Reject the transaction. The merchant will accept it once the customer signs the receipt, or reject it otherwise.

Your integration must call the relevant GET request method for the transaction type (e.g. GET /v1/purchase or GET /v1/refund), then wait for the response. The response will be returned once the merchant approves/declines the signature.

Testing

When using Gecko Bank, you can test the signature workflow as follows.

1. Start a transaction, e.g. by calling POST /v1/purchase
2. In Gecko Bank, click Swipe > Credit > click Enter without entering a PIN to trigger the signature workflow.
3. Spice’s Accept/Reject pop-up UI should appear. If instead, Gecko Bank displays the merchant receipt, you must disable the Confirm customer signature on terminal setting in Spice, then retry this test.

Note that since Gecko Bank is a virtual terminal, no receipts will be printed.

📘

Looking for more answers? See the frequently asked questions about the signature workflow.