Webhooks 🔌

Overview

Webhooks are HTTP callbacks that deliver notification messages for events. Checkout sends a webhook to the merchant-provided URL for every state change of the Checkout payment request.

StateDescription
createdA Checkout instance has launched and the Checkout session initiated.
pendingThe merchant initiated a Checkout payment and is awaiting customer completion. Payments can have a future state depending on the customer's action.
successfulThe customer completed a Checkout payment. A final state of a payment attempt.
cancelledThe customer cancelled a Checkout payment. A final state of a payment attempt.
expiredA Checkout payment has timed out by the customer. The customer might not have completed their payment in the allotted time (30 minutes) or could have closed the payment window on their device. A final state of a payment attempt.

Configuration

Set up and manage transaction webhooks for both live and test environments from the Peach Payments Console. Configure a valid URL responding with a 200 to register and save the webhook.

Checkout sends a webhook notification for all debit (DB) payments. To receive refund webhooks, merchants must opt-in for refund notifications in the Peach Payments Console.

📘

The API signs all webhooks with a signature using the secret token as the key.

Respond to notifications

When your service receives a webhook notification, it must return a 200 HTTP status code. Otherwise, the webhook service considers the notification delivery as failed and retries sending the notification later.

{
"amount": "14.99",
"checkoutId": "0fa125d002044484b0fbfb43c1c5c554",
"currency": "ZAR",
"id": "1d6c60ed0dfd4a6a9a26a13922b65766",
"merchantInvoiceId": "5654-654645-65464",
"merchantTransactionId": "UAT",
"paymentBrand": "MOBICRED",
"paymentType": "DB",
"result.code": "000.100.110",
"result.description": "Request successfully processed in 'Merchant in Integrator
Test Mode",
"resultDetails.AcquirerResponse": "Approved",
"resultDetails.ConnectorTxID1": "20001694247",
"resultDetails.ExtendedDescription": "Purchase Approved OK",
"timestamp": "2019-01-25T08:27:46.916519Z",
"signature": "49d3166063b4d881b50af0b4648c1244bfa9890a53ed6bce6d24b610777"
}
{
"amount": "2.00",
"currency": "ZAR",
"descriptor": " UAT Checkout 8831.2726.5961",
"id": "8ac7a4a06b4f7618016b50fdaa4305fb",
"merchantTransactionId": "Test1234",
"paymentType": "RF",
"referencedId": "8ac7a4a16b4f6a06016b50fb930431e8",
"result.code": "000.100.110",
"result.description": "Request successfully processed in 'Merchant in Integrator
Test Mode'",
"timestamp": "2019-06-13 13:18:50+0000",
"signature": "49d3166063b4d881b50af0b4648c1244bfa9890a53ed6bce6d2386404b610777"
}