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:
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
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:
|Retrieves a resource (idempotent, will never mutate a resource)
|Creates a new resource. A JSON object, provided by you, describes the resource.
|Updates an existing resource. A JSON object, provided by you, describes the changes.
You can pass parameters to the Checkout APIs using:
- Header parameters. For example, the
Authorizationheader specifying the private API key is always sent as an HTTP header.
- Path parameters. For example, the numerical payment identifier
paymentIdin the path
- Query parameters. For example, the
fromDateparameter in the request
- 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.
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:
- A client sends a POST request to the server.
- The request reaches the server and creates a new charge object on the server.
- The server also charges the customer's payment card.
- 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
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:
- Bulk charge subscriptions using the property
- Verify subscriptions using the property
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:
|United 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
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:
|Antigua & Barbuda
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:
The following languages can be used on the checkout page:
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 18.104.22.168/30
- Sandbox 22.214.171.124/30
Checkout JS SDK - embedded checkout
<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:
The following list shows the most important error codes and their meaning.
Acquirer response codes on failing reservations
The following list shows the most common acquirer response codes and their meaning.
|Do not honor
|Stolen card, pick-up
|Not sufficient funds
The following list shows all possible acquirer response codes and their meaning.
|Refer to card issuer
|Refer to card issuer’s special conditions
|Invalid merchant or service provider
|Pick-up, Capture card
|Do not honor
|Pick-up card, special condition (other than lost/stolen card)
|Honour with identification
|Request in progress
The codes follow the standards of ISO 8583-1987. You can read more about it from here.