Documentation

1. Getting Started

To begin accepting crypto payments, you need to sign up for a merchant account, completing your KYB, and generate your API key from the dashboard. Our API is designed to be simple and robust, allowing for quick integration with minimal effort. This guide will walk you through the essential steps.

Our SDKs for popular languages are coming soon. In the meantime, you can use our REST API directly with any HTTP client. All requests must be authenticated with your API key in the `x-api-key` header.

2. Process overview

2.1. Preface

In the following documentation, we will be assuming that you are integrating a platform that provides goods or services with MakeNanoWork. You would be using MakeNanoWork to accept payments made with Nano (XNO) from customers. The word "customer" will be reused to refer to customers of your platform.

Before starting any payment process, please be reminded that it is your responsibility to ensure that customers fully understand the steps required to complete a payment. MakeNanoWork is not liable for any issues arising from customer errors, such as customers sending funds multiple times, using an incorrect address, utilizing an expired payment link, or any misuse of your application. Refunds will not be issued under these circumstances.
In the event of a technical issue, please contact our support team immediately, we will do all we can to resolve the issue promptly.

2.2. Capabilities

There is no limit to how many payments you can make, however please know that for bigger transaction volumes, legal compliance actions might be required. A payment is considered accepted if it meets the following criteria:
1. The amount exceeds the minimum threshold of 0.1 XNO. Any amount below this threshold will be irretrievably lost.
2. MakeNanoWork will not accept payments above 1000XNO without prior consultation.
3. If the link was created with an expected amount, the received amount must match exactly.
4. If the link was created with a maximum amount, the received amount must be less than or equal to the specified value.
5. The transaction blocks on the blockchain are confirmed.
Full refunds will be issued to customers in two scenarios: if the Nano forward address is removed during the payment process, or if the customer sends an amount that does not match the required value.

2.3. Payment flows

MakeNanoWork operates as a server API and is intended for use exclusively with your backend server. Exposing your API key to client-side applications will most certainly compromise the security of your account.

The payment process begins with a request to the MakeNanoWork API for a temporary Nano payment address. Customers will send their Nano to this generated address to complete the payment. These temporary addresses (referred to as "links") can be customized with additional data to help identify the order, basket, or user associated with the transaction. Each link has a maximum lifespan of 30 minutes and includes a unique Nano account address, which should be used only once. You should ensure your customers send money using a correct, valid link.

Through your management panel, you can configure a forward address and a webhook URL. Once the customer currency is received, MakeNanoWork will forward it to this forward address, minus the operating fee. Upon successful transfer, a webhook call will be triggered only once to the address you configured, if you did configure one. In any case, you can verify the status of your payment links using our API. Each link has a unique ID, which should be stored in your database for future reference and interaction with the API.

Here's an illustrated overview of the payment process:

* (1) Optionally include relevant metadata: Provide any metadata that will assist in identifying the cart, customer, or invoice associated with the transaction being processed.
* (2) Webhook Notification on success: The webhook will be triggered exclusively upon successful processing. It will include the same data as the GET API response, including any additional metadata submitted as part of the initial request (as outlined in point 1).
* (3) Polling for processing status: To monitor the status of the transaction, you may poll the designated API endpoint. It is advisable to limit polling to instances where the customer is actively awaiting the completion of the process. A polling interval of every 2 seconds is recommended for optimal performance. Once the funds have been received by MakeNanoWork (received_at), it is recommended to conceal the XNO account to prevent the customer from inadvertently sending multiple payments.

2. Integration

2.1. Creating a payment link

Creating a link will generate work on the node. Because of that, please only generate a link when you are certain your customer will make a purchase with Nano. Request-intensive apps with low payment completion uses a lot of resources and may result in a reduced operation velocity.

All dates used in responses are at UTC time.

POST https://www.makenano.work/api/links

{
    metadata: Json, // Any JSON value that will help you identify the purchase made. You can also set a secret for the Webhook call. Can be an object.
    expires_at: Date or Null, // By default, links have a lifespan of 30 minutes. Allowed values are from 10 to 40 minutes from current time.
    expected_amount: Float // If you are expecting a specific amount to be paid for the purchase set this value here in Nano (>= 0,1). This value will be truncated to two decimals maximum.
    maximum_amount: Float // If you want to cap the amount to be received, use this field (>= 0.1, <= 1000).
}
                        

{
    id: Uuid, // Unique identifier of your payment link
    exposed_xno_account_address: String, // The Nano account your customer must send the currency to, as string
    metadata: Value, // The same data that you sent in the metadata field during the request
    expires_at: Date, // Date at which the link will expire. Funds sent after this date will be disregarded.
    expected_amount_raw: String or Null, // Same value than expected_amount in the request in raw
    received_at: Date or Null, // If the customer's payment has been received by MakeNanoWork, this field will contain the reception date. Funds sent after this date will be disregarded.
    forwarded_at: Date or Null, // If the customer's payment was successful, this is the date at which the send block to your forward account has been created
    refunded_at: Date or Null, // If the customer was refunded for any reason, this is the date at which the refund was sent.
    transaction_finished_at: Date or Null, // Independently of the success of the payment, this value is set when the flow finishes
    maximum_amount_raw: String, // The maximum amount this link will accept in raw
}
                        

2.2. Retrieving a payment link

Constant polling of a link for tracking progress is not recommended. You can poll a link every few seconds if your customer is actively waiting for updates on the payment. For general use, it is highly recommended to use the Webhook to base your business logic on.

GET https://www.makenano.work/api/links/{uuid}

{
    id: Uuid, // Unique identifier of your payment link
    exposed_xno_account_address: String, // The Nano account your customer must send the currency to, as string
    metadata: Value, // The same data that you sent in the metadata field during the request
    expires_at: Date, // Date at which the link will expire. Funds sent after this date will be disregarded.
    expected_amount_raw: String or Null, // Same value than expected_amount in the request in raw
    received_at: Date or Null, // If the customer's payment has been received by MakeNanoWork, this field will contain the reception date. Funds sent after this date will be disregarded.
    forwarded_at: Date or Null, // If the customer's payment was successful, this is the date at which the send block to your forward account has been created
    refunded_at: Date or Null, // If the customer was refunded for any reason, this is the date at which the refund was sent.
    transaction_finished_at: Date or Null, // Independently of the success of the payment, this value is set when the flow finishes
    qrcode: String, // Same as exposed_xno_account_address as a base64 encoded PNG
    received_amount: Float or Null, // If a payment from the customer has been received and is valid, this is the amount received by MakeNanoWork in Nano
    received_amount_raw: String or Null // If a payment from the customer has been received and is valid, this is the amount received by MakeNanoWork in raw Nano
    maximum_amount_raw: String, // The maximum amount this link will accept in raw
}
                        

2.3. Webhooks

Upon successful payment, currency will be transferred to your forward address. As a result, the link values forwarded_at and transaction_finished_at are set to the current date.
After the transfer, the webhook call is triggered. Responding to this call with a code 200 within 5 seconds is required to mark it as succeeded.

POST {your-webhook-url}

{
    id: Uuid, // Unique identifier of your payment link
    exposed_xno_account_address: String, // The Nano account your customer must send the currency to, as string
    metadata: Value, // The same data that you sent in the metadata field during the request
    expires_at: Date, // Date at which the link will expire. Funds sent after this date will be disregarded.
    expected_amount_raw: String or Null, // Same value than expected_amount in the request in raw
    received_at: Date or Null, // If the customer's payment has been received by MakeNanoWork, this field will contain the reception date. Funds sent after this date will be disregarded.
    forwarded_at: Date or Null, // If the customer's payment was successful, this is the date at which the send block to your forward account has been created
    refunded_at: Date or Null, // If the customer was refunded for any reason, this is the date at which the refund was sent.
    transaction_finished_at: Date or Null, // Independently of the success of the payment, this value is set when the flow finishes
    received_amount: Float or Null, // If a payment from the customer has been received and is valid, this is the amount received by MakeNanoWork in Nano
    received_amount_raw: String or Null // If a payment from the customer has been received and is valid, this is the amount received by MakeNanoWork in raw Nano
    maximum_amount_raw: String, // The maximum amount this link will accept in raw
}
                        

4. Support

MakeNanoWork is production-ready but also very new. Therefore, any report, feedback, or feature request will be examined as we will go a long way to provide the best experience possible. Please, do not hesitate to reach out as we will do the necessary to answer your questions and solve your issues swiftly at no additional cost.