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:
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:
|GET||Retrieves a resource (idempotent, will never mutate a resource)|
|POST||Creates a new resource. A JSON object, provided by you, describes the resource.|
|PUT||Updates an existing resource. A JSON object, provided by you, describes the changes.|
You can pass parameters to the Nets Easy 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 Nets Easy 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 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:
- 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.
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
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 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:
|USD||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
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:
|Country||ISO Code||Phone Prefix|
|Antigua & Barbuda||ATG||1|
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 method||Payment type|
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 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
<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:
The following list shows the most important error codes and their meaning.