Boarding API

Enables Easy partners to get customers up and running fast, with minimal manual work.

Method URI Description Response class
POST /partner/v1/onboarding Onboard New Merchant Status 201
POST /partner/v1/onboarding/{id} Perform updates on a initiated onboarding process Status 201
GET /partner/v1/onboarding/{id} Get status of a initiated onboarding process Status 201

Boarding Webhooks

Get transaction information with webhooks

Webhooks enable partners to get notified when certain events regarding an onboarding process occur. When you subscribe to a webhook, Easy will try to send an HTTP POST request to the specified URL until the server responds with a 200 OK status code. If the server responds with anything else, or times out, a certain number of trials are made with increased time between each attempt.


Configuring webhooks for an onboarding application

Webhooks are configured per onboarding application and specified either in the initiate onboarding process or the update onboarding process requests. Webhook data in these requests must have the following structure.

{
    "application": {   
        ...
        "notifications": {
            "webhooks": [{
                    "eventName": "onboarding.initiated",
                    "url": "https://www.example.com/callback/",
                    "authorization": "authorizationToken"
                }
            ]
        }
    }
    ...
}

Receiving a callback

It is very easy to receive a webhook. Just set up a new endpoint on the preferred site and read the JSON body of the request to get the event data.

C# code example:

public async Task<ihttpactionresult> Post()
{
	var content = await Request.Content.ReadAsStringAsync();
	dynamic eventData = JsonConvert.DeserializeObject(content);
	return Ok();
}

Note that, the webhooks need to be sent over HTTPS when designing the endpoint.


Callback content

The callback requests you will receive has the following structure.

{
    "id": "fd70g9f82f9f423fa5f776092ee673c9",
    "merchantId": "1064fa1e9cc44029ae0480e107cbd32b",
    "merchantNumber": 12345,
    "timestamp": "2018-10-12T13:26:15.472Z",
    "event": "onboarding.signature_failed",
    "data": {
        "onboardingId": 106,
        "status": "SIGNATURE_FAILED",
        "reason: "expired"
    }
}

DATASTRING PARAMETERS

 

Supported events for webhooks

Event Description
onboarding.initiated The onboarding application has been initiated and can be edited and submitted.
onboarding.awating_signature The onboarding application has been submitted and is in the signing process.
onboarding.signature_failed The signing process failed for one of multiple reasons.
onboarding.processing The onboarding application has been signed by the merchant and is in the review process.
onboarding.approved The onboarding application has been approved.
onboarding.abandoned The onboarding application has been abandoned, either due to signing failing or application getting rejected.

 

Notifications

Parameter Type Description
webhooks webhook List of webhooks the merchant wants to register for the payment. Maximum number of webhooks is 32.

 

Webhook parameters - Configure Webhook

Parameter Type Description
event string The callback will be triggered for this payment event. See list for valid events.
url string The callback is sent to this url on the merchant site. Must be https. Maximum length is 256 characters.
authorization string Authorization header of the callback sent to the merchant site will be set to this value. Must be between 8 and 32 characters long and alphanumeric.

 

Webhook parameters - Callback content

Parameter Description
id The unique callback id, which is a 32 character long string.
merchantId The merchant ID, which is a 32 character long string.
merchantNumber The merchant number, which is returned only for INITIATED status
timestamp The time when the event has occurred.
event An identifier for the event that has occurred, which is one of the identifiers listed under the supported events for webhooks.
data Some data of the onboarding application.
onboardingId The ID of the onboarding application, which is a number.
status The status of the onboarding application, which is one of the following values:
* INITIATED
* AWAITING_SIGNATURE
* PROCESSING
* SIGNATURE_FAILED
* APPROVED
* ABANDONED
reason This field is only returned when the signing failed, it can have one of the following values:
* failed
* expired
* cancelled

 

Do you have a question or need help?
Follow us
DIBS Payment Services
Stockholm +46 (0)8-527 525 00
Göteborg +46 031-600 800
København +45 7020 3077
Oslo +47 21 55 44 00
Close menu