Nexo Payment Gateway (1.0.0)

Welcome to the Nexo Payment Gateway API documentation. This API is designed specifically for merchants who have been successfully onboarded onto the Nexo platform. To begin the onboarding process or to access more information, please visit Nexo Onboarding.

The Nexo Payment Gateway API adheres to RESTful principles, ensuring a seamless integration experience. Our API provides predictable, resource-oriented URLs, supports form-encoded request bodies, and returns JSON-encoded responses. It employs standard HTTP response codes, authentication methods, and verbs to facilitate clear and reliable communication between your services and our platform.

Secure authentication is crucial for protecting your data. In the Nexo Payment Gateway API, authentication is handled using an API key. This API key must be included in the header of every request to ensure that the interaction is authorized.

To authenticate API requests, include your API key in the x-api-key header. This header is required for all API calls to verify that the requestor has proper authorization. Failure to include the API key, or using an incorrect or revoked key, will result in a denial of access.

Currently, the Nexo Payment Gateway API does not provide support for a sandbox or test environment. This means that all API calls made will be executed in the live production environment.

We recognize the importance of testing functionalities in a controlled setting without affecting real transactions or data. Plans to introduce a sandbox environment are under consideration, and we will inform all integrated partners once it becomes available.

• Testing Limitations: Absence of a sandbox environment requires any tests to be conducted directly in the production environment, which may impact live data and operations.
• Risk Management: Developers must take extra precautions to handle data and transactions sensitively to avoid unintended consequences during testing.

• Minimize Transaction Volumes: Use minimal transaction amounts when testing payment - processing capabilities to reduce potential risk and impact.
• Monitor Closely: Keep a tight watch on the system for any unexpected behaviors during testing phases.
• Clear Communication: Coordinate with the Nexo Client Care team during planned testing to ensure any potential issues can be managed promptly.

We understand the critical role a sandbox environment plays in effective API integration and are committed to enhancing the experience of our merchant clients. Thank you for your patience, updates will be provided as soon as they are available.

To ensure the security and integrity of data, all requests to the Nexo Payment Gateway API must be sent over HTTPS. This protocol encrypts the data exchanged between the client and the server, providing a secure channel to prevent interception and unauthorized access during transmission.

Currently, the Nexo API does not support Virtual Private Cloud (VPC) tunnelling. If VPC tunnelling is an essential feature for your integration, we encourage you to reach out to our technical support team. We are always looking to evolve our services in ways that best meet the needs of our merchants, and your feedback is invaluable in guiding our feature updates.

Currently Nexo supports the following list of networks and associated assets for the Payment Gateway, with more planned to be added in the future.

Network	Description	Assets
bitcoin	This is the network of Bitcoin.	BTC
ethereum	This is the mainnet network of Ethereum.	ETH, PAXG, USDT, USDC, AAVE
polygon	This is the mainnet network of Polygon.	POL, ETH, USDT, USDC, AAVE
bsc	This is the mainnet network of Binance Smart Chain.	BNB

The Nexo Payment Gateway provides notifications via WebHooks. This feature allows merchants to receive updates about deposits and other significant events directly through HTTPS callbacks, facilitating an automated and efficient response system.

The callback URL for the WebHooks must be configured through the Payment Gateway dashboard, available at Nexo Onboarding. This URL, which is specified during the onboarding process, can be updated at any time as needed:

• HTTPS Requirement: Only HTTPS URLs are accepted to ensure secure data transmission.
• Response Requirements: The endpoint must respond with an HTTP status code in the range of 200-299 to signify successful receipt of the WebHook.
• Response Time: The endpoint must send a response within 10 seconds of receiving the WebHook to avoid timeouts and ensure timely processing.

Below is the structure of the data that Nexo sends to the configured WebHook URL, encapsulated in two primary components - the event type and the data payload.

Event Structure

Property	Type	Description
eventType	string	Specifies the type of WebHook event. For more information, see WebHook Types.
data	object	Contains the payload of the WebHook, detailed in the WebHookPayload structure.

WebHook Payload Structure

Property	Type	Description
transactionId	string	Unique identifier of the transaction within Nexo's system.
transactionHash	string	Blockchain-specific hash associated with the transaction, if applicable.
referenceId	string	Unique identifier associated with the address involved in the transaction.
depositAddress	string	Blockchain address targeted by the deposit operation.
asset	string	Identifier representing the type of asset transferred, e.g "ETH".
amount	string	Amount of the asset transferred, presented with a comma separated value - e.g. “0.2365” ETH.
timestamp	string	Timestamp of when the deposit was detected by Nexo represented in ISO format (UTC).
fiat	object	The fiat information of the transaction. Optional: omitted when no fiat value is available.
usd	object	The fiat information for the said currency.
value	string	The calculated value of the transaction in said currency. - “27.76630856” USD
course	string	The course at the time of the transaction. - “13.88315428” ETH/USD
status	string	Confirmation state of the deposit: "confirmed" for PG_DEPOSIT, "unconfirmed" for PG_UNCONFIRMED_DEPOSIT. Always present, and always the last field of data (after fiat).

Example

{
  "eventType": "PG_DEPOSIT",
  "data": {
    "transactionId": "bfd5f586-a706-4d26-8ca1-ea91dbecea2b",
    "transactionHash": "0x02fc56662f353ebc4300d21690464e0e8afb77edc2329124b9f8b7e341f43896",
    "referenceId": "6bf84342-606b-42c4-a3af-d738002e7f18",
    "depositAddress": "0xdac17f958d2ee523a2206206994597c13d831ec7",
    "asset": "ETH",
    "amount": "0.00042142",
    "timestamp": "2020-07-28T13:53:24.674Z",
    "fiat": {
      "usd": {
        "value": "27.76630856",
        "course": "13.88315428"
      }
    },
    "status": "confirmed"
  }
}

Type	Description
PG_DEPOSIT	A deposit of assets has been done to an address which belongs to the merchant and is confirmed. data.status is "confirmed". This is the only deposit event you should credit.
PG_UNCONFIRMED_DEPOSIT	A deposit of assets to an address which belongs to the merchant has been detected, but is not yet confirmed. data.status is "unconfirmed". Informational only, never credit on this event. See Unconfirmed Deposits.

A PG_UNCONFIRMED_DEPOSIT event is sent to the same webhook URL as PG_DEPOSIT, as soon as an incoming deposit is detected and before it is confirmed. It has the same structure as PG_DEPOSIT, with data.status set to "unconfirmed". It lets you show a pending deposit to your customer early.

{
  "eventType": "PG_UNCONFIRMED_DEPOSIT",
  "data": {
    "transactionId": "bfd5f586-a706-4d26-8ca1-ea91dbecea2b",
    "transactionHash": "0x02fc56662f353ebc4300d21690464e0e8afb77edc2329124b9f8b7e341f43896",
    "referenceId": "6bf84342-606b-42c4-a3af-d738002e7f18",
    "depositAddress": "0xdac17f958d2ee523a2206206994597c13d831ec7",
    "asset": "ETH",
    "amount": "0.00042142",
    "timestamp": "2020-07-28T13:53:24.674Z",
    "fiat": {
      "usd": {
        "value": "27.76630856",
        "course": "13.88315428"
      }
    },
    "status": "unconfirmed"
  }
}

Rules for handling unconfirmed deposits:

• Never credit on PG_UNCONFIRMED_DEPOSIT. The event is informational only. Credit your customer only when you receive PG_DEPOSIT (data.status is "confirmed").
• No ordering guarantee. PG_UNCONFIRMED_DEPOSIT may arrive after the PG_DEPOSIT of the same deposit. It may also never be followed by a PG_DEPOSIT. Ignore an unconfirmed event for a deposit you have already received as confirmed.
• Chain reorganisations. After a chain reorganisation the confirmed deposit may carry a different transactionId than the unconfirmed one. Correlate the two by transactionHash and depositAddress, not by transactionId alone.
• Deduplication. Deduplicate events on the pair (eventType, transactionId). Do not deduplicate on the signature, because the signature is calculated per event (see WebHook Integrity).
• Not every network emits unconfirmed deposits. Do not rely on receiving PG_UNCONFIRMED_DEPOSIT before PG_DEPOSIT.
• Enabling and disabling. PG_UNCONFIRMED_DEPOSIT webhooks are enabled by default for newly onboarded merchants. They are controlled by the sendUnconfirmedDepositWebhooks setting of your merchant account.
• Field changes. data.status is a signed field of every deposit event. It is always the last field of data, after fiat. Make sure your signature verification includes it (see WebHook Integrity).

Overview

To ensure the integrity and security of WebHook events, Nexo incorporates an X-SIGNATURE header with every event. This cryptographic signature allows you, as the merchant, to verify that the event has not been altered or tampered with during transmission.

The signature is calculated over the whole event, so it is specific to a single event: a redelivery of the same event carries the same signature, while a different event has a different signature. A single deposit can produce more than one event, for example PG_UNCONFIRMED_DEPOSIT and later PG_DEPOSIT, and these have different signatures. For that reason do not use the signature as the only mechanism to deduplicate deposits. Deduplicate on the pair (eventType, transactionId) instead.

When you re-serialise the event to verify the signature, keep the field order exactly as documented, and omit fields that are absent from the received event (for example fiat). Do not add null values for them.

Signature Verification Process

The integrity verification is performed by recalculating the SHA256 hash of the event using a Shared Secret, which is a unique key generated for each merchant upon onboarding. This process ensures that the event you receive is exactly what was sent by Nexo without any alterations.

Steps for Verifying WebHook Integrity

1. Retrieve the Event: Capture the incoming WebHook event and parse it into a structured type. For instance, in JavaScript, you might convert it into an object or class instance.

class Event {
  constructor({ eventType, data }) {
    this.eventType = eventType;
    this.data = new Transaction(data);
  }
}

class Transaction {
  constructor({
    transactionId,
    transactionHash,
    referenceId,
    depositAddress,
    asset,
    amount,
    timestamp,
    fiat,
    status
  }) {
    this.transactionId = transactionId;
    this.transactionHash = transactionHash;
    this.referenceId = referenceId;
    this.depositAddress = depositAddress;
    this.asset = asset;
    this.amount = amount;
    this.timestamp = timestamp;
    // fiat is optional and may be absent. Do not set the property when it is missing,
    // so that JSON.stringify omits it, exactly like the original event.
    if (fiat) {
      this.fiat = new Fiat(fiat);
    }
    // status must stay after fiat, the order of the fields is part of the signature.
    this.status = status;
  }
}
class Fiat {
  constructor({ usd }) {
    this.usd = new FiatValue(usd);
  }
}
class FiatValue {
  constructor({ value, course }) {
    this.value = value;
    this.course = course;
  }
}

const raw = {
  eventType: "PG_DEPOSIT",
  data: {
    transactionId: "NXT7Z2qAw4SFZpQaOyjZjak9B",
    transactionHash:
      "0x02fc56662f353ebc4300d21690464e0e8afb77edc2329124b9f8b7e341f43896",
    depositAddress: "0xdac17f958d2ee523a2206206994597c13d831ec7",
    referenceId: "6bf84342-606b-42c4-a3af-d738002e7f18",
    amount: "0.00042142",
    asset: "ETH",
    timestamp: "2020-07-28T13:53:24.674Z",
    fiat: {
      usd: {
        value: "27.76630856",
        course: "13.88315428"
      }
    },
    status: "confirmed"
  },
};

const event = new Event(raw);

2. Obtain the Shared Secret: Access your Shared Secret from the Nexo Payment Gateway dashboard. This secret is crucial for the hash calculation.

const secret = "YourSharedSecretFromNexo";

3. Concatenate the Event and Shared Secret: Convert the parsed event back to a string, append a delimiter (typically a forward slash “/”), and then append the Shared Secret.

const data = `${JSON.stringify(event)}/${secret}`;

4. Compute the SHA256 Hash: Apply a SHA256 hashing algorithm to the concatenated string from the previous step. Ensure that the hashing implementation is secure and follows cryptographic standards.

const computedSignature = `0x${crypto
    .createHash("sha256")
    .update(data)
    .digest("hex")}`;

5. Compare the Signatures: Extract the `X-SIGNATURE`` from the headers of the received event and compare it against your locally computed signature.

let receivedSignature = receivedHeaders["X-SIGNATURE"];
if (receivedSignature === computedSignature) {
    console.log("Signature verified successfully.");
} else {
    console.log("Warning: Signature mismatch detected!");
}

Java Example

Define an Event class that holds the structure of the event.

package org.example;

import lombok.Getter;
import lombok.Setter;

@Getter
@Setter
public class Event {
    private String eventType;
    private Transaction data;

    public Event(String eventType, Transaction data) {
        this.eventType = eventType;
        this.data = data;
    }
}

Define a CurrencyData class that holds the fiat currency data of the event.

package org.example;
import lombok.Getter;
import lombok.Setter;

@Getter
@Setter
public class CurrencyData {
    private String value;
    private String course;

    public CurrencyData(String value, String course) {
        this.value = value;
        this.course = course;
    }
}

Define a FiatData class that holds the fiat currency.

package org.example;
import lombok.Getter;
import lombok.Setter;

@Getter
@Setter
public class FiatData {
    private CurrencyData usd;

    public FiatData(CurrencyData usd) {
        this.usd = usd;
    }
}

Define a Transaction class that holds the payload of the event.

package org.example;

import com.fasterxml.jackson.annotation.JsonInclude;
import lombok.Getter;
import lombok.Setter;
import java.util.Map;

@Getter
@Setter
// fiat is optional: a null value must be omitted from the serialized event, like in the original event
@JsonInclude(JsonInclude.Include.NON_NULL)
public class Transaction {
    private String transactionId;
    private String transactionHash;
    private String referenceId;
    private String depositAddress;
    private String asset;
    private String amount;
    private String timestamp;
    private FiatData fiat;
    // status must stay after fiat, the order of the fields is part of the signature
    private String status;


    public Transaction(String transactionId, String transactionHash, String referenceId,
                      String depositAddress, String asset, String amount, String timestamp, FiatData fiat, String status) {
        this.transactionId = transactionId;
        this.transactionHash = transactionHash;
        this.referenceId = referenceId;
        this.depositAddress = depositAddress;
        this.asset = asset;
        this.amount = amount;
        this.timestamp = timestamp;
        this.fiat = fiat;
        this.status = status;
    }
}

Signature creation.

package org.example;

import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.util.HexFormat;
import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.ObjectMapper;

public class Main {
    public static void main(String[] args) {

        CurrencyData usdCurrencyData = new CurrencyData("27.76630856", "13.88315428");

        FiatData fiatData = new FiatData(usdCurrencyData);

        Transaction transaction = new Transaction(
            "NXT7Z2qAw4SFZpQaOyjZjak9B",
            "0x02fc56662f353ebc4300d21690464e0e8afb77edc2329124b9f8b7e341f43896",
            "6bf84342-606b-42c4-a3af-d738002e7f18",
            "0xdac17f958d2ee523a2206206994597c13d831ec7",
            "ETH",
            "0.00042142",
            "2020-07-28T13:53:24.674Z",
            fiatData,
            "confirmed"
        );

        Event event = new Event("PG_DEPOSIT", transaction);

        String secret = "9a994da63491f3ed5abcb948f9d1976dac831742";

        try {
            String serializedEvent = new ObjectMapper().writeValueAsString(event);
            String data = serializedEvent + "/" + secret;
            String signature = "0x" + sha256Hex(data);
            System.out.println(signature); // 0x60303773ccbd594d70225c84e9e7d9844fdbcf57f3b0781fb52cc86ec2bbb6d7
        } catch (JsonProcessingException e) {
            System.out.println("Error serializing the event.");
        } catch (NoSuchAlgorithmException e) {
            System.out.println("SHA-256 algorithm not available.");
        }
    }

    public static String sha256Hex(String data) throws NoSuchAlgorithmException {
        MessageDigest digest = MessageDigest.getInstance("SHA-256");
        byte[] hash = digest.digest(data.getBytes(StandardCharsets.UTF_8));
        return HexFormat.of().formatHex(hash);
    }
}

Nexo utilizes standard HTTP response codes to signify the success or failure of an API request. Here is a general guideline:

• Codes in the 2xx range signal successful operations.
• Codes in the 4xx range indicate client-side errors, often due to incomplete or incorrect submission of information (such as missing a required parameter or failing authentication).
• Codes in the 5xx range point to rare server-side errors within Nexo's systems.

Code	Status	Description
200	OK	The request has been processed successfully.
400	Bad Request	The request could not be processed due to incorrect input.
401	Unauthorized	Authentication failed, likely due to an invalid API key.
500, 502, 503, 504	Server Errors	An issue occurred on Nexo's side. (These instances are uncommon.)

This section explains how to handle 4xx errors based on the type field. To handle 5xx errors, please use the status field, as this is a Server Error. Errors returned by our API are accompanied by a unique identifier in the type field of the error response. This identifier is a URL linking to a specific section of our documentation that describes potential reasons for the error. While the full URL in the type field can be used directly, we recommend utilizing the last segment of this URL as a concise error identifier for easier handling.

When the API encounters a BadRequest, it means that the request could not be processed due to incorrect input. This typically occurs when the passed parameters violate the constraints described for a specific endpoint.

Identifier	Code	Title	Description
bad_request_error	400	Bad Request	The request could not be processed due to incorrect input.

Recommendation: Review and assess the parameters you`ve passed, keeping in mind the specific endpoint restrictions outlined in the Nexo Payment API documentation. Ensure that all inputs meet the required conditions for successful API calls.

When the API returns an Unauthorized error, it indicates that the request has failed due to invalid authentication credentials. This is typically because the API key provided is missing or invalid. Authentication issues prevent the server from determining if you are authorized to access the requested resources.

Identifier	Code	Title	Description
unauthorized	401	Unauthorized	The request lacks valid credentials for authentication.

Recommendation: Ensure you verify your API keys per the API documentation guidelines. Proper management of credentials is crucial to maintaining the security and integrity of your API interactions.

When the API returns a MerchantNotOnboarded error, it means that the merchant account is either not fully set up or the requested asset is not supported. This error often indicates that the merchant has not completed all necessary onboarding steps or that the asset involved is not available for deposit address creation through the API.

Identifier	Code	Title	Description
merchant_not_onboarded	400	Bad Request	Merchant not onboarded, or asset not supported.

Recommendation: Verify that the merchant account is fully onboarded and check the list of supported assets. Ensure that all required setup processes are complete and that the assets you are attempting to create address with are supported by the API.

When the API encounters an InternalServerError, it indicates a problem with the API's servers that prevents it from fulfilling the request. This error is a general catch-all response for when the server encounters an unexpected condition that prevents it from completing the request.

Identifier	Code	Title	Description
internal_server_error	500	Internal Server Error	Internal backend server error.

Recommendation: This is usually a temporary issue. Retry your request after a few minutes. If the problem persists, contact our support team for assistance and provide them with the relevant details of your request.

Welcome to the Release Notes section of our API documentation! This space is dedicated to providing you with detailed and up-to-date information about the latest versions of our API. Each set of release notes is designed to help you understand what has changed, how these changes may impact your applications, and how you can take advantage of new features and improvements.

What You Will Find Here

• New Features: Discover the latest functionalities we've added to enhance your development experience and expand your application's capabilities.
• Enhancements: Learn about updates and optimizations that improve existing features, boosting performance and stability.
• Deprecated Features: Stay informed about any features that are being phased out or replaced, including important dates and migration tips to ensure a smooth transition.
• Bug Fixes: Get insights into minor and major issues that have been resolved in each new version.
• Known Issues: Be aware of ongoing issues that we are currently addressing, and find temporary workarounds to keep your application running smoothly.
• Migration Guides: Access detailed instructions and recommendations on how to upgrade your application to the latest version, ensuring compatibility and taking full advantage of new enhancements.

We recommend reviewing the release notes with each new version of our API to stay informed about changes that could impact your projects.

Thank you for choosing our API, and happy coding!

Version 1.0.0

This initial release establishes the foundation of our API with a focus on reliability, security, and ease of use. We provide you with robust tools and flexible endpoints to manage data, integrate complex functionalities, and enhance user experiences. As this is the first version, we are especially eager to hear from you. Your feedback is invaluable and will be directly used to shape future versions of this API.

What You Will Find in This Documentation

• Getting Started Guide: A straightforward introduction that will help you set up and make your first API call.
• Authentication: Detailed information on how to securely connect to our API, including step-by-step instructions.
• Endpoint Descriptions: Comprehensive details of each available API endpoint, including request and response formats, query parameters, and usage examples to help you understand how to interact with our API effectively.
• Error Codes and Messages: An exhaustive list of potential errors, their meanings, and suggested solutions to help you troubleshoot common issues quickly.

Your input is crucial to us. If you have suggestions, experience issues, or just want to share how you're using the API, please reach out to us. We are committed to continuously improving our services to meet your needs and expectations.

Operations related to the assets supported by the API, including listing available assets and providing detailed information about each asset's characteristics.

Operations concerning the creation and management of deposit addresses. A deposit address provides a blockchain address, tailored to facilitate distinct transactions per entity via a unique referenceId.

Workflow:

• One or more deposit addresses are generated based on the provided referenceId.
• These addresses are associated with specific blockchain transactions, and their creation invokes WebHook events, which notify you at a configured URL about transaction activities.
• A deposit address remains unique to the referenceId across blockchains of the same family. This means that repeating a referenceId in a request within the same blockchain family will return the previously generated address.

Benefits:

• Streamlined Transactions: Each entity interacts through a unique blockchain address, enhancing tracking and management of individual transactions.
• Consistent Address Reuse: For blockchains within the same family, a single address can be reused for entities across different sessions or interactions, reducing the need to generate multiple addresses and simplifying the entity's experience.
• Notifications: Updates via WebHooks ensure timely responses to all transaction activities related to the deposit addresses.

Restrictions:

• Reference Identifier: Reference Identifier (referenceId) is versatile, but some basic constraints are placed:
  • Up to 50 Characters in length can be passed.
  • Only Latin characters [aA-zZ], numbers [0-9], dashes (-), backslashes (), underscore (_).