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.

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

WebHook Payload Structure

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",
  }
}

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.

In addition each signature is considered unique, meaning that it also achieves idempotency for the webhook. In cases that you require data to be consumed additional times, you can rely on the signature as a resolution to duplication of events.

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,
  }) {
    this.transactionId = transactionId;
    this.transactionHash = transactionHash;
    this.referenceId = referenceId;
    this.depositAddress = depositAddress;
    this.asset = asset;
    this.amount = amount;
    this.timestamp = timestamp;
  }
}

const raw = {
  eventType: "PG_DEPOSIT",
  data: {
    transactionHash:
      "0x02fc56662f353ebc4300d21690464e0e8afb77edc2329124b9f8b7e341f43896",
    transactionId: "bfd5f586-a706-4d26-8ca1-ea91dbecea2b",
    depositAddress: "0xdac17f958d2ee523a2206206994597c13d831ec7",
    referenceId: "6bf84342-606b-42c4-a3af-d738002e7f18",
    amount: "0.00042142",
    asset: "ETH",
    timestamp: "2020-07-28T13:53:24.674Z",
  },
};

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 Transaction class that holds the payload of the event.

package org.example;

import lombok.Getter;
import lombok.Setter;

@Getter
@Setter
public class Transaction {
    private String transactionId;
    private String transactionHash;
    private String referenceId;
    private String depositAddress;
    private String asset;
    private String amount;
    private String timestamp;

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

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) {
        Transaction transaction = new Transaction(
            "bfd5f586-a706-4d26-8ca1-ea91dbecea2b",
            "0x02fc56662f353ebc4300d21690464e0e8afb77edc2329124b9f8b7e341f43896",
            "6bf84342-606b-42c4-a3af-d738002e7f18",
            "0xdac17f958d2ee523a2206206994597c13d831ec7",
            "ETH",
            "0.00042142",
            "2020-07-28T13:53:24.674Z"
        );

        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); // 0xbc97696ed137dadb3c648bb6291c4234215dad87de19e356f414294e7d6f10a7
        } 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.

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.

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.

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.

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.

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.