# 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](/documentation/get_started/in_person/set_up) 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](/documentation/api/reference/openapi#operation/inPersonTerminalInitPayment) endpoint, providing your terminal's unique ID, the payment amount, currency, and any other required details.

**Example Request**:


```json 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**:


```json 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:


```json 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](/documentation/api/reference/openapi#operation/inPersonTerminalConfirmReceipt) 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`).


Merchant Receipt Printed OK

```json inPersonTerminalConfirmReceipt - Merchant Receipt Example
{
    "merchantCopy": {
        "status": "Succeeded"
    }
}
```

Merchant Receipt Printed Failed

```json inPersonTerminalConfirmReceipt - Merchant Receipt Example
{
    "merchantCopy": {
        "status": "Failed"
    }
}
```

Customer Receipt Printed OK

```json inPersonTerminalConfirmReceipt - Customer Receipt Example
{
    "customerCopy": {
        "status": "Succeeded"
    }
}
```

Customer Receipt Printed Failed

```json inPersonTerminalConfirmReceipt - Customer Receipt Example
{
    "customerCopy": {
        "status": "Failed"
    }
}
```

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](/documentation/get_started/portal) 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](/documentation/get_started/webhooks) section.
- **Refunds**: Additionally, if you need to process refunds for in-person payments, please refer to the [Refund Payments](/documentation/get_started/in_person/refunds) guide for detailed instructions.