POST /invoice/create

Создаёт новый инвойс и возвращает ссылку на платёжную страницу. После успешного создания генерируется уникальный invoice_id, инвойс получает статус PENDING (1).

Авторизация

Требуется Bearer token и заголовок X-Merchant. См. Начало работы.

Параметры запроса

Headers

Параметр	Тип	Обязательный	Описание
`Authorization`	string	Да	`Bearer <token>`
`X-Merchant`	string	Да	Идентификатор мерчанта, например `merchant_123`
`Content-Type`	string	Да	`application/json`

Query и Path параметры отсутствуют.

Тело запроса (Request Body)

Content-Type: application/json

Поле	Тип	Обязательный	Описание
`amount`	integer	Да	Сумма в минимальных единицах валюты (> 0). 1500 = 15.00 USD
`currency`	string	Да	ISO 4217: USD, EUR, RUB, UZS
`description`	string	Да	Описание инвойса (1–1024 символа)
`end_date`	integer	Да	UTC timestamp (ms), после которого статус станет EXPIRED
`positions`	array	Да	Минимум одна позиция (см. ниже)
`merchant_transaction_id`	string	Да	Уникальный ID транзакции на стороне мерчанта
`success_url`	string (uri)	Да	Редирект после успешной оплаты (браузер)
`error_url`	string (uri)	Да	Редирект при ошибке или отмене
`callback_url`	string (uri)	Да	Webhook URL для server-to-server уведомлений
`merchant_data`	object	Нет	Произвольные данные, возвращаются в callback

Элемент массива positions

Поле	Тип	Обязательный	Описание
`title`	string	Да	Название позиции
`amount`	integer	Да	Сумма позиции (> 0)
`currency`	string	Да	Валюта позиции

{
  "amount": 1500,
  "currency": "USD",
  "description": "Payment for order #1001",
  "end_date": 1779454179000,
  "merchant_transaction_id": "order_1001",
  "success_url": "https://merchant.com/success",
  "error_url": "https://merchant.com/error",
  "callback_url": "https://merchant.com/callback",
  "positions": [
    {
      "title": "Premium subscription",
      "amount": 1500,
      "currency": "USD"
    }
  ],
  "merchant_data": {
    "customer_id": 123,
    "order_id": "1001"
  }
}
        

Ответы

200 OK — Инвойс успешно создан

Поле	Тип	Описание
`result`	boolean	`true` при успехе
`data.invoice_id`	string	ID инвойса в платёжной системе
`data.invoice_url`	string	URL страницы оплаты
`data.status`	integer	1 = PENDING
`data.amount`	integer	Сумма инвойса
`data.currency`	string	Валюта
`data.created_at`	integer	UTC timestamp (ms) создания
`error`	object \| null	`null` при успехе

{
  "result": true,
  "data": {
    "invoice_id": "inv_01970f4f6b7c7d52b2d9",
    "invoice_url": "https://pay.example.com/invoice/inv_01970f4f6b7c7d52b2d9",
    "success_url": "https://merchant.com/success",
    "error_url": "https://merchant.com/error",
    "status": 1,
    "amount": 1500,
    "currency": "USD",
    "description": "Payment for order #1001",
    "merchant_transaction_id": "order_1001",
    "merchant_data": {"customer_id": 123, "order_id": "1001"},
    "end_date": 1779454179000,
    "created_at": 1779454179000
  },
  "error": null
}
        

401 Unauthorized — Ошибка авторизации

Возможные причины: отсутствует Bearer token, неверный или деактивированный токен.

{
  "result": false,
  "data": null,
  "error": {
    "message": "Unauthorized",
    "error_code": 401
  }
}
        

409 Conflict — Дубликат транзакции

Инвойс с таким merchant_transaction_id уже существует.

{
  "result": false,
  "data": null,
  "error": {
    "message": "Invoice with this merchant_transaction_id already exists",
    "error_code": 409
  }
}
        

422 Unprocessable Entity — Ошибка валидации

Поле	Тип	Описание
`detail`	array	Список ошибок полей
`detail[].loc`	array	Путь к полю, например `["body","amount"]`
`detail[].msg`	string	Текст ошибки
`detail[].type`	string	Тип ошибки валидации

{
  "detail": [
    {
      "loc": ["body", "amount"],
      "msg": "Input should be greater than 0",
      "type": "greater_than"
    }
  ]
}
        

500 Internal Server Error

Внутренняя ошибка сервера. Повторите запрос с экспоненциальной задержкой; при устойчивой ошибке обратитесь в поддержку.

{
  "result": false,
  "data": null,
  "error": {
    "message": "Internal server error",
    "error_code": 500
  }
}
        

01 июня 2026