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

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 is SALE or SALE_WITH_CASHBACK and isApproved == true.

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": "42883193091",
  "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.

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.

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.