Use the POS Integrations API when your POS runs on a separate device from the Peach Payments terminal. Your till calls Peach Payments over HTTPS to push the payment to the terminal; the customer pays on the terminal. Your backend receives the outcome via a point of sale webhook.

When to use

Scenario	Pattern
POS on tablet, PC, or phone; terminal at counter	Integrations API
POS app on terminal	App-to-app integration

📘
Ask Peach Payments to enable the POS Integrations API on the terminal.

Get an API key

Contact support to have Peach Payments issue a merchant-scoped API key.

Send it on every request: Authorization: Bearer pk_live_xxx

Environment	Base URL
Sandbox	`https://pos-sandbox.peachpayments.com`
Live	`https://pos.peachpayments.com`

Sale flow

Make sure the terminal app is open, connected to Wifi, and displays Remote payments online.
Your till calls POST /integrations/v1/terminals/{terminalId}/payment-requests with the payment details.
Peach Payments pushes the payment to the terminal and returns 202 (received), 409 (busy), 422 (rejected), 504 (no ack), or 503 (offline).
The customer completes payment on the terminal.
Your backend receives a point of sale webhook with the outcome, matched to your order via merchantTransactionId.
Evaluate success: transactionType.value is 0 and transactionResult is approved_confirmed.

Payment request (sale)

curl --location "https://pos-sandbox.peachpayments.com/integrations/v1/terminals/{terminalId}/payment-requests" \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer pk_live_xxx' \
--data '{
  "amount": 3000,
  "merchantTransactionId": "your_order_id",
  "paymentMethod": "CARD",
  "posData": {"customField": "customValue"}
}'

Field	Required	Description
`amount`	Yes	Amount in minor units (cents)
`merchantTransactionId`	Yes	Your order reference for reconciliation
`paymentMethod`	No	Routing hint, for example `"CARD"`
`posData`	No	Additional custom fields echoed on the transaction and Dashboard

{terminalId} in the URL is the terminal's serial number, for example TJ03P28120090. You can find it at the back of the terminal. It typically starts with PC, TJ, or P3.

Response codes

HTTP status	Meaning	How to handle
`202`	Received - Peach Payments accepted the request and pushed it to the terminal	Wait for the point of sale webhook to learn the outcome
`409`	Busy - the terminal is already processing another transaction	Wait, then retry once the terminal is free
`422`	Rejected - the request was invalid, for example a malformed payload or a terminal not enabled for the POS Integrations API	Fix the request; do not retry unchanged
`503`	Offline - Peach Payments could not reach the terminal	Check the `Remote payments online` chip on the terminal; if it shows online, allow the cashier to push the payment again
`504`	No acknowledgement - the terminal did not confirm receipt in time	Check terminal connectivity; retry if the terminal is online

The response body includes a requestId. Peach Payments echoes the same value back as posData.requestId on every webhook this payment request generates, so you can correlate incoming webhooks to the request that triggered them. A single requestId can produce more than one webhook event, for example if the terminal automatically starts a new transaction attempt after an incorrect PIN.

Webhook setup

The POS Integrations API does not support polling for the result. Your backend must receive a point of sale webhook to learn the outcome. Contact support with your HTTPS URL and optional custom headers.

Reconciliation

Match till orders to payments using merchantTransactionId on the webhook payload.
The Reconciliation API returns the same value in its transactionId field - use it as a fallback if webhook delivery fails. See Terminal integration flows for Dashboard and Reconciliation API options.

Also store the transactionId from the webhook payload against the order once it arrives - you need it to request a refund or void later.

Next steps

Contact support for an Integrations API key.
Configure point of sale webhooks.
Test end-to-end with a UAT terminal - see Test your integration.