Webhooks 🔌
Webhooks are HTTP callbacks that deliver notification messages for events. Peach Payments uses webhooks to inform merchant systems when certain events occur. This way, your servers are always up to date with transaction information.
After configuring and verifying a webhook, Peach Payments delivers POST notifications to the specified URL for the following events:
Webhook event | Description |
---|---|
initiated | Triggered when you create the payment link. |
processing | Triggered when a customer attempts to pay. |
completed | Triggered when a customer completes the payment. |
cancelled | Triggered when a customer cancels the payment. |
expired | Triggered when the payment link expires. |
For bulk payment links, Peach Payments sends webhooks for the underlying payment links and for the following batch events:
Webhook event | Description |
---|---|
initiated | Triggered when you create the batch. |
processing | Triggered when processing starts on the bulk file. |
completed | Triggered when Payment Links completes processing of the bulk file. |
error | Triggered if Payment Links cannot process the bulk file. |
expired | Triggered if you do not upload a file in three hours. |
Workflow
- Merchants can configure webhooks in one of two ways:
- Enter a webhook URL in the
notificationUrl
parameter of theoptions
object of the generate link request or in thenotificationUrl
parameter of the generate bulk link request. - Register a webhook URL in the Peach Payments Dashboard.
- Enter a webhook URL in the
- Predefined events, as described above, trigger the webhook.
- The merchant then triggers a query to pull transaction or batch details and statuses.
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 until a successful acknowledgement (200 HTTP) occurs.
Exponential backoff retry
Below is the exponential backoff logic.
The interval between retries is:
- 1 minute
- 2 minutes
- 4 minutes
- 8 minutes
- 15 minutes
- 30 minutes
- 1 hour
- Every day until 30 days have passed since the first attempt
Webhook event responses
The following are some of the triggered webhook event responses.
{
"status": "initiated",
"url": "https://qa-v2.ppay.io/2c81cb0406171e9a",
"paymentId": "00d886d6-4754-4bcc-b88f-74a53d5220e5"
}
{
"status": "expired",
"paymentId": "00d886d6-4754-4bcc-b88f-74a53d5220e5"
}
{
"status": "processing",
"paymentId": "ee0d5e12-2d46-43e0-bb2d-228e5f9ce86c"
}
{
"status": "completed",
"paymentId": "ee0d5e12-2d46-43e0-bb2d-228e5f9ce86c"
}
Updated 16 days ago