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 debit (DB), preauthorisation (PA), and refund (RF) requests.

📘
The API:

Signs all webhooks (for both Embedded and Hosted Checkout) with a signature using the secret token as the key.

Sends all webhooks from a known range of IP addresses.

State	Description
`created`	A Checkout instance has launched and the Checkout session initiated.
`pending`	The merchant initiated a Checkout payment and is awaiting customer completion. Payments can have a future state depending on the customer's action.
`successful`	One of the following has occurred: - The customer completed a Checkout payment. A final state of a payment attempt. - The merchant refunded a customer successfully. A final state.
`uncertain`	The customer might have cancelled a Checkout payment. Alternatively, a Checkout payment has timed out. 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.
`cancelled`	The customer cancelled a Checkout payment. A final state of a payment attempt.

📘
In certain circumstances, Peach Payments could update a checkout status using webhooks after a checkout session ends. For example, system issues might result in a checkout status being incorrect during the session; when the session ends and the system recovers, Peach Payments sends a webhook with the updated status.
Transaction statuses can change as follows:

Created -> Pending

Pending -> Successful, cancelled, or uncertain

Uncertain or cancelled -> Successful

Peach Payments cannot guarantee the order of webhooks. For example, if your customer initiates a transaction and Peach Payments sends a pending webhook but you have a system issue that causes the webhook to go into exponential backoff, Peach Payments might send the next webhook before the pending webhook gets retried. The webhook payload contains a timestamp that you can use to identify the correct order of webhooks.

Configuration

Checkout sends webhooks as x-www-form-urlencoded content.

You can configure webhooks in two ways:

Add a webhook URL in the Peach Payments Dashboard, as described in the Configure a webhook section.
Enter a webhook URL in the notificationUrl parameter of the initiate Checkout request:
- You can configure a different URL to the webhook URL if you want to send webhooks to two location.
- You can set the notificationUrl dynamically per Checkout, for example, if you want to send all webhooks to the webhook URL, and specific webhooks for certain types of Checkouts to a different URL.
- If you've configured a webhook in the Dashboard, Peach Payments sends webhooks to both the webhook URL and this URL.

Flow

Webhooks work as follows:

The merchant receives a webhook with a result code indicating the updated checkout status.
The merchant returns a 200 status code response acknowledging the webhook.

Webhook retry mechanism

See the Reference materials section for details on the webhook retry mechanism and retry logic.

Webhook events

When your service receives a webhook notification, it must return a 200 HTTP status code. Peach Payments sends notifications using the URL-encoded query string format via HTTP POST. The webhook payload differs depending on the request parameters and payment method. If your service does not return a 200 HTTP status code, the webhook service considers the notification delivery as failed and retries sending the notification later.

Checkout created

Peach Payments sends this webhook when creating a checkout instance.

Parameter	Type	Example	Description
`amount`	String (`^[0-9]{1,8}(\\.[0-9]{2})?$`)	`1010.22`	The amount of the payment request. The period is the decimal separator. M-PESA does not support decimal amounts, so Checkout automatically rounds them up.
`checkoutId`	String (`64`)	`948cc8dec52a11eb85290242ac130003`	Checkout ID.
`currency`	String enum [`ZAR`, `USD`, `KES`, `MUR`, `GBP`, `EUR`]	`ZAR`	The currency code of the payment request amount.
`merchantTransactionId`	String (`8-16`)	`OrderNo453432`	Merchant-provided reference number unique for your transactions.
`paymentType`	String enum [`DB`, `PA`]	`DB`	The payment type for the request.
`result.code`	String	`000.200.100`	A code representing the checkout state.
`result.description`	String	`successfully created checkout`	A friendly message.
`signature`	String (`64`)	`a668342244a9c77...32035ed06164f4`	Token to verify the integrity of the webhook, ensuring the request is coming from Checkout.
`timestamp`	String	`2023-07-04T08:10:05Z`	Date and time when Peach Payments sent the webhook.

Checkout pending

Peach Payments sends this webhook when creating a transaction on a checkout instance.

Parameter	Type	Example	Description
`amount`	String (`^[0-9]{1,8}(\\.[0-9]{2})?$`)	`1010.22`	The amount of the payment request. The period is the decimal separator. M-PESA does not support decimal amounts, so Checkout automatically rounds them up.
`checkoutId`	String (`64`)	`948cc8dec52a11eb85290242ac130003`	Checkout ID.
`currency`	String enum [`ZAR`, `USD`, `KES`, `MUR`, `GBP`, `EUR`]	`ZAR`	The currency code of the payment request amount.
`id`	String	`8ac7a4a184123d86018413e098f32191`	The transaction ID.
`merchantTransactionId`	String (`8-16`)	`OrderNo453432`	Merchant-provided reference number unique for your transactions.
`paymentBrand`	String enum [`VISA`, `MASTER`, `DINERS`, `AMEX`, `MASTERPASS`, `MOBICRED`, `MPESA`, `1FORYOU`, `APLUS`, `PAYPAL`, `ZEROPAY`, `PAYFLEX`, `BLINKBYEMTEL`, `CAPITECPAY`, `MCBJUICE`, `PEACHEFT`, `RCS`, `GOOGLEPAY`, `FLOAT`, `SAMSUNGPAY`, `HAPPYPAY`, `MAUCAS`, `MONEYBADGER`]	`VISA`	The payment method which the customer is paying with.
`paymentType`	String enum [`DB`, `PA`]	`DB`	The payment type for the request.
`result.code`	String	`000.200.000`	A code representing the checkout state.
`result.description`	String	`transaction pending`	A friendly message.
`signature`	String (`64`)	`a668342244a9c77...32035ed06164f4`	Token to verify the integrity of the webhook, ensuring the request is coming from Checkout.
`timestamp`	String	`2023-07-04T08:10:05Z`	Date and time when Peach Payments sent the webhook.

Checkout successful

Peach Payments sends this webhook when a user completes a checkout instance.

Parameter	Type	Example	Description
`amount`	String (`^[0-9]{1,8}(\\.[0-9]{2})?$`)	`1010.22`	The amount of the payment request. The period is the decimal separator. M-PESA does not support decimal amounts, so Checkout automatically rounds them up.
`billing.city`	String (optional)	`Cape Town`	The customer's billing city.
`billing.company`	String (optional)	`Peach Payments`	The customer's billing company.
`billing.country`	String (optional)	`ZA`	The customer's billing country.
`billing.postcode`	String (optional)	`8000`	The customer's billing postal code.
`billing.street1`	String (optional)	`123 Main Street`	The customer's billing street.
`card.bin`	String (optional)	`455112`	The first six digits of the card number.
`card.expiryMonth`	String (optional)	`11`	The expiry month of the card.
`card.expiryYear`	String (optional)	`2029`	The expiry year of the card.
`card.holder`	String (optional)	`Grace Nkosi`	The card account holder.
`card.last4Digits`	String (optional)	`2315`	The last four digits of the card number.
`checkoutId`	String (`64`)	`948cc8dec52a11eb85290242ac130003`	Checkout ID.
`currency`	String enum [`ZAR`, `USD`, `KES`, `MUR`, `GBP`, `EUR`]	`ZAR`	The currency code of the payment request amount.
`customer.email`	String (optional)	`[email protected]`	The customer's email address.
`customer.givenName`	String (optional)	`John`	The customer's first name.
`customer.mobile`	String (optional)	`+27831234567`	The customer's mobile number.
`customer.surname`	String (optional)	`Doe`	The customer's surname.
`id`	String	`8ac7a4a184123d86018413e098f32191`	The transaction ID.
`isApplePayWallet`	Boolean (optional)	`true`	Specifies whether the transaction was processed using Apple Pay.
`merchant.name`	String	`Peach Payments`	The merchant name.
`merchantTransactionId`	String (`8-16`)	`OrderNo453432`	Merchant-provided reference number unique for your transactions.
`paymentBrand`	String enum [`VISA`, `MASTER`, `DINERS`, `AMEX`, `MASTERPASS`, `MOBICRED`, `MPESA`, `1FORYOU`, `APLUS`, `PAYPAL`, `ZEROPAY`, `PAYFLEX`, `PAYBYBANK`, `BLINKBYEMTEL`, `CAPITECPAY`, `MCBJUICE`, `PEACHEFT`, `RCS`, `GOOGLEPAY`, `FLOAT`, `SAMSUNGPAY`, `HAPPYPAY`, `MAUCAS`, `MONEYBADGER`]	`VISA`	The payment method which the customer is paying with.
`paymentType`	String enum [`DB`, `PA`, `RF`]	`DB`	The payment type for the request.
`recon.authCode`	String	`123456`	The authorisation code from the payment service provider.
`recon.resultCode`	String		The result code from the payment service provider.
`recon.rrn`	String	`123456789012`	The reconciliation reference number from the payment service provider.
`result.code`	String	`000.000.000`	A code representing the checkout state.
`result.description`	String	`transaction pending`	A friendly message.
`resultDetails.AcquirerResponse`	String	`Approved`
`resultDetails.ConnectorTxID1`	String
`resultDetails.ExtendedDescription`	String	`Purchase Approved OK`
`shipping.city`	String (optional)	`Cape Town`	The customer's shipping city.
`shipping.company`	String (optional)	`Peach Payments`	The customer's shipping company.
`shipping.country`	String (optional)	`ZA`	The customer's shipping country.
`shipping.postcode`	String (optional)	`8000`	The customer's shipping postal code.
`shipping.street1`	String (optional)	`123 Main Street`	The customer's shipping street.
`signature`	String (`64`)	`a668342244a9c77...32035ed06164f4`	Token to verify the integrity of the webhook, ensuring the request is coming from Checkout.
`timestamp`	String	`2023-07-04T08:10:05Z`	Date and time when Peach Payments sent the webhook.

Checkout uncertain status

Peach Payments sends this webhook when a user might have cancelled a checkout instance.

Parameter	Type	Example	Description
`amount`	String (`^[0-9]{1,8}(\\.[0-9]{2})?$`)	`1010.22`	The amount of the payment request. The period is the decimal separator. M-PESA does not support decimal amounts, so Checkout automatically rounds them up.
`checkoutId`	String (`64`)	`948cc8dec52a11eb85290242ac130003`	Checkout ID.
`currency`	String enum [`ZAR`, `USD`, `KES`, `MUR`, `GBP`, `EUR`]	`ZAR`	The currency code of the payment request amount.
`merchantTransactionId`	String (`8-16`)	`OrderNo453432`	Merchant-provided reference number unique for your transactions.
`paymentType`	String enum [`DB`, `PA`]	`DB`	The payment type for the request.
`result.code`	String	`100.396.104`	A code representing the checkout state.
`result.description`	String	`Uncertain status - probably cancelled by user`	A friendly message.
`signature`	String (`64`)	`a668342244a9c77...32035ed06164f4`	Token to verify the integrity of the webhook, ensuring the request is coming from Checkout.
`timestamp`	String	`2023-07-04T08:10:05Z`	Date and time when Peach Payments sent the webhook.

Checkout cancelled

Peach Payments sends this webhook when a user cancels a checkout instance.

Parameter	Type	Example	Description
`amount`	String (`^[0-9]{1,8}(\\.[0-9]{2})?$`)	`1010.22`	The amount of the payment request. The period is the decimal separator. M-PESA does not support decimal amounts, so Checkout automatically rounds them up.
`checkoutId`	String (`64`)	`948cc8dec52a11eb85290242ac130003`	Checkout ID.
`currency`	String enum [`ZAR`, `USD`, `KES`, `MUR`, `GBP`, `EUR`]	`ZAR`	The currency code of the payment request amount.
`merchantTransactionId`	String (`8-16`)	`OrderNo453432`	Merchant-provided reference number unique for your transactions.
`paymentType`	String enum [`DB`, `PA`]	`DB`	The payment type for the request.
`result.code`	String	`100.396.101`	A code representing the checkout state.
`result.description`	String	`Cancelled by user`	A friendly message.
`signature`	String (`64`)	`a668342244a9c77...32035ed06164f4`	Token to verify the integrity of the webhook, ensuring the request is coming from Checkout.
`timestamp`	String	`2023-07-04T08:10:05Z`	Date and time when Peach Payments sent the webhook.

Example webhooks

amount=10.00&checkoutId=f4e5753843ea4851aec6ec7e3985a8az&currency=ZAR&merchantTransactionId=webhooktest01&paymentType=DB&result_code=000.200.100&result_description=successfully+created+checkout&signature=7b9112e285d00772eb898e3e7cd194b03fa87c85df53f06c81ba5b0b65c36abz&timestamp=2023-09-27T20%3A29%3A04Z

amount=10.00&checkoutId=f4e5753843ea4851aec6ec7e3985a8az&currency=ZAR&id=6b30c8d59dfc435896b925350fe69dbz&merchantTransactionId=webhooktest01&paymentBrand=CAPITECPAY&paymentType=DB&result_code=000.200.000&result_description=transaction+pending&signature=e16c91688e90abdae1b212264e16ac6d03dfb4e08342c67bcc1d09f3d3e8b63z&timestamp=2023-09-27T20%3A30%3A44Z

amount=10.00&bankAccount.bankCode=470010&bankAccount.bankName=capitec&billing.city=Cape+Town&billing.country=ZA&billing.postcode=8000&billing.street1=123+Main+Street&checkoutId=b361300e1b334acdb8bdd6e764ef0d9a&currency=ZAR&customer.email=test%40test.com&customer.givenName=John&customer.mobile=%2B27831234567&customer.surname=Doe&id=749a0cc6f45e4449b4bcb0c6fa3a0084&merchant.name=Peach+Payments&merchantTransactionId=20241106121719&paymentBrand=CAPITECPAY&paymentType=DB&result.code=000.100.110&result.description=Request+successfully+processed+in+%27Merchant+in+Integrator+Test+Mode%27&resultDetails.AcquirerResponse=SUCCESS&resultDetails.ConnectorTxID1=8cc4fc8a-9c28-11ef-89cc-0e61cffa7e17&resultDetails.ExtendedDescription=The+transaction+has+completed.&shipping.city=Cape+Town&shipping.country=ZA&shipping.postcode=8000&shipping.street1=123+Main+Street&signature=c63e56a78ede97d613e0287d8b1825f8c932bd64c554f2d20a997d366aca9626&timestamp=2024-11-06T10%3A19%3A39Z

amount=839.44&card.bin=&card.expiryMonth=&card.expiryYear=&card.last4Digits=&checkoutId=9f77244f9e2c4976996c6563f647b3f9&currency=ZAR&descriptor=&id=e9397e8649334ceaa765b2569b7f62ca&merchant.name=Peach-Testing&merchantTransactionId=reYsGSx77g7q21jVy9V4ESSAX&paymentBrand=1FORYOU&paymentType=RF&recon.authCode=None&recon.resultCode=None&recon.rrn=None&recon.stan=None&referencedId=6419b4099b7448139e7f129dcf6df755&result.code=000.100.110&result.description=Request+successfully+processed+in+%27Merchant+in+Integrator+Test+Mode%27&signature=b2d7c36a1b0efd1f6a08175ed3ea5c81c2325b2bcee88213d19a8bd735e17572&timestamp=2025-04-15T09%3A22%3A35Z

amount=10.00&checkoutId=fd5771f695924af6ade5fa5162789a2z&currency=ZAR&merchantTransactionId=webhooktest01&paymentType=DB&result_code=100.396.104&result_description=Uncertain+status+-+probably+cancelled+by+user&signature=f0e2fa5bc2b4c6255a6351df5614c35a9c01b9b5a3087956f873bc91115b5d6z&timestamp=2023-09-28T10%3A27%3A42Z

amount=10.00&checkoutId=ea266cc84b22402aad42e5d5f2995c7z&currency=ZAR&merchantTransactionId=webhooktest01&paymentType=DB&result_code=100.396.101&result_description=Cancelled+by+user&signature=353052add9889da0b8c6c15b8caf9ca71e4e736343183030307158595a98bf8z&timestamp=2023-09-27T20%3A46%3A56Z