Webhooks

  What are Webhooks

Webhooks are user-defined HTTP callbacks. Paidy uses Webhooks as an additional way of notifying you about payment-related events and token-related events. A webhook endpoint is the URL to which you want to receive event notifications. Once you register a URL as a webhook endpoint, Paidy will send notifications to that URL whenever an event occurs related to your account.

There are several benefits to using Webhooks:

  • Data synchronization: When you register a URL as a webhook endpoint, Paidy will send near real-time notifications to that URL as events take place. This allows you to synchronize the data with other services not directly responsible for making the API request that may need to know the result of the request.
  • Device failure: When using Paidy Checkout, the result of the payment authorization is provided to your callback function, which when executed returns the payment ID to your front-end server. In the very rare event that a consumer's mobile connection drops before completing the checkout process, you will still receive a webhook notifying you of a successful authorization.
  • Monitoring: Since Webhooks provides an additional way receiving events related to your account, you can monitor these notifications for specific events and you can then execute custom code after a specific event happens. For example, some merchants use these webhook notifications to trigger capture requests or cancel requests.

While you can use Paidy without Webhooks, we highly recommend its use. In the rare event that a callback does not get executed when a payment is authorized, Webhooks adds resilience. Conversely, Webhooks should not be the only method used; both the JavaScript callback function and Webhooks are an important part of the payment process and we strongly recommend that you implement both methods.

How does it work

webhooks overview

  • When you send a request to Paidy, we processes the request and return a response containing an HTTP status code and either the new object (upon success) or an error object (upon failure).
  • If Webhooks is set up, Paidy also creates an event object and sends it to your webhook endpoint via an HTTP POST request. The POST request will contain data (formatted as JSON) relevant to the event.
  • You must acknowledge receipt of the webhook by returning a 200 HTTP status code. No response or a response other than 200 will indicate an error to Paidy.

Supported events

Paidy sends webhook notifications in the following cases.

  • EVENT TYPE

    WEBHOOK EVENT

    TRIGGER

  • Payment event

    authorize_success

    A payment was created with status AUTHORIZED.

  • capture_success

    A payment was captured. When a payment is captured, Paidy will also send the close_success webhook notification.

  • close_success

    A payment was closed. A payment can be closed by capture, or by cancellation.

  • refund_success

    A payment was refunded.

  • update_success

    A payment was updated through an Update payment API request.

  • Token event

    activate_success

    A token was created with status ACTIVE.

  • suspend_success

    A token was suspended.

  • resume_success

    A suspended token was resumed.

  • delete_success

    A token was deleted.

Please note, we may add webhooks for new event types at any time, so you may receive additional notifications to the ones listed here.

Latency & retries

We send a webhook notification any time an event occurs related to one of your payments or tokens. Typically you will receive the notification in near real-time, however, a webhook notification may fail (timeout) due to network latency.

For failed webhook notifications, we will try to resend the notification. There is an exponential interval between attempts, and the final retry attempt will be sent approximately 5 hours after the first retry attempt. While we are processing retry attempts, Paidy will continue to process and send webhook notifications for other payment events as they occur.

  Integrating Webhooks

You can set up and test Webhooks in 3 simple steps.

  • Register the URL for the webhook endpoint in the Merchant Dashboard. If you want to receive webhooks for test requests, you must also enter a test webhooks URL.
  • Make sure the IP addresses are not blocked and can send messages to your webhook endpoint(s). Paidy sends webhook notifications from the following IP addresses:
    • 13.114.134.35
    • 13.113.94.100
    • 18.182.135.232
    • 52.199.50.20
    • 52.199.62.26
  • Send a test message from the Merchant Dashboard to verify that you entered the correct URL and that your URL is receiving webhook notifications.

Optional configuration

Webhooks are asynchronous, their order is not guaranteed, and idempotency might lead to a duplicate notification of the same event type. For these reasons, you may also want to configure your system for the following:

  • When Webhooks is implemented, you will automatically receive notifications for all payment events. You can filter the notifications and only process the webhooks that you want.
  • Webhooks are not guaranteed to be in any particular order. For example, a capture event might be delivered after an authorization event for the same paym
  • You may receive multiple copies of the same webhook notification. You should configure your system to ignore webhooks that you have already processed.

Webhooks for test accounts

We send webhooks for test requests to a test webhooks URL. If you do not set this up in the Merchant Dashboard, Webhooks will be ignored for test requests.

  Using Webhooks

Receiving webhook notifications

Once you register a webhook endpoint, Paidy posts data to the URL every time an event occurs. The request will contain JSON data relevant to the event.

Payment-related notifications

  • PARAMETER

    DESCRIPTION

  • payment_id

    Paidy payment ID.

  • capture_id

    Paidy capture ID. (Only sent for capture and refund events.)

  • event_type

    Paidy only sends webhooks for payment events. Set to "payment". (To determine what type of payment event, refer to the status field.)

  • status

    Indicates both the type of payment event and the result of the request. Valid values for this field are:
    authorize_success
    capture_success
    refund_success
    update_success
    close_success

  • order_ref

    Merchant’s own unique reference for the order.

  • reason

    Reason for the refund. (Only sent for refund events.)

  • timestamp

    Date and time in UTC that the event was created, displayed in ISO 8601 format.

For example, the webhook notification for a successful capture payment event would be:


    {
        "payment_id":"pay_WFDYLhEAAEQA42Dw",
        "capture_id":"cap_WFIk5yIAACIAC6n3",
        "status":"capture_success",
        "event_type": "payment",
        "order_ref": "88e021674",
        "timestamp":"2018-06-15T05:06:47.189Z"
    }

Currently, the response contains both an event_datetime field and a timestamp field. Please use timestamp; the event_datetime field has been deprecated and will be removed at some point in the future.

Token-related notifications

  • PARAMETER

    DESCRIPTION

  • token_id

    Paidy token ID, beginning with tok_.

  • status

    Indicates both the type of event and the result of the request. Valid values for this field are:
    activate_success
    suspend_success
    resume_success
    delete_success

  • timestamp

    Date and time in UTC that the event was created, displayed in ISO 8601 format.

For example, the webhook notification for a successful resume token event would be:


    {
        "token_id":"tok_WK5KjCEAAA0RvPp9",
        "status":"resume_success",
        "timestamp":"2018-06-15T05:06:47.189Z"
    }

Responding to webhook notifications

To acknowledge receipt of a webhook, your endpoint should return a 200 HTTP status code. Paidy only accepts a 200 HTTP status code. If Paidy receives an HTTP status code other than 200 or no response within 10 seconds, we will try re-sending that notification.

  Best practices

Payment verification

When a payment is authorized, Webhooks returns the payment ID to your backend. Before saving the payment ID, you must verify the payment data to ensure the data is valid and wasn't tampered with.

This verification is an important security measure that you must not skip.

The verification process is:

  1. Send a retrieve payment request from your backend system to the /payments/{id} endpoint, where {id} is the payment ID. If the request is successful, Paidy returns the full payment object.
  2. Verify the payment object data matches the data you sent to Paidy Checkout. In particular, you must check the amount field.
  3. If the data matches, the payment is valid. If the data doesn’t match, close the payment.

Test Webhooks

The two most common mistakes with webhooks are:

  • Registering the wrong URL in the Merchant Dashboard
  • Not returning a 200 status code for a webhook notification within 10 seconds

Please test your system to make sure that both of these are implemented correctly.