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:

Status	Description
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

Name	Type	Description
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

Name	Type	Description
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)

200 Successful response

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

• See create signature logic.

• See full example with signature creation.

• See the list of supported tokens for amount value.

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

Name	Type	Description
id*	string	Invoice Id (uuid)

200 Successful response

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