Invoices

Use the endpoints below to create new invoices. When a new invoice is created, the "Created" status is assigned to it.

Once the invoice is created, the backend begins tracking incoming payments on the blockchain and updates the status and other attributes accordingly.

The following statuses could be assigned to an invoice:

StatusDescription

Created

Initial status for new invoices

Paid or SimplePaid

The payment was successfully processed on the blockchain

OverPaid

Error, the amount provided by the customer is greater than the amount of invoice

UnderPaid

Error, the amount provided by the customer is lower than the amount of invoice

Expired

Error, the invoice is expired and can no longer be processed

Invalid

Generic internal error during invoice processing

Create an invoice

POST <api>/integration/invoices

Create a new invoice returning its identifier.

Headers

NameTypeDescription

x-api-key*

string

API Key

x-api-sig*

string

Signature created using API Secret

x-api-ts*

string

Timestamp of the request

Request Body

NameTypeDescription

metadata

string

Custom metadata for invoice

amount*

string

Amount in tokens, e.g "100.12 btBUSD"

expiresAt*

string

Date/time when invoice expires (in ISO 8601 format)

Response:
// Invoice
- invoice [required, object]
  // Amount with token code
  - amount [required, string]
  // Invoice creation date/time
  - createdAt [required, string]
  // Invoice creation block
  - createdAtBlock [required, array]
    // Mined block number
    - blockNum [required, number, format:int64]
    // Blockchain network code
    - blockchain [required, string]
  // Expiration date/time
  - expiresAt [required, string]
  // Identifier of this invoice
  - id [required, string, format:uuid]
  // Identifier of this invoice
  - paymentAddress [required, string, format:uuid]
  // Sequence number corresponding for this invoice
  - sequenceNumber [required, string, format:uuid]
  // Invoice status
  - status [required, string, format:enum]
  // Paid date/time
  - paidAt [optional, string]
  // Paid amount
  - paidAmount [optional, string]
  // Error code (when invoice is in error state)
  - errorCode  [optional, string]
  // External metadata
  - metadata   [optional, string]



Example 1 (status is "Created"):
{
    "invoice": {
        "amount": "11 btBUSD",
        "createdAt": "2021-06-21T14:44:58.098725Z",
        "createdAtBlock": [
            {
                "blockNum": 8492543,
                "blockchain": "BinanceMainNet"
            },
            {
                "blockNum": 9929784,
                "blockchain": "BinanceTestNet"
            }
        ],
        "expiresAt": "2021-06-22T20:19:38.146071Z",
        "id": "5d51062e-52a1-4aa3-9616-2d5835f32634",
        "paymentAddress": "0x6838a1756d1e08782b33721e3881d7f6ccc24525",
        "sequenceNumber": 3032,
        "status": "Created",
        "metadata": "User defined data"
    }
}

Example 2 (status is "Paid"):
{
    "invoice": {
        "amount": "15 bBUSD",
        "companyId": 1,
        "createdAt": "2021-05-10T21:44:27.174323Z",
        "createdAtBlock": [
            {
                "blockNum": 8292344,
                "blockchain": "BinanceMainNet"
            }
        ],
        "expiresAt": "2021-05-10T23:44:24.051837Z",
        "id": "a44797d6-82f9-4a38-9598-7dda8cb5ca97",
        "paidAmount": "15 bBUSD",
        "paidAt": "2021-05-10T22:44:23.051Z",
        "paymentAddress": "0xb1468d715d21ba1ed57b172f3b4bc2d8ae4dd0d3",
        "sequenceNumber": 45,
        "status": "Paid"
    }
}

You can get invoice details and status using the method below.

Get invoice

GET <api>/integration/invoices/<id>

Returns the invoice details by id.

Path Parameters

NameTypeDescription

id*

string

Invoice Id (uuid)

Response:
// Invoice
- invoice [required, object]
  // Amount with token code
  - amount [required, string]
  // Invoice creation date/time
  - createdAt [required, string]
  // Invoice creation block
  - createdAtBlock [required, array]
    // Mined block number
    - blockNum [required, number, format:int64]
    // Blockchain network code
    - blockchain [required, string]
  // Expiration date/time
  - expiresAt [required, string]
  // Identifier of this invoice
  - id [required, string, format:uuid]
  // Identifier of this invoice
  - paymentAddress [required, string, format:uuid]
  // Sequence number corresponding for this invoice
  - sequenceNumber [required, string, format:uuid]
  // Invoice status
  - status [required, string, format:enum]
  // Paid date/time
  - paidAt [optional, string]
  // Paid amount
  - paidAmount [optional, string]
  // Error code (when invoice is in error state)
  - errorCode  [optional, string]
  // External metadata
  - metadata   [optional, string]



Example 1 (status is "Created"):
{
    "invoice": {
        "amount": "11 btBUSD",
        "createdAt": "2021-06-21T14:44:58.098725Z",
        "createdAtBlock": [
            {
                "blockNum": 8492543,
                "blockchain": "BinanceMainNet"
            },
            {
                "blockNum": 9929784,
                "blockchain": "BinanceTestNet"
            }
        ],
        "expiresAt": "2021-06-22T20:19:38.146071Z",
        "id": "5d51062e-52a1-4aa3-9616-2d5835f32634",
        "paymentAddress": "0x6838a1756d1e08782b33721e3881d7f6ccc24525",
        "sequenceNumber": 3032,
        "status": "Created"
    }
}

Example 2 (status is "Paid"):
{
    "invoice": {
        "amount": "15 bBUSD",
        "companyId": 1,
        "createdAt": "2021-05-10T21:44:27.174323Z",
        "createdAtBlock": [
            {
                "blockNum": 8292344,
                "blockchain": "BinanceMainNet"
            }
        ],
        "expiresAt": "2021-05-10T23:44:24.051837Z",
        "id": "a44797d6-82f9-4a38-9598-7dda8cb5ca97",
        "paidAmount": "15 bBUSD",
        "paidAt": "2021-05-10T22:44:23.051Z",
        "paymentAddress": "0xb1468d715d21ba1ed57b172f3b4bc2d8ae4dd0d3",
        "sequenceNumber": 45,
        "status": "Paid"
    }
}

Last updated