Notifications

Receive notifications about any changes related to your payments.

About notifications

The Unzer API gives you a convenient way to receive customized notifications from the Unzer system: webhooks.

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 the standard HTTP/1.1 protocol.

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

Set up your webhooks

Step 1: Whitelist the Unzer IPs

All Unzer API webhook events come from one of the following IP addresses:

• 3.120.62.83
• 18.196.35.212

Step 2: Prepare your API

Make your RESTful API ready for the Unzer API notifications.

API requirements

Your RESTful API needs to:

• Accept text/plain content type requests
• Respond with the standard HTTP 200 OK success code, to prevent notification resends
• Have no security checks (e.g. HTTP basic authentication)

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:

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 3: Register your URL and choose your event types

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

Make a webhooks POST call, with the following parameters in the request body:

POST https://api.unzer.com/v1/webhooks
{
  "url": "https://www.yourApiUrl.de/notifications",
  "event": "all"
}

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.de/notifications",
  "event": "all"
}

response:
{
  "id": "s-whk-1",
  "event": "all",
  "url": "https://www.yourApiUrl.de/notifications"
}

Selected event types

To get notified about selected event types, use eventList:

POST https://api.unzer.com/v1/webhooks
{
  "url": "https://www.yourApiUrl.de/notifications",
  "eventList": [
      "authorize", "charge", "types"
  ]
}

{
    "events": [
        {
         "id": "s-whk-2",
         "url": "https://www.yourApiUrl.de/notifications",
         "event": "authorize"
       },
       {
         "id": "s-whk-3",
         "url": "https://www.yourApiUrl.de/notifications",
         "event": "charge"
       },
       {
         "id": "s-whk-4",
         "url": "https://www.yourApiUrl.de/notifications",
         "event": "types"
       }
    ]
}

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

For information on managing your webhooks, go to Webhooks.