Payment Links webhooks
Overview
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 a payment link. |
opened | Triggered when a customer opens the payment link. |
processing | Triggered when a customer attempts to pay. |
completed | Triggered when a customer completes the payment. |
cancelled | Triggered when you cancel the payment link. |
expired | Triggered when the payment link expires. |
- 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.
- Payment Links uses Checkout to accept payments. Peach Payments therefore sends you webhooks for Payment Links and Checkout updates. To only receive Payment Links webhooks, contact support.
- Payment Links sends all webhooks from a known range of IP addresses.
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. |
Flow
You can configure webhooks in two ways:
- Add a webhook URL in the Peach Payments Dashboard.
- 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. ThenotificationUrl
webhook overrides the webhook configured in the Dashboard.
Predefined events, as described above, trigger the webhook.
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.
The merchant can then trigger a query to pull transaction or batch details and statuses.
Webhook retry mechanism
See the Reference materials section for details on the webhook retry mechanism and retry logic.
Webhook events
Peach Payments sends the following webhooks for payment links.
Event | Parameter | Type | Example |
---|---|---|---|
Initiated | paymentId | String | 00d886d6-4754-4bcc-b88f-74a53d5220e5 |
status | String | initiated | |
url | String (URL) | https://l.ppay.io/4c1a48e6dc3b7ebd | |
Opened | paymentId | String | 00d886d6-4754-4bcc-b88f-74a53d5220e5 |
status | String | opened | |
Processing | paymentId | String | 00d886d6-4754-4bcc-b88f-74a53d5220e5 |
status | String | processing | |
Completed | paymentId | String | 00d886d6-4754-4bcc-b88f-74a53d5220e5 |
status | String | completed | |
paymentBrand | String enum [VISA , MASTER , DINERS , AMEX , MASTERPASS , MOBICRED , MPESA , 1FORYOU , APLUS , PAYPAL , ZEROPAY , PAYFLEX , BLINKBYEMTEL , CAPITECPAY , MCBJUICE , PEACHEFT ] | VISA | |
registrationId * | String (optional) | 8ac7a4a188e7cf090188f7112dbe389a | |
Cancelled | paymentId | String | 00d886d6-4754-4bcc-b88f-74a53d5220e5 |
status | String | cancelled | |
Expired | paymentId | String | 00d886d6-4754-4bcc-b88f-74a53d5220e5 |
status | String | expired |
* Card registration token, if tokeniseCard
was true on the initial request and paymentBrand
is a card type.
{
"status": "initiated",
"url": "https://l.ppay.io/4c1a48e6dc3b7ebd",
"paymentId": "00d886d6-4754-4bcc-b88f-74a53d5220e5"
}
{
"status": "opened",
"paymentId": "00d886d6-4754-4bcc-b88f-74a53d5220e5"
}
{
"status": "processing",
"paymentId": "00d886d6-4754-4bcc-b88f-74a53d5220e5"
}
{
"status": "completed",
"paymentId": "00d886d6-4754-4bcc-b88f-74a53d5220e5",
"paymentBrand": "VISA",
"registrationId": "8ac7a4a188e7cf090188f7112dbe389a",
}
{
"status": "cancelled",
"paymentId": "00d886d6-4754-4bcc-b88f-74a53d5220e5"
}
{
"status": "expired",
"paymentId": "00d886d6-4754-4bcc-b88f-74a53d5220e5"
}
Updated 1 day ago