Boarding API

The Boarding API enables you, as a Nexi Group partner, to facilitate the onboarding process for new Checkout merchants. This API requires a secret API key with Nexi Group partner privileges. Please note that for testing purposes, we recommend to only use the live-test-key from the LIVE environment.

The onboarding flow in Checkout Portal, which is mandatory for all new merchants, can be customized with prepopulated values using this API. After you have configured the onboarding application using this API, you can send a URL to the merchant that leads to the customized onboarding flow. Or, you can have Nexi Group automatically send the activation link to the admin user you provide through the API.

You can track the status changes of the onboarding by using webhooks.

The code samples contain the test environment's base address. Make sure to replace that base address with the corresponding live environment address.

C#PHPNodeShell

Scroll down for code samples, example requests and responses.
Select a language for code samples from the tabs or the mobile navigation menu.

Create onboarding application

POST /partner/v1/onboarding

Creates a new onboarding application. After a new application has been submitted, you can send the returned verification link (URL) to the merchant or have Nexi Group send it automatically. The merchant can then use the link and complete the signup process in Easy Portal by signing the application.

Parameters

Authorizationstringrequired
The secret API key with Nexi Group partner privileges.

Create onboarding application

C#
PHP
Node
Shell

var client = new RestClient("https://test.api.dibspayment.eu/partner/v1/onboarding");
var request = new RestRequest(Method.POST);
request.AddHeader("content-type", "application/json");
request.AddHeader("Authorization", "REPLACE_KEY_VALUE");
request.AddParameter("application/json", "{\"REPLACE_REQUEST_BODY\":\"REPLACE_REQUEST_BODY\"}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

Request body

applicationobjectrequired
The onboarding application for the new merchant.
- countrystringrequired
  The country where the merchant's company is registered. Possible values are: 'DNK', 'SWE', 'NOR', 'GRL'.
  
  DNK, SWE, NOR, GRL
- currencystringrequired
  The currency to be used in the webshop, for example 'SEK'. Additional currencies can be added in Easy Portal if needed.
- companyobjectrequired
  - organizationNumberstringrequired
    The organization number of the company.
  - vatNumberstringoptional
    The VAT (value-added tax) number of the company.
  - invoiceEmailstringoptional
    An email address to receive invoices.
  - contactPersonobjectoptional
    firstNamestringoptional
    The first name (also known as given name).
    lastNamestringoptional
    The last name (also known as surname/family name).
    phonestringoptional
    The phone number including the country calling code, for example '+46123456'.
    emailstringoptional
    The email address. Activation emails are sent to this address.
  - companyNamestringoptional
    The name of the company.
  - companyAddressstringoptional
    The company address.
  - zipCodestringoptional
    The zip code.
  - citystringoptional
    The name of the city.
  - referenceDetailsarrayoptional
    systemstringoptional
    DnB
    referenceKeystringoptional
    DUNS_NO
    referenceValuestringoptional
- productCodesarrayoptional
  A set of payment options to be supported at the checkout. Possible values are: 'CARD', 'INVOICE', 'SWISH', 'INSTALLMENT', 'VIPPS', 'DANKORT', 'MOBILEPAY', 'PAYPAL'.
- salesCodestringoptional
  A sales code which determines the list of rates to be used.
- webshopobjectoptional
  Defines the merchant's webshop.
  - urlstringoptional
    The complete URL (including protocol) for the webshop. For example, 'https://shop.example.com/'.
  - namestringoptional
    The name of the webshop.
- bankAccountobjectoptional
  - ibanstringoptional
    The IBAN (Internaltional Bank Account Number) of the bank account that will receive the payouts from Nexi Group.
  - swiftstringoptional
    The Swift (BIC) code of the bank that holds the account that will receive the payouts from Nexi Group.
- salesRepPartnerstringoptional
  The full name of the sales representative at the partner company (your company).
- salesRepDibsstringoptional
  The full name of the sales representative at Nexi Group.
- quoteobjectoptional
  - documentNostringrequired
  - currencystringrequired
  - signoninteger (int64)required
  - subscriptioninteger (int64)required
  - paymentOptionsarrayrequired
    itemNostringrequired
    paymentTypestringrequired
    CARD, INVOICE, A2A, INSTALLMENT, WALLET
    paymentMethodsarrayrequired
    paymentMethodProviderstringrequired
    Teller, Arvato, SwishSwedbank, Dankort, PayPal, RatePay, PPRO
    optionalbooleanrequired
    selectedbooleanrequired
    feesarrayrequired
    paymentActionTypestringrequired
    CHARGE, REFUND, DA, MOBILEPAY, SWISH, VIPPS, PAYPAL
    feeTypestringrequired
    AMT, TAMT, QTY, TQTY
    unitPriceinteger (int64)required
    priceVATinteger (int64)required
    itemTypestringrequired
    TRANS, SUB
    paymentMethodVariant1stringoptional
    DEBIT, CREDIT
    paymentMethodVariant2stringoptional
    CONSUMER, CORPORATE
    paymentMethodVariant3stringoptional
    EEA, NON-EEA
- amlCustomerIntroductionTypeobjectoptional
  - introductionTypestringrequired
- notificationsobjectoptional
  Notifications allow you to subscribe to status updates for an application.
  - webhooksarrayrequired
    eventNamestringrequired
    The name of the event you want to subscribe to. See the Onboarding events section for the complete list of events.
    
    onboarding.initiated, onboarding.awaiting_signature, onboarding.signature_failed, onboarding.processing, onboarding.approved, onboarding.abandoned
    urlstringrequired
    The callback is sent to this URL. Must be HTTPS to ensure a secure communication. Maximum allowed length of the URL is 256 characters.
    authorizationstringrequired
    The credentials that will be sent in the HTTP Authorization request header of the callback. Must be between 8 and 32 characters long and contain alphanumeric characters.
merchantIdstringoptional
adminUserobjectrequired
Defines a user with administration privileges for the new merchant account.
- firstNamestringoptional
  The first name (also known as given name).
- lastNamestringoptional
  The last name (also known as surname/family name).
- emailstringrequired
  The email address.
- languagestringoptional
  The interface language to be used in Easy Portal. Possible values are: 'EN_US', 'DA_DK', 'SV_SE', 'NO_NO', 'DE_DE'.
  
  EN_US, DA_DK, SV_SE, NO_NO, DE_DE
- sendActivationEmailbooleanoptional
  Determines whether an activation email (with the activation link included) should be sent automatically to the admin user after the onboarding application has been created. Set this property to false if you want to send the activation link to the new merchant yourself.

Request body

{
    "application": {
        "country": "SWE",
        "currency": "SEK",
        "company": {
            "organizationNumber": "123456-1234",
            "vatNumber": "SE123456123401",
            "invoiceEmail": "invoice@example.com",
            "contactPerson": {
                "firstName": "John",
                "lastName": "Doe",
                "phone": "+46123456",
                "email": "john.doe@example.com"
            },
            "companyName": "A Company",
            "companyAddress": "Solgatan 4",
            "zipCode": "12345",
            "city": "Stockholm"
        },
        "productCodes": [
            "CARD"
        ],
        "salesCode": "string",
        "webshop": {
            "url": "https://shop.example.com/",
            "name": "The Webshop"
        },
        "bankAccount": {
            "iban": "AA00BBBB1111111",
            "swift": "AABBCCDD"
        },
        "salesRepPartner": "Dallas Gray",
        "salesRepDibs": "Charlie Tatum",
        "notifications": {
            "webhooks": [
                {
                    "eventName": "onboarding.initiated",
                    "url": "https://webhookendpoint.example.com/",
                    "authorization": "SECRET"
                }
            ]
        }
    },
    "adminUser": {
        "firstName": "John",
        "lastName": "Doe",
        "email": "admin@example.com",
        "language": "EN_US",
        "sendActivationEmail": true
    }
}

Responses

200SUCCESSoptional
- idinteger (int64)optional
  A numeric identifier of the newly created onboarding application.
- verificationLinkstringoptional
  A URL which can be used by the new merchant in order to verify and sign the new onboarding application. You can send the returned verification link to the merchant or have Nexi Group send it automatically by using the property sendActivationEmail or the method Resend activation code.
- merchantIdstringoptional
  The identifier of the new merchant.
400Bad Requestoptional
401Unauthorizedoptional
500Unexpected Erroroptional
- messagestringoptional
  An internal error message. This message is not meant to be presented to end users. Instead, this message can be logged and used for debugging purposes.
- codestringoptional
  A numeric error code to be used for debugging purposes.
- sourcestringoptional
  The source of the error, for example: 'internal'.

{
    "id": 28625,
    "verificationLink": "https://signup.example.com/",
    "merchantId": "1064fa1e9cc44029ae0480e107cbd32b"
}

Update onboarding application

POST /partner/v1/onboarding/{id}

Updates the specified onboarding application.

Parameters

Authorizationstringrequired
The secret API key with Nexi Group partner privileges.
idstringrequired
The identifier of the onboarding application.

Update onboarding application

C#
PHP
Node
Shell

var client = new RestClient("https://test.api.dibspayment.eu/partner/v1/onboarding/{id}");
var request = new RestRequest(Method.POST);
request.AddHeader("content-type", "application/json");
request.AddHeader("Authorization", "REPLACE_KEY_VALUE");
request.AddParameter("application/json", "{\"REPLACE_REQUEST_BODY\":\"REPLACE_REQUEST_BODY\"}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

Request body

applicationobjectrequired
The onboarding application for the new merchant.
- countrystringrequired
  The country where the merchant's company is registered. Possible values are: 'DNK', 'SWE', 'NOR', 'GRL'.
  
  DNK, SWE, NOR, GRL
- currencystringrequired
  The currency to be used in the webshop, for example 'SEK'. Additional currencies can be added in Easy Portal if needed.
- companyobjectrequired
  - organizationNumberstringrequired
    The organization number of the company.
  - vatNumberstringoptional
    The VAT (value-added tax) number of the company.
  - invoiceEmailstringoptional
    An email address to receive invoices.
  - contactPersonobjectoptional
    firstNamestringoptional
    The first name (also known as given name).
    lastNamestringoptional
    The last name (also known as surname/family name).
    phonestringoptional
    The phone number including the country calling code, for example '+46123456'.
    emailstringoptional
    The email address. Activation emails are sent to this address.
  - companyNamestringoptional
    The name of the company.
  - companyAddressstringoptional
    The company address.
  - zipCodestringoptional
    The zip code.
  - citystringoptional
    The name of the city.
  - referenceDetailsarrayoptional
    systemstringoptional
    DnB
    referenceKeystringoptional
    DUNS_NO
    referenceValuestringoptional
- productCodesarrayoptional
  A set of payment options to be supported at the checkout. Possible values are: 'CARD', 'INVOICE', 'SWISH', 'INSTALLMENT', 'VIPPS', 'DANKORT', 'MOBILEPAY', 'PAYPAL'.
- salesCodestringoptional
  A sales code which determines the list of rates to be used.
- webshopobjectoptional
  Defines the merchant's webshop.
  - urlstringoptional
    The complete URL (including protocol) for the webshop. For example, 'https://shop.example.com/'.
  - namestringoptional
    The name of the webshop.
- bankAccountobjectoptional
  - ibanstringoptional
    The IBAN (Internaltional Bank Account Number) of the bank account that will receive the payouts from Nexi Group.
  - swiftstringoptional
    The Swift (BIC) code of the bank that holds the account that will receive the payouts from Nexi Group.
- salesRepPartnerstringoptional
  The full name of the sales representative at the partner company (your company).
- salesRepDibsstringoptional
  The full name of the sales representative at Nexi Group.
- quoteobjectoptional
  - documentNostringrequired
  - currencystringrequired
  - signoninteger (int64)required
  - subscriptioninteger (int64)required
  - paymentOptionsarrayrequired
    itemNostringrequired
    paymentTypestringrequired
    CARD, INVOICE, A2A, INSTALLMENT, WALLET
    paymentMethodsarrayrequired
    paymentMethodProviderstringrequired
    Teller, Arvato, SwishSwedbank, Dankort, PayPal, RatePay, PPRO
    optionalbooleanrequired
    selectedbooleanrequired
    feesarrayrequired
    paymentActionTypestringrequired
    CHARGE, REFUND, DA, MOBILEPAY, SWISH, VIPPS, PAYPAL
    feeTypestringrequired
    AMT, TAMT, QTY, TQTY
    unitPriceinteger (int64)required
    priceVATinteger (int64)required
    itemTypestringrequired
    TRANS, SUB
    paymentMethodVariant1stringoptional
    DEBIT, CREDIT
    paymentMethodVariant2stringoptional
    CONSUMER, CORPORATE
    paymentMethodVariant3stringoptional
    EEA, NON-EEA
- amlCustomerIntroductionTypeobjectoptional
  - introductionTypestringrequired
- notificationsobjectoptional
  Notifications allow you to subscribe to status updates for an application.
  - webhooksarrayrequired
    eventNamestringrequired
    The name of the event you want to subscribe to. See the Onboarding events section for the complete list of events.
    
    onboarding.initiated, onboarding.awaiting_signature, onboarding.signature_failed, onboarding.processing, onboarding.approved, onboarding.abandoned
    urlstringrequired
    The callback is sent to this URL. Must be HTTPS to ensure a secure communication. Maximum allowed length of the URL is 256 characters.
    authorizationstringrequired
    The credentials that will be sent in the HTTP Authorization request header of the callback. Must be between 8 and 32 characters long and contain alphanumeric characters.

Request body

{
    "application": {
        "country": "SWE",
        "currency": "SEK",
        "company": {
            "organizationNumber": "123456-1234",
            "vatNumber": "SE123456123401",
            "invoiceEmail": "invoice@example.com",
            "contactPerson": {
                "firstName": "John",
                "lastName": "Doe",
                "phone": "+46123456",
                "email": "john.doe@example.com"
            },
            "companyName": "A Company",
            "companyAddress": "Solgatan 4",
            "zipCode": "12345",
            "city": "Stockholm"
        },
        "productCodes": [
            "CARD"
        ],
        "salesCode": "string",
        "webshop": {
            "url": "https://shop.example.com/",
            "name": "The Webshop"
        },
        "bankAccount": {
            "iban": "AA00BBBB1111111",
            "swift": "AABBCCDD"
        },
        "salesRepPartner": "Dallas Gray",
        "salesRepDibs": "Charlie Tatum",
        "notifications": {
            "webhooks": [
                {
                    "eventName": "onboarding.initiated",
                    "url": "https://webhookendpoint.example.com/",
                    "authorization": "SECRET"
                }
            ]
        }
    }
}

Responses

200SUCCESSoptional
400Bad Requestoptional
401Unauthorizedoptional
404Resource Not Foundoptional
500Unexpected Erroroptional
- messagestringoptional
  An internal error message. This message is not meant to be presented to end users. Instead, this message can be logged and used for debugging purposes.
- codestringoptional
  A numeric error code to be used for debugging purposes.
- sourcestringoptional
  The source of the error, for example: 'internal'.

500

{
    "message": "string",
    "code": "string",
    "source": "string"
}

Retrieve application details

GET /partner/v1/onboarding/{id}

Retrieves the details of an existing onboarding application. The id is obtained from the API when creating an application.

Parameters

Authorizationstringrequired
The secret API key with Nexi Group partner privileges.
idstringrequired
The identifier of the onboarding application.

Retrieve application details

C#
PHP
Node
Shell

var client = new RestClient("https://test.api.dibspayment.eu/partner/v1/onboarding/{id}");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "REPLACE_KEY_VALUE");
IRestResponse response = client.Execute(request);

Responses

200SUCCESSoptional
- applicationobjectoptional
  The onboarding application for the new merchant.
  - countrystringrequired
    The country where the merchant's company is registered. Possible values are: 'DNK', 'SWE', 'NOR', 'GRL'.
    
    DNK, SWE, NOR, GRL
  - currencystringrequired
    The currency to be used in the webshop, for example 'SEK'. Additional currencies can be added in Easy Portal if needed.
  - companyobjectrequired
    organizationNumberstringrequired
    The organization number of the company.
    vatNumberstringoptional
    The VAT (value-added tax) number of the company.
    invoiceEmailstringoptional
    An email address to receive invoices.
    contactPersonobjectoptional
    firstNamestringoptional
    The first name (also known as given name).
    lastNamestringoptional
    The last name (also known as surname/family name).
    phonestringoptional
    The phone number including the country calling code, for example '+46123456'.
    emailstringoptional
    The email address. Activation emails are sent to this address.
    companyNamestringoptional
    The name of the company.
    companyAddressstringoptional
    The company address.
    zipCodestringoptional
    The zip code.
    citystringoptional
    The name of the city.
    referenceDetailsarrayoptional
    systemstringoptional
    DnB
    referenceKeystringoptional
    DUNS_NO
    referenceValuestringoptional
  - productCodesarrayoptional
    A set of payment options to be supported at the checkout. Possible values are: 'CARD', 'INVOICE', 'SWISH', 'INSTALLMENT', 'VIPPS', 'DANKORT', 'MOBILEPAY', 'PAYPAL'.
  - salesCodestringoptional
    A sales code which determines the list of rates to be used.
  - webshopobjectoptional
    Defines the merchant's webshop.
    urlstringoptional
    The complete URL (including protocol) for the webshop. For example, 'https://shop.example.com/'.
    namestringoptional
    The name of the webshop.
  - bankAccountobjectoptional
    ibanstringoptional
    The IBAN (Internaltional Bank Account Number) of the bank account that will receive the payouts from Nexi Group.
    swiftstringoptional
    The Swift (BIC) code of the bank that holds the account that will receive the payouts from Nexi Group.
  - salesRepPartnerstringoptional
    The full name of the sales representative at the partner company (your company).
  - salesRepDibsstringoptional
    The full name of the sales representative at Nexi Group.
  - quoteobjectoptional
    documentNostringrequired
    currencystringrequired
    signoninteger (int64)required
    subscriptioninteger (int64)required
    paymentOptionsarrayrequired
    itemNostringrequired
    paymentTypestringrequired
    CARD, INVOICE, A2A, INSTALLMENT, WALLET
    paymentMethodsarrayrequired
    paymentMethodProviderstringrequired
    Teller, Arvato, SwishSwedbank, Dankort, PayPal, RatePay, PPRO
    optionalbooleanrequired
    selectedbooleanrequired
    feesarrayrequired
    paymentActionTypestringrequired
    CHARGE, REFUND, DA, MOBILEPAY, SWISH, VIPPS, PAYPAL
    feeTypestringrequired
    AMT, TAMT, QTY, TQTY
    unitPriceinteger (int64)required
    priceVATinteger (int64)required
    itemTypestringrequired
    TRANS, SUB
    paymentMethodVariant1stringoptional
    DEBIT, CREDIT
    paymentMethodVariant2stringoptional
    CONSUMER, CORPORATE
    paymentMethodVariant3stringoptional
    EEA, NON-EEA
  - amlCustomerIntroductionTypeobjectoptional
    introductionTypestringrequired
  - notificationsobjectoptional
    Notifications allow you to subscribe to status updates for an application.
    webhooksarrayrequired
    eventNamestringrequired
    The name of the event you want to subscribe to. See the Onboarding events section for the complete list of events.
    
    onboarding.initiated, onboarding.awaiting_signature, onboarding.signature_failed, onboarding.processing, onboarding.approved, onboarding.abandoned
    urlstringrequired
    The callback is sent to this URL. Must be HTTPS to ensure a secure communication. Maximum allowed length of the URL is 256 characters.
    authorizationstringrequired
    The credentials that will be sent in the HTTP Authorization request header of the callback. Must be between 8 and 32 characters long and contain alphanumeric characters.
- statusstringoptional
  The current status of the onboarding process. Possible values are: 'INITIATED', 'AWAITING_SIGNATURE', 'SIGNATURE_FAILED', 'PROCESSING', 'APPROVED', 'ABANDONED'.
  
  INITIATED, AWAITING_SIGNATURE, SIGNATURE_FAILED, PROCESSING, APPROVED, ABANDONED
- partnerIdstringoptional
  The partner identifier.
- merchantNumberinteger (int64)optional
  The merchant nummber.
401Unauthorizedoptional
404Resource Not Foundoptional
500Unexpected Erroroptional
- messagestringoptional
  An internal error message. This message is not meant to be presented to end users. Instead, this message can be logged and used for debugging purposes.
- codestringoptional
  A numeric error code to be used for debugging purposes.
- sourcestringoptional
  The source of the error, for example: 'internal'.

{
    "application": {
        "country": "SWE",
        "currency": "SEK",
        "company": {
            "organizationNumber": "123456-1234",
            "vatNumber": "SE123456123401",
            "invoiceEmail": "invoice@example.com",
            "contactPerson": {
                "firstName": "John",
                "lastName": "Doe",
                "phone": "+46123456",
                "email": "john.doe@example.com"
            },
            "companyName": "A Company",
            "companyAddress": "Solgatan 4",
            "zipCode": "12345",
            "city": "Stockholm"
        },
        "productCodes": [
            "CARD"
        ],
        "salesCode": "string",
        "webshop": {
            "url": "https://shop.example.com/",
            "name": "The Webshop"
        },
        "bankAccount": {
            "iban": "AA00BBBB1111111",
            "swift": "AABBCCDD"
        },
        "salesRepPartner": "Dallas Gray",
        "salesRepDibs": "Charlie Tatum",
        "notifications": {
            "webhooks": [
                {
                    "eventName": "onboarding.initiated",
                    "url": "https://webhookendpoint.example.com/",
                    "authorization": "SECRET"
                }
            ]
        }
    }
}

Resend activation code

POST /partner/v1/onboarding/{id}/resendActivation

Sends an activation code to the admin user associated with the specified onboarding application.

Parameters

Authorizationstringrequired
The secret API key with Nexi Group partner privileges.
idstringrequired
The identifier of the onboarding application.

Resend activation code

C#
PHP
Node
Shell

var client = new RestClient("https://test.api.dibspayment.eu/partner/v1/onboarding/{id}/resendActivation");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "REPLACE_KEY_VALUE");
IRestResponse response = client.Execute(request);

Responses

200SUCCESSoptional
- codestringoptional
  A status code. Possible values are: 'EMAIL_SENT', 'USER_ACTIVE', 'NOT_FOUND', 'AUTHENTICATION_REQUIRED'
  
  EMAIL_SENT, USER_ACTIVE, NOT_FOUND, AUTHENTICATION_REQUIRED
- messagestringoptional
  A human readable message describing the status of the activation email.
401Unauthorizedoptional
404Resource Not Foundoptional
500Unexpected Erroroptional
- messagestringoptional
  An internal error message. This message is not meant to be presented to end users. Instead, this message can be logged and used for debugging purposes.
- codestringoptional
  A numeric error code to be used for debugging purposes.
- sourcestringoptional
  The source of the error, for example: 'internal'.

{
    "code": "EMAIL_SENT",
    "message": "Some message."
}

Generate test merchant

POST /partner/v1/onboarding/testaccount

Parameters

Authorizationstringrequired
The secret API key with Nexi Group partner privileges.

Generate test merchant

C#
PHP
Node
Shell

var client = new RestClient("https://test.api.dibspayment.eu/partner/v1/onboarding/testaccount");
var request = new RestRequest(Method.POST);
request.AddHeader("content-type", "application/json");
request.AddHeader("Authorization", "REPLACE_KEY_VALUE");
request.AddParameter("application/json", "{\"REPLACE_REQUEST_BODY\":\"REPLACE_REQUEST_BODY\"}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

Request body

generateUserobjectoptional
- firstNamestringoptional
- lastNamestringoptional
- emailstringrequired
- languagestringoptional
  EN_US, DA_DK, SV_SE, NO_NO, DE_DE
- sendActivationEmailbooleanoptional
- phoneNumberstringrequired

Request body

{
    "generateUser": {
        "firstName": "string",
        "lastName": "string",
        "email": "string",
        "language": "EN_US",
        "sendActivationEmail": true,
        "phoneNumber": "string"
    }
}

Responses

200SUCCESSoptional
- codestringoptional
  A status code. Possible values are: 'EMAIL_SENT', 'USER_ACTIVE', 'NOT_FOUND', 'AUTHENTICATION_REQUIRED'
  
  EMAIL_SENT, USER_ACTIVE, NOT_FOUND, AUTHENTICATION_REQUIRED
- messagestringoptional
  A human readable message describing the status of the activation email.
400Bad Requestoptional
401Unauthorizedoptional
500Unexpected Erroroptional

{
    "code": "EMAIL_SENT",
    "message": "string"
}