API Reference

Webhooks

Listen for events on your Payssion account to automatize the integration of your business.

Configure methods

Payssion offers these two ways to configure the URL address for receiving callback notifications.

Fixed configuration (Recommended)

Based on a Webhook endpoint URL, multiple events can be configured against it. The following are the currently supported webhook event types.

EventEvent Description
payment.succeededOccurs whenever a payment is succeeded.
payment.failedOccurs whenever a payment is failed.
refund.succeededOccurs whenever a refund is succeeded.
mandate.succeededOccurs whenever a mandate is succeeded.
mandate.canceledOccurs whenever a mandate is canceled.
subscription.createdOccurs whenever a subscription is created.
subscription.canceledOccurs whenever a subscription is canceled.
subscription.completedOccurs whenever a subscription is completed.
payout.succeededOccurs whenever a payout is succeeded.
payout.canceledOccurs whenever a payout is canceled.
payout.failedOccurs whenever a payout is failed.

Dynamic configuration

For some objects(Payment, Refund, Mandate only) that support the notify_url parameter, it is allowed to send a callback URL on this parameter, for which Payssion will send notifications on all events triggered. If notify_url is specified, no webhooks will be sent to webhook endpoint URL. Only https URLs are supported in livemode mode.

It is strongly recommended that this parameter is only applicable to debugging scenarios.

Retry Schedule

Payssion webhooks have built-in retry methods for 3xx, 4xx, or 5xx response status codes. If Payssion doesn’t quickly receive a 2xx response status code for an event, we would try to send it to your endpoint several more times until 2xx response is returned.

The retry backoff strategy is 5s, 10s, 2min, 5min, 10min, 30min, 1h, 2h, 6h, and 12h. Totally 10 times at most.

Sample Webhook Event Data

{
    "object": "event",
    "livemode": true,
    "type": "subscription.created",
    "data": {
        "object": {
            "id": "sub_Sq1e1OqvnP8CmzbP",
            "object": "subscription",
            "livemode": true,
            "reference": null,
            "customer_id": "cst_mDqj5S5CiXDCrbPi",
            "email": "test@customer.com",
            "mandate_id": "mdt_XfLSSGyDC8041aPi",
            "amount": "2.00",
            "currency": "USD",
            "description": "test",
            "time_created": "2022-09-19T15:00:13+08:00",
            "time_start": "2022-09-19T15:00:13+08:00",
            "time_current_period_start": null,
            "time_current_period_end": null,
            "interval_unit": "day",
            "times": 3,
            "times_completed": 0,
            "extra": {},
            "metadata": {},
            "status": "created"
        }
    },
    "request": "iar_b1CCi9W9GmfPOmjfP44a1Wb5",
    "account": "acct_yz50aD",
    "time_created": "2022-10-25T09:49:09+08:00"
}

Verifying Signatures

To make sure that the webhook message you receive is actually from Payssion, you need to verify its signature. The methods are as follows:

  1. First get the signature value in the Payssion-Signature header.
  2. Get webhook event data as payload message data, should be in JSON format.
  3. Compute an HMAC with the SHA256 hash function, use the webhook endpoint’s signing secret as the key(For dynamical notify_url, use API key as signing secret), and use the payload string as the message.
  4. Compare the signatures.

e.g. 

$signature = \hash_hmac('sha256', $payloadInJson, $signingSecret);

📘

Best Practices

Payssion will try its best to push webhooks, but we can't rule out a few cases that can't be delivered in time, so please make sure to interface with the Retrieve interface and call it according to the reasonable time interval of the business itself, in order to make sure to get the final transaction result.