Webhooks

Paytree provides webhook support to keep you informed of payment status updates. When important events occur— such as changes in payment status, failed attempts, or successful transactions—we will send relevant data to the callback URL you specify.

It is essential to implement webhook handling on your server to receive these updates in real time. This will allow you to keep your system in sync with payment events and take appropriate actions based on the information received.

Ensure that your callback URL is publicly accessible and capable of securely processing the incoming webhook data. Proper handling of webhooks is critical to maintaining a smooth payment process and ensuring your system stays up-to-date.

Callback Flow

Paytree webhooks allow you to receive real-time payment updates by sending data to the callback URL you specify. The flow is as follows:

1. GET Request to Callback URL: Paytree sends a GET request to the callback URL you provide, containing key parameters like Payment Intent ID and Transaction ID.

2. Extract Parameters: You need to extract the Payment Intent ID and Transaction ID from the request to identify the relevant payment.

3. Lookup Payment Details: Use the Payment Intent ID to make an API request to Paytree, retrieving the latest payment information and status.

You must respond with a HTTP status code of 200. Any other status code will result in a total 10 consecutive retry attempts, spaced 30 seconds apart.

Adhering to this flow ensures your system is up-to-date with the latest payment data and status changes.

Overview of webhook notification process flow

Callback URL Tags

When setting up your callback URL for Paytree webhooks, you can use special tags to dynamically represent key values such as the Payment Intent ID and Transaction ID. These tags are replaced by Paytree with the actual data when sending the webhook request.

• {payment_intent_id}: This tag represents the Payment Intent ID that Paytree generates when you create a payment intent. You will need to use this ID to perform the lookup for the latest payment details.

• {transaction_id}: This tag represents the transaction_ref that you provide when creating a payment. This will be included in the webhook data to help you match the payment with your system.

You can place these tags in your callback URL, and Paytree will automatically replace them with the corresponding values in the webhook request. For example, your callback URL might look like this:

https://yourdomain.com/payment-update?payment_intent_id={payment_intent_id}&transaction_id={transaction_id}

When the webhook is triggered, Paytree will replace the tags with actual values, so the resulting URL might look like this:

https://yourdomain.com/payment-update?payment_intent_id=76460612-27a6-40a3-ad1a-7da0b758f563&transaction_id=txn_abc123

Retries

In the event where you return a status code which is not 200, we will attempt a total of 10 retries, first one 30 seconds after the initital failure and all subsequent ones 60 seconds apart.

Retry Attempt	Time after Previous Attempt (in seconds)	Retry Timestamp
1st Retry	30	January 1, 2024, 12:00:30 PM
2nd Retry	60	January 1, 2024, 12:01:30 PM
3rd Retry	60	January 1, 2024, 12:02:30 PM
4th Retry	60	January 1, 2024, 12:03:30 PM
5th Retry	60	January 1, 2024, 12:04:30 PM
6th Retry	60	January 1, 2024, 12:05:30 PM
7th Retry	60	January 1, 2024, 12:06:30 PM
8th Retry	60	January 1, 2024, 12:07:30 PM
9th Retry	60	January 1, 2024, 12:08:30 PM
10th Retry	60	January 1, 2024, 12:09:30 PM

In the event of a longer outage, where you were unable to capture any events sent by us (Including all retries); it's possible to query the payment intent or payment endpoints to retreieve up to date information about the transactions in question.