Webhooks 🔌

Overview

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

StateDescription
createdA Checkout instance has been launched and the Checkout session has been initiated.
pendingA Checkout payment has been initiated by the merchant and is awaiting customer completion. Payments can have a future state depending on the customer's action.
successfulA Checkout payment has been successfully completed. This is a final state of a payment attempt.
cancelledA Checkout payment has been cancelled by the customer. This is 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 alloted time (30 minutes) or could have closed the payment window on their device. This is a final state of a payment attempt.

Configuration

Transaction webhooks can be set up and managed for both live and test environments from within the Peach Payments Console. A valid URL, responding with a 200 must be set up for you to register and save.

Webhook notifications are sent for all debit (DB) payments. In order to receive refund webhooks, merchants must opt-in for refund notifications within the Peach Payments Console.

📘

All webhooks are signed 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"
}