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:
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 or no response within 10 seconds 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.