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.
The API:
- Signs all webhooks (for both Embedded and Hosted Checkout) with a signature using the secret token as the key.
- Sends all webhooks from a known range of IP addresses.
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 | One of the following has occurred: - The customer completed a Checkout payment. A final state of a payment attempt. - The merchant refunded a customer successfully. A final state. |
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
Checkout sends webhooks as x-www-form-urlencoded
content.
You can configure webhooks in two ways:
- Add a webhook URL in the Peach Payments Dashboard, as described in the Configure a webhook section.
- Enter a webhook URL in the
notificationUrl
parameter of the initiate Checkout request:- You can configure a different URL to the webhook URL if you want to send webhooks to two location.
- You can set the
notificationUrl
dynamically per Checkout, for example, if you want to send all webhooks to the webhook URL, and specific webhooks for certain types of Checkouts to a different URL. - If you've configured a webhook in the Dashboard, Peach Payments sends webhooks to both the webhook URL and this URL.
Flow
Webhooks work as follows:
Webhook flow.
- 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
See the Reference materials section for details on the webhook retry mechanism and retry logic.
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 , MASTER , DINERS , AMEX , MASTERPASS , MOBICRED , MPESA , 1FORYOU , APLUS , PAYPAL , ZEROPAY , PAYFLEX , BLINKBYEMTEL , CAPITECPAY , MCBJUICE , PEACHEFT , RCS , GOOGLEPAY , FLOAT , SAMSUNGPAY , HAPPYPAY , MAUCAS , MONEYBADGER ] | 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.expiryMonth | String (optional) | 11 | The expiry month of the card. |
card.expiryYear | String (optional) | 2029 | The expiry year of the card. |
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. |
isApplePayWallet | Boolean (optional) | true | Specifies whether the transaction was processed using Apple Pay. |
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 , MASTER , DINERS , AMEX , MASTERPASS , MOBICRED , MPESA , 1FORYOU , APLUS , PAYPAL , ZEROPAY , PAYFLEX , PAYBYBANK , BLINKBYEMTEL , CAPITECPAY , MCBJUICE , PEACHEFT , RCS , GOOGLEPAY , FLOAT , SAMSUNGPAY , HAPPYPAY , MAUCAS , MONEYBADGER ] | VISA | The payment method which the customer is paying with. |
paymentType | String enum [DB , PA , RF ] | 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=839.44&card.bin=&card.expiryMonth=&card.expiryYear=&card.last4Digits=&checkoutId=9f77244f9e2c4976996c6563f647b3f9¤cy=ZAR&descriptor=&id=e9397e8649334ceaa765b2569b7f62ca&merchant.name=Peach-Testing&merchantTransactionId=reYsGSx77g7q21jVy9V4ESSAX&paymentBrand=1FORYOU&paymentType=RF&recon.authCode=None&recon.resultCode=None&recon.rrn=None&recon.stan=None&referencedId=6419b4099b7448139e7f129dcf6df755&result.code=000.100.110&result.description=Request+successfully+processed+in+%27Merchant+in+Integrator+Test+Mode%27&signature=b2d7c36a1b0efd1f6a08175ed3ea5c81c2325b2bcee88213d19a8bd735e17572×tamp=2025-04-15T09%3A22%3A35Z
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 1 day ago