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) and refund 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. Otherwise, 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]	`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`, `EFTSECURE`, `MPESA`, `1FORYOU`, `APLUS`, `PAYPAL`, `ZEROPAY`, `PAYFLEX`, `BLINKBYEMTEL`, `CAPITECPAY`, `NEDBANKDIRECTEFT`, `MCBJUICE`]	`VISA`	The payment method which the customer is paying with.
`paymentType`	String enum [`DB`]	`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.
`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.
`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, EFTSECURE, MPESA, 1FORYOU, APLUS, PAYPAL, ZEROPAY, PAYFLEX, PAYBYBANK, BLINKBYEMTEL, CAPITECPAY`, `NEDBANKDIRECTEFT`, `MCBJUICE`]	`VISA`	The payment method which the customer is paying with.
`paymentType`	String enum [`DB`]	`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`
`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`]	`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`]	`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&checkoutId=f4e5753843ea4851aec6ec7e3985a8az&currency=ZAR&id=6b30c8d59dfc435896b925350fe69dbz&merchant_name=Peach&merchantTransactionId=webhooktest01&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=6d0E956E-D561-15f2-3093-AfEFCD00ef7e&resultDetails_ExtendedDescription=Payment+went+through+successfully&signature=efe12782ef127a8a855805fbe26db09dcf3ed9b48fc2d49d4fb2e5d02c42bdbz&timestamp=2023-09-27T20%3A31%3A02Z

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