Skip to content
Checkout
    Operational status

    Checkout API reference

    The Checkout 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 Nexi Checkout 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 Checkout APIs.

    Environments and base addresses

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

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

    Cryptographic protocol

    The following is a list of supported TLS versions and ciphers suites that Nexi Checkout API endpoint supports. Both Checkout production and sandbox endpoints support the same TLS versions and cipher suites:

    Version TLS 1.2
    TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
    TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
    TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
    TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
    TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
    TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
    TLS_RSA_WITH_AES_256_GCM_SHA384
    TLS_RSA_WITH_AES_128_GCM_SHA256
    TLS_RSA_WITH_AES_256_CBC_SHA256
    TLS_RSA_WITH_AES_128_CBC_SHA256
    TLS_RSA_WITH_AES_256_CBC_SHA
    TLS_RSA_WITH_AES_128_CBC_SHA

    Requests and responses

    The Checkout 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 Checkout 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 Nexi Checkout APIs.

    Maximum string length

    The string type parameter of JSON posts sent to our API is limited to 128 characters. The only exception is Checkout.URL which allows up to 256 characters.

    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 Nexi Checkout 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.

    It is important to note here that there must be created individual unique idempotency keys for each charge and refund actions. This means that for the use cases of a partial charge or partial refund on the same order will not be allowed unless it has two individual unique idempotency keys.

    Using idempotency keys to enable retries

    The POST methods in the Checkout 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 identifier should be a unique string with a maximum length of 63 characters.

    Data types and formats

    The Checkout 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 Checkout:

    CodeCurrency
    DKKDanish krone
    EUREuro
    GBPPound sterling
    NOKNorwegian krone
    SEKSwedish krona
    USDUnited States dollar
    PLNZłoty
    CHFSwiss franc
    CZKKoruna

    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.

    Entering the amount 100 corresponds to 1 unit of the currency entered, such as e.g. 1 NOK.

    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 Nexi Checkout:

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

    Payment methods

    You can retrieve the payment method and the payment type by using the method Retrieve payment from the Payment API. The following table lists all possible values:

    Payment methodPayment type
    AmExCARD
    ArvatoINVOICE
    DankortCARD
    MasterCardCARD
    MobilePayWALLET
    Apple PayWALLET
    PayPalWALLET
    RatePayInvoiceINVOICE
    ExpressBankINVOICE

    Localization

    The following languages can be used on the checkout page:

    TagLanguage
    en-GBEnglish (default)
    da-DKDanish
    nl-NLDutch
    ee-EEEstonian
    fi-FIFinnish
    fr-FRFrench
    de-DEGerman
    it-ITItalian
    lv-LVLatvian

    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 the Checkout, 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 Checkout. It is robust against various runtime failures (network failures and other temporary processing failures) and efficient since it avoids polling Checkout for state changes.

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

    The following public IP ranges are used for sending webhooks:

    • Production 20.103.218.104/30
    • Sandbox 20.31.57.60/30

    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 Checkout. 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

    Error Codes

    The following list shows the most important error codes and their meaning.

    CodeDescription
    1000Unknown
    1001OverCharge
    1002ZeroCharge
    1003NotReserved
    1004AlreadyReserved
    1005AmountDiffersFromOrderItems
    1006ConsumerNotAddedToPayment
    1007PartialCancelNotAllowed
    1008AlreadyCharged

    Acquirer response codes on failing reservations

    The following list shows the most common acquirer response codes and their meaning.

    CodeDescription
    1aSCA
    05Do not honor
    41Lost card
    43Stolen card, pick-up
    51Not sufficient funds
    59Suspected fraud
    99Internal error

    The following list shows all possible acquirer response codes and their meaning.

    CodeDescription
    1Refer to card issuer
    2Refer to card issuer’s special conditions
    3Invalid merchant or service provider
    4Pick-up, Capture card
    5Do not honor
    6Error
    7Pick-up card, special condition (other than lost/stolen card)
    8Honour with identification
    9Request in progress

    The codes follow the standards of ISO 8583-1987. You can read more about it from here.

    You can also check out re-attempts from here and the payment.reservation.failed webhook from here.

    Was this helpful?

    What was your feeling about it?