Nets Easy API reference

    The Nets Easy APIs provide a secure way to add online payments to your website or application by sending JSON over HTTPS.

    One-time payments and subscriptions are carried out using the Payment API. Payouts from your customers are reported in the Easy Portal. In addition, you can use the Reporting API to programmatically retrieve information about payouts. The Checkout JS SDK allows you to embed a custom checkout page on your website.

    This is the complete API reference for the Nets Easy APIs.

    Environments and base addresses

    All communication between your site and Nets Easy is managed over HTTPS. The Easy REST APIs are collected under the following base addresses:

    EnvironmentBase address
    Testhttps://test.api.dibspayment.eu
    Livehttps://api.dibspayment.eu

    Requests and responses

    The Nets Easy APIs follow the RESTful architectural style. A set of resources can be accessed using some of the endpoints provided by the APIs. To retrieve, add, or update resources, you use the associated HTTP methods for these actions:

    MethodDescription
    GETRetrieves a resource (idempotent, will never mutate a resource)
    POSTCreates a new resource. A JSON object, provided by you, describes the resource.
    PUTUpdates an existing resource. A JSON object, provided by you, describes the changes.

    Parameters

    You can pass parameters to the Nets Easy APIs using:

    • Header parameters. For example, the Authorization header specifying the private API key is always sent as an HTTP header.
    • Path parameters. For example, the numerical payment identifier paymentId in the path /v1/payment/{paymentId}.
    • Query parameters. For example, the fromDate parameter in the request /v1/payouts?fromDate=2020-09-10.
    • JSON objects. Some requests, typically POST and PUT, expect you to pass JSON objects to the Nets Easy APIs.

    Authentication

    All API requests are required to include a valid Authorization header. This header should contain your secret API key for the environment (Test or Live) you are currently using. For more information, please see the articles Access your integration keys and Use the test environment.

    The secret API key should only be passed between your server and a Nets Easy endpoint. The secret API key should never be used from the client side of your site / app for security reasons.

    Retries and idempotent keys

    Most HTTP methods are idempotent, meaning that sending the same HTTP request multiple times to the server will not change the state of the server. In case of a network failure, it is always safe to retry an idempotent request. However, POST requests usually create new resources on the server side and cannot be retried safely by default. Using an idempotency key makes it safe for clients to retry POST requests that failed due to network failures.

    POST methods and network failures

    To understand the potential problem of POST requests and network failures, consider the following flow between an HTTP client and a Nets server when charging a customer:

    1. A client sends a POST request to the server.
    2. The request reaches the server and creates a new charge object on the server.
    3. The server also charges the customer's payment card.
    4. The client's network become unreachable and the response from the server never reaches the client.

    In this state, the client doesn't know whether or not a charge object has been created. Also, the client did not receive a chargeId back from the server, so there is no way for the client to check whether the charge object has been created. The client could potentially send a new HTTP POST request, asking the server to create a new charge, but that would run the risk of charging the customer's payment card twice.

    The solution to this problem is to have the client generate a unique idempotency key. The client adds this key to the initial HTTP POST request and on subsequent retries. The server can use the idempotency key to detect whether the client is sending a retry to avoid performing the same operation multiple times on the server. If a retry was detected, the server will respond with the same HTTP status code and response object (if any) as it did the first time.

    Using idempotency keys to enable retries

    The POST methods in the Easy APIs that support idempotency keys all accept a header called Idempotency-Key. Use this header parameter to pass an idempotency key to the server to enable safe retries and avoid the risk of creating multiple resources or charges by mistake. The value of the Idempotency-Key parameter should be a unique string with a maximum length of 63 characters.

    We highly recommend that you add idempotency keys to all POST methods that accepts the Idempotency-Key header.

    Using external identifiers to enable retries

    Some methods in the Payment API support safe retries by using an external identifier instead of an idempotency key. These external identifiers are very similar to the Idempotency-Key header but are instead provided explicitly in the request body of the POST request. The two places where external identifiers are use are:

    The value of the external identifer should be a unique string with a maximum length of 63 characters.

    Data types and formats

    Nets Easy APIs uses the data types and data formats as defined in OpenAPI specification.

    Date and time

    All date and time strings should be formatted according to the definition of date-time in RFC3339, unless otherwise specified. For example, the string 2021-03-23T15:30:55.23Z represents 30 minutes and 55.23 seconds after the 15th hour of March 23rd, 2021 in UTC.

    Currency and amount

    Currency should always be specified using a 3-letter code (ISO-4217). The following table lists all currencies supported by Nets Easy:

    CodeCurrency
    DKKDanish krone
    EUREuro
    GBPPound sterling
    NOKNorwegian krone
    SEKSwedish krona
    USDUnited States dollar

    Amounts are specified in the lowest monetary unit for the given currency, without punctuation marks. For example: 100,00 NOK is specified as 10000 and 9.99 USD is specified as 999.

    Country codes and phone prefixes

    Country codes and phone prefixes are both used in the checkout. Country codes are used when limiting the set of countries available for shipping. Phone prefixes appear in the consumer data object and other locations.

    The following table lists all countries supported by Easy:

    CountryISO CodePhone Prefix
    AfghanistanAFG93
    AlbaniaALB355
    AlgeriaDZA213
    AndorraAND376
    AngolaAGO244
    Antigua & BarbudaATG1
    ArgentinaARG54
    ArmeniaARM374
    AustraliaAUS61

    Localization

    The following languages can be used on the checkout page:

    TagLanguage
    en-GBEnglish (default)
    da-DKDanish
    nl-NLDutch
    fi-FIFinnish
    fr-FRFrench
    de-DEGerman
    nb-NONorwegian
    pl-PLPolish
    es-ESSpanish
    sv-SESwedish

    The tag combines an ISO 639-1 language code with an ISO 3166-1 country code.

    Languages can be specified using the Checkout JS SDK for embedded web integrations or by appending a language parameter to the hosted checkout URL when using a hosted checkout integration.

    Webhooks

    Webhooks (or HTTP callbacks) allow you to subscribe to different events that affect a payment and to be notified directly when these events happen. When an event occurs in Easy, for example, a charge is made or a payment is refunded, this event can be sent along with the associated data.

    Webhooks are the most robust and efficient way of keeping your backend in sync with Nets Easy. It is robust against various runtime failures (network failures and other temporary processing failures) and efficient since it avoids polling Nets Easy for state changes.

    We highly recommend that you use webhooks when integrating Nets Easy on your site. See the complete Webhooks reference for more information about the events that can be subscribed to.

    Checkout JS SDK - embedded checkout

    The Checkout JS SDK is a JavaScript library that dynamically creates a checkout page embedded in an iframe on your site. Your site defines a container element (typically a <div>) in which the JS library generates an <iframe> element which embeds the checkout page. The library manages all communication between the frontend of your site and Nets Easy. Checkout.js should be loaded from the following URLs:

    EnvironmentJavaScript URL
    Testhttps://test.checkout.dibspayment.eu/v1/checkout.js?v=1
    Livehttps://checkout.dibspayment.eu/v1/checkout.js?v=1