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.

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

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

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

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 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.

Property	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-255`)	`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.

Property	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-255`)	`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`, `STITCHEFT`, `FINCHOICEPAY`, `BLINKBYEMTEL`, `CAPITECPAY`]	`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.

Property	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-255`)	`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, STITCHEFT, FINCHOICEPAY, BLINKBYEMTEL, CAPITECPAY`]	`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.200.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.

Property	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-255`)	`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.

Property	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-255`)	`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.