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 eventDescription
initiatedTriggered when you create the payment link.
openedTriggered when a customer opens the payment link.
processingTriggered when a customer attempts to pay.
completedTriggered when a customer completes the payment.
cancelledTriggered when a customer cancels the payment.
expiredTriggered 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 eventDescription
initiatedTriggered when you create the batch.
processingTriggered when processing starts on the bulk file.
completedTriggered when Payment Links completes processing of the bulk file.
errorTriggered if Payment Links cannot process the bulk file.
expiredTriggered if you do not upload a file in three hours.

Flow

Merchants can configure webhooks in one of two ways:

Predefined events, as described above, trigger the webhook.

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.

The merchant can then trigger 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 events

Peach Payments sends the following webhooks for payment links.

EventParameterTypeExample
InitiatedpaymentIdString00d886d6-4754-4bcc-b88f-74a53d5220e5
statusStringinitiated
urlString (URL)https://l.ppay.io/4c1a48e6dc3b7ebd
OpenedpaymentIdString00d886d6-4754-4bcc-b88f-74a53d5220e5
statusStringopened
ProcessingpaymentIdString00d886d6-4754-4bcc-b88f-74a53d5220e5
statusStringprocessing
CompletedpaymentIdString00d886d6-4754-4bcc-b88f-74a53d5220e5
statusStringcompleted
paymentBrandString enum [VISA, MASTERCARD, DINERS CLUB, AMERICAN EXPRESS, MASTERPASS, MOBICRED, EFTSECURE, MPESA, 1FORYOU, APLUS, PAYPAL, ZEROPAY, PAYFLEX, FINCHOICEPAY, BLINKBYEMTEL, CAPITECPAY]VISA
registrationId*String (optional)8ac7a4a188e7cf090188f7112dbe389a
CancelledpaymentIdString00d886d6-4754-4bcc-b88f-74a53d5220e5
statusStringcancelled
ExpiredpaymentIdString00d886d6-4754-4bcc-b88f-74a53d5220e5
statusStringexpired

* 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"
}