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.

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

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

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`	The customer completed a Checkout payment. A final state of a payment attempt.
`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

To configure a webhook, follow the instructions in the webhook documentation.

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

Peach Payments expects a 200 HTTP for successful webhook delivery and a non-200 HTTP status code for failures.

For an unsuccessful response, Peach Payments retries the webhook for 30 days or until a successful acknowledgement (200 HTTP) occurs.

Exponential backoff retry

Below is the exponential backoff logic.

The interval between retries is:

2 minutes
4 minutes
8 minutes
15 minutes
30 minutes
1 hour, every day until 30 days have passed since the first attempt

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`, `MASTERCARD`, `DINERS CLUB`, `AMERICAN EXPRESS`, `MASTERPASS`, `MOBICRED`, `MPESA`, `1FORYOU`, `APLUS`, `PAYPAL`, `ZEROPAY`, `PAYFLEX`, `BLINKBYEMTEL`, `CAPITECPAY`, `MCBJUICE`, `PEACHEFT`, `RCS`, `GOOGLEPAY`]	`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.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.
`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, MASTERCARD, DINERS CLUB, AMERICAN EXPRESS, MASTERPASS, MOBICRED, MPESA, 1FORYOU, APLUS, PAYPAL, ZEROPAY, PAYFLEX, PAYBYBANK, BLINKBYEMTEL, CAPITECPAY`, `MCBJUICE`, `PEACHEFT`, `RCS`, `GOOGLEPAY`]	`VISA`	The payment method which the customer is paying with.
`paymentType`	String enum [`DB`, `PA`]	`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=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