Collect&Exchange

Order Creation Flow

This section describes the process of creating a payment order in the crypto acquiring system. A payment order represents a single intent to receive funds from a customer and is the core entity of the acquiring flow.

Endpoint Overview

HTTP Method: POST
Endpoint: /api/public/v1/acquiring/order
Authentication: Signature header

This endpoint creates a new payment order and returns all data required to complete the payment, including the destination wallet address and QR code.

Request Headers

Header	Description
`Content-Type`	Must be `application/json`
`Accept`	Must be `application/json`
`Signature`	Request signature used for authentication and integrity validation

The Signature header is mandatory. It is used to identify the merchant and verify request integrity.
The signature generation process is described in detail in a dedicated section later in this documentation.

The specifics of creating a signature in the header can be found in the section Signature Generation

The following fields are used to generate the signature in the order specified:

amount token_address network external_client_id external_data external_order_id

300;0xdAC17F958D2ee523a2206206994597C13D831ec7;ethereum;1;{"key":"value"};1;

Payment Creation Request Example


POST {{baseUrl}}/api/public/v1/acquiring/order
Content-Type: application/json
Accept: application/json
Signature: {{signature}}
 
{
    "terminal_uuid": "fa03e78f-4b2e-4da0-a3ca-6a8cd05ad468",
    "amount": 300,
    "token_address": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
    "network": "ethereum",
    "external_client_id": 1,
    "external_data": "{\"key\":\"value\"}",
    "external_order_id": 1,
    "webhook_url": "https://example.com/webhook"
}

Request Parameters

Field	Type	Required	Description
`terminal_uuid`	UUID	yes	Identifier of the terminal under which the payment is created
`amount`	Number	yes	Payment amount in selected token
`token_address`	String	yes	Smart contract address of the payment token
`network`	String	yes	Blockchain network where the payment will be processed
`external_client_id`	String / Number	no	Optional merchant-side client identifier
`external_order_id`	String / Number	yes	Merchant-side order identifier
`external_data`	String (JSON)	no	Arbitrary metadata associated with the order
`webhook_url`	String (URL)	no	URL that will receive payment status notifications

The external_order_id, external_client_id, and external_data fields represent the external order and client identifiers. They can be used to connect the payment API to the merchant’s external system.

The list of supported networks and tokens can be retrieved via the Directories API, which is described in a Networks and Currencies.

Successful Response Example


{
  "success": true,
  "data": {
    "uuid": "09710bb5-7a49-4321-8824-1a39ef99cd30",
    "terminal_uuid": "fa03e78f-4b2e-4da0-a3ca-6a8cd05ad468",
    "amount": 300,
    "currency": {
      "token_address": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
      "name": "Tether USD",
      "symbol": "USDT",
      "decimals": 6
    },
    "wallet": {
      "wallet_address": "0x26dCF2eA9a10F5EAA6500d88920CC45f64e7e52a",
      "wallet_qr": "<base64-encoded-qr>",
      "network": "ethereum"
    },
    "external_order_id": "1",
    "external_client_id": "1",
    "external_data": {
      "key": "value"
    },
    "status_id": 1,
    "status": "Created",
    "webhook_url": "https://example.com/webhook",
    "is_test": true,
    "created_at": "2026-01-01T12:00:00.000000Z",
    "transaction_end_at": null,
    "expired_at": "2026-01-01T12:30:00.000000Z"
  }
}

Response Details

A successful response contains a fully initialized payment order with the following key elements:

Order UUID: Internal unique identifier of the payment order.

Wallet Address: A dedicated blockchain wallet generated specifically for this payment. The customer must send the exact specified amount to this address.

QR Code: Base64-encoded QR code that can be displayed directly in checkout or payment pages.

Payment Status: Newly created payments are returned with the status Created.

Expiration Time: The expired_at field defines the time window during which the payment is valid. Payments received after expiration are not processed.

Next Steps

After creating a payment order, the merchant should:

Display the wallet address or QR code to the customer
Monitor payment status via webhooks or API
Process the order once the payment reaches a final status