API guide

The API works this way:

• You register a webhook URL
• We send updates and information to the webhook URL you have specified

Register a webhook

Webhooks can send out events for the Recurring API, ePayment API, and QR API.

To get information from us, you first make a POST:/webhooks/v1/webhooks request to register the webhook for the events you want from us, and you then receive updates and information for the specified events to the URL you provided.

You can subscribe to get notifications whenever an event happens. For example, if you want to know when a payment is captured, subscribe for this event.

Code example

To receive a message for each Authorized payment, send the following HTTP POST request:

POST:/webhooks/v1/webhooks

In the body, specify the "epayments.payment.authorized.v1", as shown in the Event table for ePayment. Also, specify the url of the web server where we should send the webhook notifications. For example:

{
   "url":"https://example.com/webhooks-receiver",
   "events":[
      "epayments.payment.authorized.v1"
   ]
}

You will receive a response similar to this, confirming that the webhook registration was successful:

{
   "id":"497f6eca-6276-4993-bfeb-53cbbbba6f08",
   "secret":"090a478d-37ff-4e77-970e-d457aeb26a3a"
}

Use the secret to authenticate the webhook notifications with HMAC, as described in Request authentication.

Once a notification is authenticated, you will be able to receive its payload. This is sent as a POST request to the url you registered. For example:

{
   "msn":"123456",
   "reference":"24ab7cd6ef658155992",
   "pspReference":"1234567891",
   "name":"AUTHORIZED",
   "amount":{
      "currency":"NOK",
      "value":35000
   },
   "timestamp":"2023-08-14T12:48:46.260Z",
   "idempotencyKey":"49ca711a9487112e1def",
   "success":true
}

Each API determines the format of their payloads. The payload from an ePayment API's webhook is shown on the ePayment API: Webhooks page.

Retries

Failed webhook notifications are retried with an exponential backoff for up to 7 days. After all retries are exhausted, the notification is never sent again. This applies to both new and previously created webhooks.

The delivery order of failed webhook notifications is guaranteed in order per registered webhook. That means your server needs to accept all preceding requests for a given payment, before any new notifications can be received for the same payment.

For example, if you reply with HTTP 500 Server Error to an authorization notification, a new notification about the same payment being captured will not be sent unless you reply with a successful HTTP status code, like HTTP 200 OK, to one of the retry attempts.

Any response with HTTP status code in range 4-5xx will result in a retry. Delay between retries will be progressively slower to not overwhelm receivers.

Partner webhooks

As a partner, you can access endpoints with your usual key, client ID, and secret, without MSN. Any webhooks registered by a partner will trigger for the subscribed events from ANY merchant registered the given partner.