Overview

To create a merchant invoice, you first need to obtain the terminalId to associate the invoice with a specific terminal.

This process involves two API calls:
1️⃣ Retrieve all terminals and select an active one.
2️⃣ Create the invoice using the selected terminal ID.

1️⃣ Step 1: Retrieve Terminal ID

➡ API Reference: GET /terminals

Description:
Returns the list of available merchant terminals. You must use the id of an active terminal (status = "ACTIVE") as the terminalId when creating an invoice.

Headers:

Authorization: Bearer <access_token>

Example Request

curl -X GET "https://api.pay.asterium.uz/terminals?page=0&size=50" \
  -H "Authorization: Bearer <access_token>"

Example Response

{
  "currentPage": 0,
  "totalItems": 10,
  "totalPages": 1,
  "data": [
    {
      "id": "278e0d8e-f7e9-4ace-9747-20785ab00070",
      "name": "Default Point of Sale",
      "businessUnitName": "Default business unit",
      "status": "ACTIVE"
    }
  ]
}

Note: The field id from the active terminal object should be used as terminalId in the next request.

2️⃣ Step 2: Create Invoice

➡ API Reference: POST /merchant-invoices

Description:
Creates a new invoice linked to a specific terminal.
Each invoice can include one or multiple items (products or services).

Headers:

Authorization: Bearer <access_token>
Content-Type: application/json

Request Body Parameters

Field	Type	Required	Description
`terminalId`	string	✅	Identifier of the terminal that initialized the invoice.
`clientId`	string	❌	External client ID provided by the merchant.
`desc`	string	❌	External description or purpose of the invoice.
`currency`	string	✅	Currency code in ISO 4217 format.
`clientEmail`	string	❌	Client’s email address used for notifications or receipts.
`type`	string (enum)	❌	Type of invoice request. Defaults to `ORIGINAL`. Allowed: `ORIGINAL`.
`items`	array of objects	✅	List of products included in the invoice.

Item object fields:

Field	Type	Required	Description
`id`	string	❌	Client- or system-defined identifier of the item.
`name`	string	✅	Name of the product or service.
`description`	string	❌	Detailed description of the item.
`price`	string	✅	Price per single unit in item currency.
`currency`	string	✅	ISO 4217 currency code of the item.
`quantity`	integer	✅	Quantity of units for the item (must be ≥ 1).
`icpuCode`	string	❌	ICP/ICPS code or internal classification code for the product/service.
`packageCode`	string	❌	Packaging or unit-of-measure code (e.g., BOX, CTN, PCS).
`imageUrl`	uri	❌	URL of the product image.
`metadata`	object	❌	Optional metadata or custom parameters for the item.

Additional invoice parameters:

Field	Type	Description
`expireAt`	date-time	Timestamp when the invoice expires and is no longer payable.
`overpaidAmount`	string	Fixed overpayment tolerance amount in invoice currency.
`overpaidPercent`	string	Percentage of overpayment allowed on the invoice.
`underpaidAmount`	string	Fixed underpayment tolerance amount in invoice currency.
`underpaidPercent`	string	Percentage of underpayment allowed on the invoice.

Example Request

{
  "terminalId": "278e0d8e-f7e9-4ace-9747-20785ab00070",
  "clientId": "user-101",
  "desc": "Order payment for subscription and digital goods",
  "currency": "USDT",
  "clientEmail": "customer@example.com",
  "type": "ORIGINAL",
  "items": [
    {
      "id": "item-001",
      "name": "Premium Plan",
      "description": "1-month access to premium features",
      "price": "9.99",
      "currency": "USD",
      "quantity": 1,
      "imageUrl": "https://merchant-assets.example.com/images/premium-plan.png"
    },
    {
      "id": "item-002",
      "name": "Game Credits",
      "description": "10,000 game credits",
      "price": "25.00",
      "currency": "USD",
      "quantity": 1,
      "imageUrl": "https://merchant-assets.example.com/images/credits.png"
    }
  ],
  "expireAt": "2025-11-30T23:59:00Z",
  "overpaidPercent": "2.5",
  "underpaidAmount": "1.00"
}

Example Response

{
  "id": "0a0528cc-544a-4975-8005-9197dac11f32",
  "payUrl": "checkout.pay.asterium.uz/terminal/278e0d8e-f7e9-4ace-9747-20785ab00070/invoice/0a0528cc-544a-4975-8005-9197dac11f32/payment"
}

Response Fields

Field	Type	Description
`id`	string	Unique invoice identifier.
`payUrl`	string	URL to redirect the customer for payment.

👍
Additional Notes

The invoice is tied to the terminal through the terminalId field.

Multiple products can be included in the items array.

If the callbackUrl is provided, the system sends asynchronous status updates (created, processing, paid, failed, expired).

The payUrl can be embedded in a payment page or opened directly in a browser.