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:

📘

• 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.

For bulk payment links, Peach Payments sends webhooks for the underlying payment links and for the following batch events:

Flow

Merchants can configure webhooks in one of two ways:

• Enter a webhook URL in the notificationUrl parameter of the options object of the generate link request or in the notificationUrl parameter of the generate bulk link request.
• Register a webhook URL in the Peach Payments Dashboard.

Predefined events, as described above, trigger the webhook.

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 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

Peach Payments sends the following webhooks for payment links.

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