Checkout webhooks 🔌

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.

StateDescription
createdA Checkout instance has launched and the Checkout session initiated.
pendingThe merchant initiated a Checkout payment and is awaiting customer completion. Payments can have a future state depending on the customer's action.
successfulThe customer completed a Checkout payment. A final state of a payment attempt.
uncertainThe customer might have cancelled a Checkout payment.
cancelledThe customer cancelled a Checkout payment. 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 allotted time (30 minutes) or could have closed the payment window on their device. A final state of a payment attempt.

Configuration

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

Flow

Webhooks work as follows:

Webhook flow.

Webhook flow.

  1. The merchant receives a webhook with a result code indicating the updated checkout status.
  2. 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.

ParameterTypeExampleDescription
amountString (^[0-9]{1,8}(\\.[0-9]{2})?$)1010.22The amount of the payment request. The period is the decimal separator. M-PESA does not support decimal amounts, so Checkout automatically rounds them up.
checkoutIdString (64)948cc8dec52a11eb85290242ac130003Checkout ID.
currencyString enum [ZAR, USD, KES, MUR, GBP, EUR]ZARThe currency code of the payment request amount.
merchantTransactionIdString (8-16)OrderNo453432Merchant-provided reference number unique for your transactions.
paymentTypeString enum [DB]DBThe payment type for the request.
result.codeString000.200.100A code representing the checkout state.
result.descriptionStringsuccessfully created checkoutA friendly message.
signatureString (64)a668342244a9c77...32035ed06164f4Token to verify the integrity of the webhook, ensuring the request is coming from Checkout.
timestampString2023-07-04T08:10:05ZDate and time when Peach Payments sent the webhook.

Checkout pending

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

ParameterTypeExampleDescription
amountString (^[0-9]{1,8}(\\.[0-9]{2})?$)1010.22The amount of the payment request. The period is the decimal separator. M-PESA does not support decimal amounts, so Checkout automatically rounds them up.
checkoutIdString (64)948cc8dec52a11eb85290242ac130003Checkout ID.
currencyString enum [ZAR, USD, KES, MUR, GBP, EUR]ZARThe currency code of the payment request amount.
idString8ac7a4a184123d86018413e098f32191The transaction ID.
merchantTransactionIdString (8-16)OrderNo453432Merchant-provided reference number unique for your transactions.
paymentBrandString enum [VISA, MASTERCARD, DINERS CLUB, AMERICAN EXPRESS, MASTERPASS, MOBICRED, EFTSECURE, MPESA, 1FORYOU, APLUS, PAYPAL, ZEROPAY, PAYFLEX, BLINKBYEMTEL, CAPITECPAY, NEDBANKDIRECTEFT, MCBJUICE]VISAThe payment method which the customer is paying with.
paymentTypeString enum [DB]DBThe payment type for the request.
result.codeString000.200.000A code representing the checkout state.
result.descriptionStringtransaction pendingA friendly message.
signatureString (64)a668342244a9c77...32035ed06164f4Token to verify the integrity of the webhook, ensuring the request is coming from Checkout.
timestampString2023-07-04T08:10:05ZDate and time when Peach Payments sent the webhook.

Checkout successful

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

ParameterTypeExampleDescription
amountString (^[0-9]{1,8}(\\.[0-9]{2})?$)1010.22The 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.binString (optional)455112The first six digits of the card number.
card.holderString (optional)Grace NkosiThe card account holder.
card.last4DigitsString (optional)2315The last four digits of the card number.
checkoutIdString (64)948cc8dec52a11eb85290242ac130003Checkout ID.
currencyString enum [ZAR, USD, KES, MUR, GBP, EUR]ZARThe currency code of the payment request amount.
idString8ac7a4a184123d86018413e098f32191The transaction ID.
merchant.nameStringPeach PaymentsThe merchant name.
merchantTransactionIdString (8-16)OrderNo453432Merchant-provided reference number unique for your transactions.
paymentBrandString enum [VISA, MASTERCARD, DINERS CLUB, AMERICAN EXPRESS, MASTERPASS, MOBICRED, EFTSECURE, MPESA, 1FORYOU, APLUS, PAYPAL, ZEROPAY, PAYFLEX, PAYBYBANK, BLINKBYEMTEL, CAPITECPAY, NEDBANKDIRECTEFT, MCBJUICE]VISAThe payment method which the customer is paying with.
paymentTypeString enum [DB]DBThe payment type for the request.
recon.authCodeString123456The authorisation code from the payment service provider.
recon.resultCodeStringThe result code from the payment service provider.
recon.rrnString123456789012The reconciliation reference number from the payment service provider.
result.codeString000.000.000A code representing the checkout state.
result.descriptionStringtransaction pendingA friendly message.
resultDetails.AcquirerResponseStringApproved
resultDetails.ConnectorTxID1String
resultDetails.ExtendedDescriptionStringPurchase Approved OK
signatureString (64)a668342244a9c77...32035ed06164f4Token to verify the integrity of the webhook, ensuring the request is coming from Checkout.
timestampString2023-07-04T08:10:05ZDate 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.

ParameterTypeExampleDescription
amountString (^[0-9]{1,8}(\\.[0-9]{2})?$)1010.22The amount of the payment request. The period is the decimal separator. M-PESA does not support decimal amounts, so Checkout automatically rounds them up.
checkoutIdString (64)948cc8dec52a11eb85290242ac130003Checkout ID.
currencyString enum [ZAR, USD, KES, MUR, GBP, EUR]ZARThe currency code of the payment request amount.
merchantTransactionIdString (8-16)OrderNo453432Merchant-provided reference number unique for your transactions.
paymentTypeString enum [DB]DBThe payment type for the request.
result.codeString100.396.104A code representing the checkout state.
result.descriptionStringUncertain status - probably cancelled by userA friendly message.
signatureString (64)a668342244a9c77...32035ed06164f4Token to verify the integrity of the webhook, ensuring the request is coming from Checkout.
timestampString2023-07-04T08:10:05ZDate and time when Peach Payments sent the webhook.

Checkout cancelled

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

ParameterTypeExampleDescription
amountString (^[0-9]{1,8}(\\.[0-9]{2})?$)1010.22The amount of the payment request. The period is the decimal separator. M-PESA does not support decimal amounts, so Checkout automatically rounds them up.
checkoutIdString (64)948cc8dec52a11eb85290242ac130003Checkout ID.
currencyString enum [ZAR, USD, KES, MUR, GBP, EUR]ZARThe currency code of the payment request amount.
merchantTransactionIdString (8-16)OrderNo453432Merchant-provided reference number unique for your transactions.
paymentTypeString enum [DB]DBThe payment type for the request.
result.codeString100.396.101A code representing the checkout state.
result.descriptionStringCancelled by userA friendly message.
signatureString (64)a668342244a9c77...32035ed06164f4Token to verify the integrity of the webhook, ensuring the request is coming from Checkout.
timestampString2023-07-04T08:10:05ZDate 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
amount=10.00&checkoutId=2070b43f10324e5789e0d1e052cc6cez&currency=ZAR&merchantTransactionId=webhooktest01&paymentType=DB&result_code=100.396.104&result_description=Uncertain+status+-+probably+cancelled+by+user&signature=05162c7634b59feaf063706f936340b749d735c33ba131c7556a333fc2cdb99z&timestamp=2023-10-09T11%3A54%3A26Z