alt

Important information

There was an update of Unzer TLS/SSL certificates. Learn more

Unzer

Notifications

Receive notifications about any changes related to your payments.

Overview

Unzer supports notifications for payment events that you can configure as webhooks.

Webhooks are individually defined HTTP callbacks from one website to another. They can go either way and are usually triggered by events. To keep your app or website up to date with any changes happening to your payments, you can register a webhook triggered by relevant events. To send notifications, we’re using the standard HTTP/1.1 protocol.

For the full list of webhook events supported by the Unzer API, go to Supported webhook events.

icon info
To get the updated state of a resource
  • Don’t use the event name as an indicator of the state of a resource. To get the latest state of the resource, you should always fetch the resource using the Unzer API.
  • Don’t use the event’s retrieveUrl to fetch the event’s resource without making sure the domain is legit.
  • Always fetch the event by creating an API request for the affected resource with correct Unzer API domain.

Step 1: Prepare your API

Besides the basic requirements, your API should also fulfill the following:

  • Accept text/plain content-type requests
  • Respond with the standard HTTP 200 OK success code, to acknowledge a received notification and prevent sending it again.

Notification examples

You’ll get notifications based on your public key, as a JSON payload. For example:

{
   "event":"types",
   "publicKey":"s-pub-xxxxxxxxxx",
   "retrieveUrl":"https://api.unzer.com/v1/types/card/s-crd-88xu7qjboupc"
}
{
  "event":"payment.pending",
  "publicKey":"s-pub-xxxxxxxxxx",
  "retrieveUrl":"https://api.unzer.com/v1/payments/s-pay-774",
  "paymentId":"s-pay-774"
}

Error handling

If our system doesn’t receive the standard HTTP 200 OK success code within 20 seconds, it tries to resend the notification in the following intervals:

Retry attempt Interval
1 1-2 minutes after the initial webhook event
2 5-6 minutes after the 1st retry attempt
3 10-11 minutes after the 2nd retry attempt
4 30-31 minutes after the 3rd retry attempt
5 60-61 minutes after the 4th retry attempt
6-16 (10 times) Every 60 minutes

If your API doesn’t respond after the last retry attempt, the notification gets marked as undeliverable, and you can’t retrieve it anymore.

Step 2: Register event notification

Register a URL to which you want to get notifications and specify the events that you want to get notified about.

Selected event types

To enable notifications for selected event use event key. For example to trigger notifications for all charge related events:

POST https://api.unzer.com/v1/webhooks
{
  "url": "https://www.yourApiUrl.com/notifications",
  "event": "charge"
}
{
  "id": "s-whk-1",
  "event": "charge",
  "url": "https://www.yourApiUrl.com/notifications"
}

To enable notifications for multiple events with one request use eventList:

POST https://api.unzer.com/v1/webhooks
{
  "url": "https://www.yourApiUrl.com/notifications",
  "eventList": [
      "authorize", "types"
  ]
}
{
    "events": [
        {
         "id": "s-whk-3",
         "url": "https://www.yourApiUrl.com/notifications",
         "event": "authorize"
       },
       {
         "id": "s-whk-4",
         "url": "https://www.yourApiUrl.com/notifications",
         "event": "types"
       }
    ]
}

You can’t declare both event and eventList in a single request.

All events

To get notified about every single event, set event to all, for example:

POST https://api.unzer.com/v1/webhooks
{
  "url": "https://www.yourApiUrl.com/notifications",
  "event": "all"
}
{
  "id": "s-whk-2",
  "event": "all",
  "url": "https://www.yourApiUrl.com/notifications"
}

Step 3: Manage webhooks

Using Unzer API webhooks endpoint you can retrieve, update and delete your webhooks.

Retrieve webhooks

To retrieve an existing webhook, make a webhooks GET call with the webhook’s ID in the URL:

GET https://api.unzer.com/v1/webhooks/s-whk-1
{
  "id": "s-whk-1"
  "url": "https://www.yourApiUrl.com/notifications",
  "event": "charge"
}

To retrieve all of your existing webhooks, make a webhooks GET call with no webhook ID:

GET https://api.unzer.com/v1/webhooks
{
    "events": [
        {
            "id": "s-whk-1",
            "url": "https://www.yourApiUrl.com/notification",
            "event": "charge"
        },
        {
            "id": "s-whk-2",
            "url": "https://www.yourApiUrl.com/notification",
            "event": "all"
        },
        {
            "id": "s-whk-3",
            "url": "https://www.yourApiUrl.com/notification",
            "event": "authorize"
        },
        {
            "id": "s-whk-4",
            "url": "https://www.yourApiUrl.com/notification",
            "event": "types"
        }
    ]
}

Update webhooks

To update the URL for an existing webhook, make a webhooks PUT call, with the webhook’s ID in the URL and your new URL in the request body.

PUT https://api.unzer.com/v1/webhooks/s-whk-1

{
  "url": "https://www.yourApiUrl.com/notification?event=charge"
}

{
  "id": "s-whk-1",
  "event": "charge",
  "url": "https://www.yourApiUrl.com/notification?event=charge"
}

Delete webhooks

To delete an existing webhook, make a webhooks DELETE call, with the webhook’s ID in the URL:

DELETE https://api.unzer.com/v1/webhooks/s-whk-1
{
   "id": "s-whk-1"
}

To delete all of your existing webhooks, make a webhooks DELETE call with no webhook ID:

DELETE https://api.unzer.com/v1/webhooks
{
    "events": [
        {
            "id": "s-whk-1"
        },
        {
            "id": "s-whk-2"
        },
        {
            "id": "s-whk-3"
        },
        {
            "id": "s-whk-4"
        }
    ]
}

For more details on Unzer API webhook calls, see the API Reference.

See also