Point of sale webhooks
Your backend receives payment outcomes through this webhook. Required for the POS Integrations API (no polling endpoint available yet).
This webhook is different from eCommerce webhooks.
Setup
Contact support with:
- Your HTTPS webhook URL (Peach Payments only allows ports 80 and 443)
- Optional custom request headers (for example, authentication tokens) - Peach Payments configures these on your endpoint
Point of sale webhooks use plain JSON - you do not need to decrypt them.
Peach Payments configures the webhook at merchant level. One configuration covers all terminals allocated to the merchant.
Delivery
Successful and declined webhooks are triggered immediately. Peach Payments attempts delivery five times, 30 seconds apart. If all attempts fail, Peach Payments moves the event to a dead-letter queue and can manually resubmit it.
webhookId differs between retried deliveries of the same event, so it is not a reliable way to deduplicate. Use the latest webhookTime for a transaction to determine its current status instead. Use transaction.posData.merchantTransactionId to match the event to your order.
Reversals
If the terminal cannot show the Transaction successful screen because of connectivity loss, an app crash, or app closure, the result is unclear on the terminal and Peach Payments does not send a successful webhook.
Peach Payments reverses the payment within five minutes. The customer might still receive a successful payment notification on their phone during this period. Decide whether to wait for the reversal before you attempt a new payment. If no success is confirmed, you can retry the payment.
Refunds
Refund events use the transaction webhook flow. You can use the webhook as the single confirmation path for refund outcomes.
Success criterion
Check transactionType and transactionResult on the webhook transaction payload: transactionType tells you what kind of event this is (sale or refund), and transactionResult tells you the outcome.
transactionType.value | Operation |
|---|---|
0 | Sale (description: "Goods and Services") |
20 | Refund (description: "Refund") |
transactionResult | Outcome |
|---|---|
approved | Still in progress - wait for approved_confirmed |
approved_confirmed | Transaction succeeded |
declined | Transaction declined |
failed | Transaction failed |
voided / reversed | Transaction was cancelled or reversed |
Key fields
| Field | Use |
|---|---|
transactionId | Peach Payments transaction UUID - refunds or voids |
amount | Amount in minor units |
transaction.posData.merchantTransactionId | Your order reference |
transaction.posData.requestId | Reference ID from your POS Integrations API response |
transactionType | {value, description} - 0 is a sale, 20 is a refund |
transactionResult | approved, approved_confirmed, declined, failed, voided, or reversed |
webhookTime | Time of transaction status change, the latest webhookTime reflects the latest status |
terminal.manufacturerSerialNumber | Terminal serial number |
Match webhook events to till orders using merchantTransactionId in transaction.posData.
Updated 5 days ago