Skip to content
/
Payments
Last updated

Payments

Overview

This section provides detailed instructions on how merchants can process and accept In-Person Payments using their configured payment terminals.

Prerequisites

Before you can start accepting in-person payments, ensure that you have completed your terminal setup by following the steps outlined in the Set-Up Terminal guide.

Once your terminal is properly configured and linked to a location, you will need the terminal's unique identifier (ID) to process payments.

When testing in-person payments in Sandbox, you must open the Test Pax Controller app on the terminal device. This app simulates the payment processing environment and allows you to test transactions without using real payment methods.

Accepting Payments

To connect to and process payments with your terminal, you can use our API.

The first step is to send a request to our initiate payment on a terminal endpoint, providing your terminal's unique ID, the payment amount, currency, and any other required details.

Example Request:

inPersonTerminalInitPayment - Payload Example
{
    "amounts": {
        "requested": 1742  // £17.42 in minor units
    },
    "currency": "GBP"
}

If the payment is for a Sub-Account, make sure you include the Account field in your request headers.

Provided the request is successful, the API will return a payload containing various details about the initiated payment.

Example Response:

inPersonTerminalInitPayment - Response Example
{
    "id": "tml_XXXXXXXXX",
    "name": "Main Desk Terminal",
    "location": {"id": "iploc_XXXXXXXXX"},
    "device": {"type": "A920Pro", "serialNumber": "1853777898"},
    "action": {
        "type": "Transaction",
        "status": "InProgress",
        "id": "tmlact_XXXXXXXXX",
        "transaction": {
            "type": "Payment",
            "paymentSessionId": "ps_XXXXXXXXX",
            "amounts": {"requested": 1742},
            "currency": "GBP",
            "settings": {"receiptPrintingSource": "Terminal"},
        },
        "createdTimestamp": 1761231259,
    },
    "createdTimestamp": 1760456293,
    "lastUpdatedTimestamp": 1761231259,
}

The action object contains important information about the current status of the payment.

We recommend retaining the action.transaction.paymentSessionId value. This corresponds to the payment which is automatically created as part of processing payments on physical terminals.

Provided the request is successful, the terminal will display prompts to the customer to complete the payment, after which the terminal will process the payment.

Receipt Printing

If your terminal supports receipt printing, it will be used to print both the customer and merchant copies.

You can optionally configure the receipt printing settings during payment initiation by including the settings object in your request payload, as shown below:

inPersonTerminalInitPayment - Receipt Printing Example
{
    "amounts": {
        "requested": 1742
    },
    "currency": "GBP",
    "settings": {
        "receiptPrintingSource": "PointOfSale"
    }
}

By default, if no settings object is provided, the terminal will handle receipt printing automatically.

However, in this example, the receiptPrintingSource is set to PointOfSale, which indicates that the terminal should wait for a command from your point-of-sale system to initiate the printing of the receipts.

In this scenario, to inform Ryft of the outcome of the receipt printing process, you will need to send two separate requests to the Confirm Print API endpoint exactly in the following order:

  1. Merchant Receipt Confirmation: First, confirm the printing status of the merchant receipt (either Succeeded or Failed).
  2. Customer Receipt Confirmation: Next, confirm the printing status of the customer receipt (either Succeeded or Failed).
inPersonTerminalConfirmReceipt - Merchant Receipt Example
{
    "merchantCopy": {
        "status": "Succeeded"
    }
}

If either of the receipts fails to print, the transaction on the terminal will be voided and the customer will need to try again.

Next Steps

  • Payment Monitoring: Just as with online payments, you can manage and monitor your in-person payments through the Ryft Portal. You can find more information on how to do this in the Managing Payments section.
  • Webhooks: Also mirroring online payments, you will receive webhooks for in-person payment events. For more details on the available webhooks and how to set them up, please refer to the Webhooks section.
  • Refunds: Additionally, if you need to process refunds for in-person payments, please refer to the Refund Payments guide for detailed instructions.
Previous page
Next page