Skip to content
Customer portal
Contact us
  • There are no suggestions because the search field is empty.

Checkout Instant Payment Notification

The Checkout feature supports an Instant Payment Notification (IPN) mechanism. This sends reliable server-to-server notifications (webhooks) to your system to confirm all status changes, regardless of the user's browser state. Your system can then process these events to update the order status accordingly.

How to Implement

Integrating the IPN mechanism is a three-step process:

Step 1: Provide a Webhook URL in the Intent API Call

To receive server-to-server notifications for a checkout session, you must include the webhook_url parameter in the body of your POST /v1/checkouts/intent API call. This parameter specifies the URL where Paydock will send all webhooks related to the session. Paydock validates the reachability of this URL before proceeding with the payment.

If the webhook_url is omitted, no webhooks will be sent for that specific checkout session. 

Example Intent object:

{

  "amount": number,

  "version": number,

  "currency": "string",

  "description": "string",

  "reference": "string",

  "reference2": "string",

  "customer_reference": "string",

  "webhook_url": "https://merchant-site.com/woocommerce/webhook"

  "customisation": {

   "template_id": "string"

    },

  "configuration": {

 "template_id": "string"

   },

  "customer": {

        "email": "string",

        "phone": "string",

        "billing_address": {

          "first_name": "string",

          "last_name": "string",

          "address_line1": "string",

          "address_line2": "string",

          "address_city": "string",

          "address_state": "string",

          "address_country": "string",

          "address_postcode": "string"             

        },

    }

}

Step 2: Create a Secure Endpoint

The secure endpoint you provided must be configured to receive and process webhook events via a POST request with a JSON payload. It is critical that this endpoint can handle the event data to correctly update the internal order status (e.g., from "pending" to "complete"). For auditing and debugging purposes, all incoming events and the results of their processing must be logged.

Step 3: Process Webhook Events

Your system will receive notifications, known as events, for key stages in the payment lifecycle. You need to be ready to process the following events:

  • Payment Completed (e.g., payment_succeeded);
  • Payment Failed (e.g., payment_failed);
  • Payment Cancelled ( e.g., payment_cancelled);

Event Payload

All webhook events will be sent with a JSON payload. While the exact structure may vary by event, it will contain the following key identifiers:

  • intent_id: The unique ID of the checkout session.
  • event: A string identifying the event type (e.g., "payment_succeeded").
  • event_id: A unique ID for this specific event notification.
  • object_type: The type of object related to the event (e.g., "payment").
  • charge: The charge object.
  • error: The error object (if exists).
  • is_paid: A boolean indicating whether the payment was processed.
  • datetime: The timestamp (ISO 8601) when the event occurred.
  • amount: The transaction amount.
  • currency: The transaction currency.
  • reference: The merchant reference, line 1.
  • reference2: The merchant reference, line 2.

Security and Idempotency

  • Webhook URLs must use HTTPS. All events include a unique event_id and timestamp to protect against replay attacks. A signature mechanism is also used to validate that the event originated from Paydock.
  • Idempotency: Your endpoint must be idempotent, meaning it is safe to process the same event multiple times without error. This is essential because the retry mechanism may send the same event more than once to guarantee delivery. Use the event_id to de-duplicate messages.

Retry Mechanism

Paydock employs a robust, multi-tiered strategy to ensure webhook delivery, even if your system is temporarily unavailable:

  1. Primary Retry:
    • Upon initial delivery failure, an automatic retry policy is engaged.
    • This involves 4 attempts conducted over a very short period, totaling 10 seconds.
  2. Escalated Retry (Persistent Child Workflow):
    • If all primary retries are unsuccessful, the process is escalated.
    • A persistent child workflow continues to retry the delivery for up to 24 hours.
    • Retries use an exponential backoff schedule (e.g., 5 mins, 10 mins, 20 mins...)
  3. Non-Retryable Errors:
    • Paydock does not retry deliveries for permanent errors.
    • These include all 4xx Errors (e.g., "404 Not Found" for an invalid URL or "401 Unauthorized" for authentication failures).