How To Use

Getting Started

Start a transaction by Creating a Pay Request.

There are a few things to note when creating a Pay Request:

• The Create a Pay request call will return a Pay Request ID which you should store in the POS against your sale.
• If the Create Pay Request call responds with a 201 status code, the Pay Request has been successfully created and will be attempted to be sent to the terminal.
• Creating a Pay request does not guarantee that the terminal will accept or has accepted the transaction for processing. The terminal may reject the transaction for various reasons such as the terminal being offline.
• Each invoked Pay Request is required to have a supplied UUID in the origin.transactionId field, unique for each sale. The same transaction can be reattempted with the same data and UUID, and notifications of pay request creations that had no response can be obtained by using this reference in scenarios such as a network failure.

Transactions for Payments, Payments with Cashout, Cashout Only and Refunds, work via the same processing flow.

Pay Request Updates

After creating a Pay Request, your server will receive notifications about its processing. Use these notifications to fetch updates to the transaction status in your POS. Please refer to list of various Webhook events.

When you receive a notification for a Pay Request, you can consume its latest data such as status, states and outcomes by calling the Get Pay Request endpoint.

Pay Request Data

A Pay Request has some major components of data that is relative to the transaction which you can use in your POS:

• status - The overall status of the transaction.
• transactionProgress - The current status of the transaction, such as "Pending", "Processing", "Complete".
• terminalProgress - The current state of the terminal, such as "Bad Read" or "Enter Pin".
• pendingDecision - A current question that is being asked on the terminal, such as "Would you like a receipt?".
• transactionOutcome - The details of any transaction that was processed. May be undefined if the transaction was not processed at all.

Answering Terminal Prompts

When the terminal asks a question, such as "Would you like a receipt?", you can answer the question by calling the Answer Terminal Prompt endpoint.

This endpoint is asynchronous and will return a 202 status code if the answer was successfully sent to the terminal.

Cancelling a Pay Request

If you need to cancel a Pay Request, you can do so by calling the Cancel Pay Request endpoint.

Rate Limiting

The Pay Instore API has a rate limit of 1 request per 250ms, per mid+tid combination. This is to prevent an influx of messages inflight to a terminal. If you exceed this rate limit, you will receive a RATE_LIMIT_EXCEEDED error. It is recommended that your integration either banks or debounces requests to avoid this error.

Nuances

There are a few nuances and behaviours due to the nature of the terminal state and the network that you should be aware of:

• A Pay Request may not make it to the terminal if the terminal is offline or the network that the terminal is connected to is down. You can reattempt the same Pay Request multiple times if none of the data has changed.
• Rate limiting aside, it is possible that multiple in-flight transaction requests to the same terminal exist. The terminal will process whichever transaction it receives first. You can monitor which transaction has made it to the terminal by awaiting the notification event "PAY_TERMINAL_REQUEST_INITIALISED".
• Creating, Answering and Cancelling requests are all asynchronous and may take some time to process. It should not be assumed that these api calls have been processed immediately, or at all. Instead, refer to the notification events for the status of the transaction.
• Implementation of the service in your POS should rely on the notification events to update the status of the transaction in your POS. The notification events are the source of truth for the state of the transaction.
• In the event that no notification events are received, you can use the Get Pay Request endpoint to check the status of the transaction, but this should be used sparingly and not as a polling mechanism.