Optional backend confirmation alongside Intent API callbacks. Required for till-point QR integrations (no Intent callback on the till).

📘
This webhook is different from eCommerce webhooks.

When to use

Pattern	Webhook
App-to-app (Intent API)	Optional - Intent callback is primary; webhook for server-side reconciliation
Till-point QR	Required - till receives outcome via webhook

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.

Use webhookId to deduplicate deliveries. 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

Apply the same logic as the Intent API response: check transactionType and isApproved on the webhook transaction payload.

Operation	Success
Sale	`transactionType` is `SALE` or `SALE_WITH_CASHBACK` and `isApproved == true`
Refund	`transactionType == REFUND` and `isApproved == true`
Void	Use void-specific fields on the payload (no `isApproved`)

Do not rely on transactionResult alone - always evaluate isApproved together with transactionType.

Key fields

Field	Use
`transactionId`	Peach Payments transaction UUID - refunds or voids
`amount`	Amount in minor units
`transaction.posData.merchantTransactionId`	Your order reference
`transactionType`	`SALE`, `REFUND`, and so on
`isApproved`	`true` / `false`

Match webhook events to till orders using merchantTransactionId in transaction.posData.

Payload fields

Fields that do not apply to a transaction can be absent.

Webhook envelope

Field	Description
`webhookId`	Unique webhook delivery UUID. Use this value to deduplicate deliveries.
`webhookType`	Webhook type. Transaction and refund events use `transaction`.
`webhookTime`	Date and time that Peach Payments creates the webhook, in ISO 8601.
`terminal`	Terminal details.
`network`	Terminal network details.
`routing`	Acquiring route details.
`reversalFailureReason`	Reason that a reversal failed, when applicable.
`transaction`	Transaction or refund result.

`terminal`

Field	Description
`id`	Peach Payments terminal UUID.
`manufacturerSerialNumber`	Terminal serial number issued by the manufacturer.
`externalSerialNumber`	External terminal serial number.
`manufacturer`	Terminal manufacturer.
`model`	Terminal model.
`firmwareVersions`	Map of terminal firmware names and versions.
`batteryPercent`	Terminal battery percentage.
`location.latitude`	Terminal latitude, when available.
`location.longitude`	Terminal longitude, when available.

`network` and `routing`

Field	Description
`network.type`	Network type, such as Wifi or mobile data.
`network.name`	Network name.
`network.signalStrength`	Network signal strength.
`network.networkLatency`	Measured network latency, when available.
`routing.route`	Acquiring route.
`routing.tenantPaymentMethodRouteId`	Tenant payment method route UUID.
`routing.config`	Route-specific configuration.

`transaction`

Field	Description
`transactionId`	Peach Payments transaction UUID.
`originalTransactionId`	Original transaction UUID for linked transactions.
`transactionResult`	Processing result, such as `approved_confirmed`, `declined`, or `reversed`.
`errorMessage`	Error description for a failed or declined transaction.
`cardNotPresentRefundableStatus`	`refundable`, `not_refundable`, or `unknown`.
`transactionType`	Transaction operation type.
`responseCode`	Transaction response code details.
`cardTransactionData`	Card transaction, amount, merchant, and card details.
`voidableUntilTime`	Last time that a void can be accepted, in UTC.
`transactionTime`	Time Peach Payments receives the transaction, in UTC.
`posData`	Merchant metadata, including `merchantTransactionId`.
`paymentMethod`	Payment method, such as `card`.
`softPosPinToken`	Token used when a SoftPOS PIN prompt is required.
`refundBalanceData`	Original amount, remaining balance, and refund history for refunds.

`transaction.cardTransactionData`

Field	Description
`rrn`	Retrieval Reference Number sent to the acquirer.
`transactionLinkId`	Mastercard lifecycle-linking identifier, when available.
`traceId`	Transaction trace identifier.
`stan`	System Trace Audit Number sent to the acquirer.
`settlementDate`	Expected settlement date in `yyyy-MM-dd` format.
`merchant`	Merchant name, city, and country code for the transaction.
`amount`	Amount details.
`card`	Card details.
`mid`	Acquirer merchant identifier.
`tid`	Acquirer terminal identifier.
`approvalCode`	Approval code issued by the authorising institution.
`cryptogram`	EMV response cryptogram.
`issuerTerminalData`	Issuer response data returned to the terminal.

`transaction.cardTransactionData.amount`

Field	Description
`amount`	Total amount in minor units.
`currencyCode`	ISO 4217 currency code.
`displayValue`	Formatted amount.
`otherAmount`	Secondary amount in minor units, when applicable.
`otherAmountDisplayValue`	Formatted secondary amount.

`transaction.cardTransactionData.card`

Field	Description
`maskedPan`	Masked primary account number.
`binNumber`	Bank identification number.
`scheme`	Card scheme.
`cardholderName`	Cardholder name.
`expiryYear`	Card expiry year in `yy` format.
`expiryMonth`	Card expiry month in `MM` format.
`budgetPeriod`	Customer-selected repayment period in months.
`accountType`	Account type value and description.
`panEntryMode`	Card entry mode value and description.
`cvmMethod`	Cardholder verification method value and description.
`cvmConditionCode`	Cardholder verification condition value and description.
`cvmRuleResult`	Cardholder verification result value and description.
`applicationId`	EMV application identifier.
`applicationName`	EMV application label.
`terminalVerificationResult`	Terminal verification result.
`transactionStatusInformation`	EMV transaction status information.
`productType`	Card product type.
`bankName`	Card-issuing bank name.
`countryCode`	Card issuer ISO 3166 alpha-2 country code.
`aip`	EMV Application Interchange Profile.
`aipSupportsCDCVM`	Whether the card supports consumer-device verification.
`tokenized`	Whether the primary account number is tokenised.
`cardHmac`	Peach Payments card HMAC.
`cardFingerprint`	Peach Payments card fingerprint.

`transaction.responseCode`

Field	Description
`value`	Response code.
`description`	Response description.
`isoCodeDescription`	ISO response description.
`terminalOutcomeString`	Outcome text for the terminal.
`receiptString`	Outcome text for the receipt.
`explanation`	Additional response explanation.
`internalResponse`	Peach Payments response code and description.
`acquirerResponse`	Acquirer response code, description, and route.
`schemeResponse`	Card scheme response code.

`transaction.refundBalanceData`

Field	Description
`amount`	Original transaction amount.
`balance`	Amount still available to refund.
`refundHistory`	Successful refunds, including transaction UUID, amount, and transaction time.

`reversalFailureReason`

Possible values are card_declined, customer_cancel, malfunction, suspected_fraud, timeout, unable_to_complete, unable_to_send, security_error, offline_declined, online_declined, partial, too_late_response, issuer_unavailable, and merchant_reversal.

When to use

Setup

Delivery

Reversals

Refunds

Success criterion

Key fields

Payload fields

Webhook envelope

terminal

network and routing

transaction

transaction.cardTransactionData

transaction.cardTransactionData.amount

transaction.cardTransactionData.card

transaction.responseCode

transaction.refundBalanceData

reversalFailureReason

`terminal`

`network` and `routing`

`transaction`

`transaction.cardTransactionData`

`transaction.cardTransactionData.amount`

`transaction.cardTransactionData.card`

`transaction.responseCode`

`transaction.refundBalanceData`

`reversalFailureReason`