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

# Initiate a payment on a terminal

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

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

## Path parameters

- `id` string, required

## Headers

- `Account` string

## Request body

- object — The request for initiating a payment on a terminal
  - `amounts` object, required
    - `requested` integer — The total amount requested for the purchase. Minimum and maximum amounts [vary by currency](https://developer.ryftpay.com/documentation/overview/core_concepts/currencies).
  - `currency` string, required — The ISO currency code
  - `paymentSession` TerminalPaymentSessionRequest — Use this field to set any relevant properties on the underlying PaymentSession that will be created as part of this request.
    - `platformFee` integer, nullable — The amount (if any) that will be taken and applied to the platform account. This cannot be greater than the "amount" property
    - `metadata` object, nullable
    - `paymentSettings` PaymentSettingsRequest, nullable — Allows for customisation of various payment settings.
      - `paymentMethodOptions` PaymentMethodOptionSettingsRequest, nullable — Use of this field is not enabled by default and subject to approval, please contact our support team if you wish to request it.
        - `disabled` string[] — Use this field to explicitly disable specific options from being used to complete payment. e.g. if you have your own requirements for accepting Amex on only particular transactions. If your customer attempts to pay with a disabled option, the payment session will be updated with `lastError: "payment_method_option_amex_disabled"` You can re-enable a disabled option by removing it from this array.
      - `platform` PaymentPlatformSettingsRequest, nullable — Only applicable to payments under the platform model. Use this field to control various settings relating to payments done under as a platform.
        - `paymentFees` object, nullable — Use this field to control the Ryft account subject to paying a particular fee. Note that this is only permitted for platform payments, i.e. those using the platform fee or split payment transaction models.
          - `interchange` object, nullable — The ID of the Ryft account to deduct any interchange fees from. **Only** applicable for accounts on the `ICC++` pricing model. Specifying this when on `Blended` pricing is not permitted.
            - `bookTo` string — The ID of the Ryft account to book the fee to.
          - `network` object, nullable — The ID of the Ryft account to deduct any network (scheme) fees from. **Only** applicable for accounts on the `ICC++` pricing model. Specifying this when on `Blended` pricing is not permitted.
            - `bookTo` string — The ID of the Ryft account to book the fee to.
          - `miscPassThrough` object, nullable — The ID of the Ryft account to deduct any miscellanous pass-through fees from. **Only** applicable for accounts on the `ICC++` pricing model. Specifying this when on `Blended` pricing is not permitted.
            - `bookTo` string — The ID of the Ryft account to book the fee to.
          - `processor` object, nullable — The ID of the Ryft account to deduct the Ryft processing fee from. **Note** that: - when on `Blended` pricing, this refers to the full blended fee - when on `ICC++` pricing, this refers to the final `+`, i.e. Ryft's markup
            - `bookTo` string — The ID of the Ryft account to book the fee to.
          - `gateway` object, nullable — The ID of the Ryft account to deduct any gateway fees from.
            - `bookTo` string — The ID of the Ryft account to book the fee to.
          - `combined` object, nullable — The ID of the Ryft account to deduct all of the above fees from. Specifying this will take precedence over any of the more granular fields. **Note** that: - when on `Blended` pricing, this will book all of: `processor` & `gateway` fees - when on `ICC++` pricing, this will book all of: `interchange`, `network`, `processor` & `gateway` fees
            - `bookTo` string — The ID of the Ryft account to book the fee to.
      - `threeDs` PaymentThreeDsSettingsRequest, nullable — Allow for customisation of various 3D-secure settings when leveraging Ryft's 3D-secure MPI
        - `challengeIndicator` 'NoPreference' | 'NoChallengeRequested' | 'ChallengeRequested' | 'TransactionRiskAnalysisAlreadyPerformed', nullable — Optional 3DS challenge preference. - `NoPreference`: No explicit challenge preference is requested. - `NoChallengeRequested`: Request a frictionless flow where possible. - `ChallengeRequested`: Request that the issuer performs a challenge. - `TransactionRiskAnalysisAlreadyPerformed`: Indicates TRA has already been performed before authentication which requests an exemption from the issuer If omitted, no explicit preference is requested.
  - `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 payment 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

---

[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)