Create Orders

Registered and verified merchants and individuals can receive crypto payments via the web interface or API requests. When creating an order on the web interface, the following fields are unavailable:

• Group number (group_no) (API only)
• Order number (order_no) (automatically generated)
• Notify URL (notify_url) (API only)
• Return URL (return_url) (API only)
• Timeout (timeout) (defaults to 30 minutes)

Create Pre-configured Invoice

Pre-configured invoices support two default on-chain confirmation methods:

• ID Confirmation: The order ID is compiled as additional data and included in the blockchain transfer information. Payment is confirmed by matching the order ID after the transfer is complete.
• Tail Confirmation: A tail (tail) is added to the order amount. When the user initiates a blockchain transfer, the order amount plus the tail is used to locate and confirm the order.

Preparation

Before making the API request, you need to prepare the following:

• Get the list of supported blockchains: GET /api/v1/chain
• Get the list of supported tokens: GET /api/v1/token
• Get the list of pre-created addresses: GET /api/v1/address

The selected blockchain and token from the pre-created address list must be an exact match. The requested data can be cached locally to speed up request preparation.

Request

• Endpoint: POST /api/v1/order/create/invoice
• Headers:
  • X-API-Key: '<API Key>'
  • X-Signature: '<SIGNATURE>' (please refer to: API Keys.)
• Request Body Constraints:
  • The order number (order_no) must be unique for each address (address), i.e., UNIQUE(address, order_no).
  • For pending orders using the tail confirmation method, the address, token, amount, and tail must be unique, i.e., UNIQUE(address, token, amount, tail) WHERE status = 0 AND type = 'tail'.

    This unique combination is required to match the corresponding blockchain transfer transaction.

Notify URL

For orders with a Notify URL configured, the payment page will immediately send a POST request with the order information to this URL after a successful payment. Your server can process the order by parsing the received request. The request body contains order-related information in JSON format:

{
  "id": "order.id", // xxxxxxxxxxxxxxx
  "group_no": "order.group_no",
  "order_no": "order.order_no",
  "chain": "chain.name", // ETH, BSC, ...
  "address": "address.address", // 0x...
  "token": "token.address", // 0x...
  "amount": "full_amount_with_tail",
  "pay_time": "order.pay_time", // ISO
  "transaction": TokenTx,
  "locale": "en" // UI language
}

// TokenTx
interface TokenTx {
    blockNumber: string;
    timeStamp: string;
    hash: string;
    nonce: string;
    blockHash: string;
    from: string;
    contractAddress: string;
    to: string;
    value: string;
    tokenName: string;
    tokenSymbol: string;
    tokenDecimal: string;
    transactionIndex: string;
    gas: string;
    gasPrice: string;
    gasUsed: string;
    cumulativeGasUsed: string;
    input: string;
    confirmations: string;
}

Note: Due to reasons such as request interception, target server unavailability, or network fluctuations, this notification may fail. Therefore, be sure to configure Callback as fallback.

Return URL

After processing the request to the Notify URL (if applicable), the payment page will redirect the browser to this Return URL, which can be used to return to your website page and complete the loop.

Response

Content-Type: application/json

{
  "code": 200,
  "data": {
    "id": "order_id",
    "type": "tail", // id | tail
    "group_no": "",
    "order_no": "external_order_no",
    "user": "RELATION_RECORD_ID",
    "chain": "RELATION_RECORD_ID",
    "address": "RELATION_RECORD_ID",
    "token": "RELATION_RECORD_ID",
    "amount": 123,
    "tail": "5623", // empty for id type
    "status": 0, // 0: pending, 1: success, 2: overdue
    "pay_time": "", // empty when created
    "timeout": 1800, // seconds, default 1800
    "return_url": "https://domain.com/path",
    "created": "2022-01-01 10:00:00.123Z",
    "updated": "2022-01-01 10:00:00.123Z"
  }
}

{
  "code": 400,
  "message": "error message"
}

Create Custom Transfer

Not yet available