---
title: "Initiate a refund on a terminal"
method: POST
path: "/in-person/terminals/{id}/refund"
tags: ["In-Person Terminals"]
---

# Initiate a refund on a terminal

`POST /in-person/terminals/{id}/refund`

Initiate a refund on a specific terminal. The cardholder can present their card to complete the refund.

## Path parameters

- `id` string, required

## Headers

- `Account` string

## Request body

- object — The request for initiating a refund on a terminal
  - `paymentSession` object, required
    - `id` string — The ID of the corresponding payment session to be refunded
  - `amount` integer, nullable — The amount to refund in minor digits. Can be omitted, in which case a full refund will be issued.
  - `refundPlatformFee` boolean, nullable — A flag to indicate whether the platform fee should be refunded. If the payment amount is fully refunded, the platform fee will be too. If this is a partial refund then the platform fee will be refunded proportionally to the amount being refunded. By default this flag is false.
  - `settings` TerminalTransactionSettingsRequest, nullable — Allows for various customisation of terminal transactions. If not provided, 'receiptPrintingSource' will default to 'Terminal'
    - `receiptPrintingSource` 'Terminal' | 'PointOfSale' — Identifies the source responsible for receipt printing

## Response `200`

The refund was initiated on the terminal. Note that the result is asynchronous and will be available via webhook events.

- Terminal
  - `id` string — The unique Id of the terminal
  - `name` string — Your name for the terminal. This can be used for display purposes.
  - `location` object — The location where the terminal resides
    - `id` string — The unique location ID
  - `device` TerminalDeviceDetail
    - `type` string — The type of the device
    - `serialNumber` string — The serial number of the device
  - `action` TerminalAction, nullable — The most recent action initiated on the terminal.
    - `type` 'Transaction' — The type of action in progress on the terminal.
    - `status` 'InProgress' | 'Cancelled' | 'Failed' | 'Succeeded' — The status of the action on the terminal
    - `id` string — The unique ID of the action
    - `error` object, nullable
      - `code` string — Identifies the specific reason for the action failing on the device
      - `settings` TerminalActionTransactionSettings — The settings that were used for this transaction on the terminal
        - `receiptPrintingSource` 'Terminal' | 'PointOfSale' — Identifies the source responsible for receipt printing
    - `transaction` object, nullable
      - `type` 'Payment' | 'Refund'
      - `paymentSessionId` string — The unique paymentSessionId corresponding to the payment action on the terminal
      - `amounts` TerminalActionAmounts
        - `requested` integer — The total amount requested for this transaction
      - `currency` string — The ISO currency code
      - `settings` TerminalActionTransactionSettings — The settings that were used for this transaction on the terminal
        - `receiptPrintingSource` 'Terminal' | 'PointOfSale' — Identifies the source responsible for receipt printing
    - `createdTimestamp` integer — The epoch timestamp (seconds) when the action was initiated on the terminal
    - `completedTimestamp` integer, nullable — The epoch timestamp (seconds) when the action was completed on the terminal. This field will be populated once the action reaches a status of `Cancelled`, `Failed` or `Succeeded`.
  - `metadata` object — Your own custom key-value data for this object. These will be sent with any associated events on your webhooks. You can have a maximum of 10 pieces of metadata. Keys must be between 1 and 30 characters in length. Values must be between 1 and 250 characters in length.
  - `createdTimestamp` integer — The epoch timestamp (seconds) when the object was created
  - `lastUpdatedTimestamp` integer — The epoch timestamp (seconds) when the object was last updated

## Other responses

- `400` — One or more inputs are invalid
- `404` — The given resource could not be found
- `500` — An unexpected error occurred when executing this request
- `502` — An unexpected error occurred when communicating with a downstream service external to Ryft

---

[API](https://skmtc.net/ryftpay/apis/ryft-payment-api.md) · [All operations](https://skmtc.net/ryftpay/apis/ryft-payment-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/ryftpay/ryft-payment-api/versions/a042f64d4305/schema)