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), 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 , FLOAT ] | 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 , FLOAT ] | 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¤cy=ZAR&merchantTransactionId=webhooktest01&paymentType=DB&result_code=000.200.100&result_description=successfully+created+checkout&signature=7b9112e285d00772eb898e3e7cd194b03fa87c85df53f06c81ba5b0b65c36abz×tamp=2023-09-27T20%3A29%3A04Z
amount=10.00&checkoutId=f4e5753843ea4851aec6ec7e3985a8az¤cy=ZAR&id=6b30c8d59dfc435896b925350fe69dbz&merchantTransactionId=webhooktest01&paymentBrand=CAPITECPAY&paymentType=DB&result_code=000.200.000&result_description=transaction+pending&signature=e16c91688e90abdae1b212264e16ac6d03dfb4e08342c67bcc1d09f3d3e8b63z×tamp=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¤cy=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×tamp=2024-11-06T10%3A19%3A39Z
amount=10.00&checkoutId=fd5771f695924af6ade5fa5162789a2z¤cy=ZAR&merchantTransactionId=webhooktest01&paymentType=DB&result_code=100.396.104&result_description=Uncertain+status+-+probably+cancelled+by+user&signature=f0e2fa5bc2b4c6255a6351df5614c35a9c01b9b5a3087956f873bc91115b5d6z×tamp=2023-09-28T10%3A27%3A42Z
amount=10.00&checkoutId=ea266cc84b22402aad42e5d5f2995c7z¤cy=ZAR&merchantTransactionId=webhooktest01&paymentType=DB&result_code=100.396.101&result_description=Cancelled+by+user&signature=353052add9889da0b8c6c15b8caf9ca71e4e736343183030307158595a98bf8z×tamp=2023-09-27T20%3A46%3A56Z
Updated about 4 hours ago