Разработчикам

Справочник API

Небольшой REST API для счетов, платёжных ссылок, балансов и принимаемых монет. Он использует JSON поверх HTTPS, и каждый запрос выполняется с вашим секретным ключом.

Базовый URL

Продакшен: https://cryptomerchant.online/api/v1
Локальная разработка: http://localhost:3000/api/v1

Машиночитаемое описание этого API находится по адресу /openapi.json (OpenAPI 3.1). Его можно импортировать в Postman или генератор клиентов.

Аутентификация

Передавайте секретный ключ в заголовке Authorization каждого запроса как Bearer-токен. Ключи создаются в личном кабинете в разделе Разработчикам.

HTTP

Authorization: Bearer cm_live_…

В основной сети ключи начинаются с cm_live_, в тестовой — с cm_test_.
Полный ключ показывается только один раз, при создании. Мы храним только его хеш, поэтому сохраните ключ в надёжном месте.
Используйте ключи только на своём сервере. Никогда не размещайте их на веб-странице, в мобильном приложении или в публичном репозитории кода.
Если ключ мог утечь, отзовите его в личном кабинете и создайте новый.

Ошибки

Если запрос не удался, ответ содержит HTTP-статус ошибки и JSON-тело с машиночитаемым code и понятным человеку message:

JSON

{
  "error": {
    "code": "amount_too_small",
    "message": "Amount must be at least 0.50 USD."
  }
}

HTTP-статус

400: Запрос некорректен, например не хватает поля или сумма слишком мала.
401: API-ключ отсутствует, неверен или отозван.
403: Ваш аккаунт не может этого сделать: он ещё не активирован или приостановлен.
404: Объект не существует или принадлежит другому бизнесу.
409: Со счётом нельзя выполнить это действие в текущем статусе, например отменить счёт, по которому уже есть платёж.
500: Что-то пошло не так на нашей стороне. Попробуйте немного позже.

Возможные коды

invalid_json: Тело запроса не является JSON-объектом.
invalid_request: Поле отсутствует или некорректно. В сообщении указано, какое именно.
unauthorized: API-ключ отсутствует, неверен или отозван.
account_suspended: Этот аккаунт продавца приостановлен.
merchant_not_live: Ваш аккаунт ещё не активирован. Сначала завершите настройку в личном кабинете.
invalid_amount: Сумма отсутствует, не является числом или не больше нуля.
amount_too_small: Сумма меньше 0,50 доллара США.
invalid_asset: ID монеты не соответствует ни одной известной монете.
asset_not_accepted: Вы не принимаете эту монету.
invalid_state: Со счётом нельзя выполнить это действие в текущем статусе.
not_found: Объекта с таким ID нет.
server_error: Что-то пошло не так на нашей стороне.

Объект счёта

Счета имеют такую структуру в ответах API и в вебхуках. Суммы передаются десятичными строками, поэтому точность не теряется.

idstring: ID счёта, начинается с inv_.
objectstring: Всегда invoice.
statusstring: Текущий статус. Список статусов приведён ниже.
amountstring: Запрошенная вами цена в валюте currency.
currencystring: Валюта цены, например USD.
amount_usdstring: Цена в долларах США.
descriptionstring | null: Ваше описание, которое видит клиент.
order_idstring | null: Ваш собственный номер заказа.
customer_emailstring | null: Эл. почта клиента, если вы её указали.
metadataobject: Объект, переданный при создании счёта, возвращается без изменений.
coinobject | null: Монета, которую выбрал клиент, или монета, которой он фактически заплатил, с её id, symbol и network. null, пока монета не выбрана.
requested_coinobject | null: Обычно null. Если клиент заплатил другой монетой или в другой сети и платёж был засчитан, это монета, которую запрашивал счёт, с теми же полями, что и coin. См. раздел «Не та монета или не та сеть».
pay_addressstring | null: Адрес для оплаты этого счёта. null, пока монета не выбрана.
pay_amountstring | null: Точная сумма к отправке в выбранной монете.
network_fee_amountstring: Часть pay_amount: комиссия за газ, которую клиент платит сверх цены, в монете. 0, если её нет.
network_fee_usdstring: Та же комиссия за газ в долларах США.
rate_usdstring | null: Зафиксированная цена одной единицы выбранной монеты в долларах США.
received_amountstring: Сколько уже поступило в выбранной монете.
received_usdstring: Стоимость поступившего в долларах США.
overpaid_amountstring: На сколько больше требуемого по счёту было заплачено, в выбранной монете.
refunded_amountstring: Сколько вы вернули по этому платежу через ссылки на возврат, в монете оплаты. 0, если ничего.
checkout_urlstring: Страница счёта. Направьте сюда клиента для оплаты.
redirect_urlstring | null: Куда клиент может перейти после оплаты.
expires_atISO 8601: Когда истечёт срок счёта, если платёж не будет замечен.
paid_atISO 8601 | null: Когда счёт был оплачен, или null.
created_atISO 8601: Когда счёт был создан.

invoice

{
  "id": "inv_…",
  "object": "invoice",
  "status": "open",
  "amount": "49.9",
  "currency": "USD",
  "amount_usd": "49.9",
  "description": "Annual plan",
  "order_id": "1042",
  "customer_email": "[email protected]",
  "metadata": { "plan": "annual" },
  "coin": null,
  "requested_coin": null,
  "pay_address": null,
  "pay_amount": null,
  "network_fee_amount": "0",
  "network_fee_usd": "0",
  "rate_usd": null,
  "received_amount": "0",
  "received_usd": "0",
  "overpaid_amount": "0",
  "refunded_amount": "0",
  "checkout_url": "https://cryptomerchant.online/pay/i/inv_…",
  "redirect_url": "https://yourstore.example/thanks",
  "expires_at": "2026-10-28T10:00:00.000Z",
  "paid_at": null,
  "created_at": "2026-10-28T09:30:00.000Z"
}

Статусы счёта

openОткрыт: Создан. Клиент ещё не выбрал монету.
awaiting_paymentОжидает оплаты: Монета выбрана, адрес для оплаты назначен, курс зафиксирован.
confirmingПодтверждается: Платёж замечен в блокчейне и ожидает подтверждений.
underpaidНедоплачен: Подтверждённому платежу не хватает больше заданного вами допуска. Клиент может доплатить остаток или запросить возврат.
paidОплачен: Оплачен и подтверждён. Сумма за вычетом комиссии находится на вашем балансе. При частичном возврате этот статус сохраняется.
expiredИстёк: Время истекло до того, как был замечен какой-либо платёж.
cancelledОтменён: Счёт был отменён до того, как был замечен какой-либо платёж.
refundedВозвращён: Клиенту возвращено то, что он отправил по недоплаченному счёту, или вы вернули всё, что получили по оплаченному счёту.

Создание счёта

POST/invoices

Создаёт счёт и возвращает объект счёта со статусом 201. Направьте клиента на его checkout_url.

Параметры тела

amountОбязательныйnumber | string: Цена числом или десятичной строкой. Должна быть не меньше 0,50 доллара США.
currencyНеобязательныйstring: Валюта цены, например USD. По умолчанию USD.
descriptionНеобязательныйstring: За что платит клиент, до 300 символов. Показывается на странице счёта.
order_idНеобязательныйstring: Ваш собственный номер заказа, до 120 символов, чтобы связать счёт с заказом.
customer_emailНеобязательныйstring: Адрес эл. почты клиента. В личном кабинете платежи группируются по клиентам.
customer_nameНеобязательныйstring: Имя клиента, до 120 символов.
redirect_urlНеобязательныйstring: Полный URL, куда клиент может перейти после оплаты.
metadataНеобязательныйobject: Любой JSON-объект размером до 4 КБ. Возвращается без изменений в счёте и в вебхуках.
coinНеобязательныйstring: Заранее выбирает монету по её ID, например USDT.TRON. Она должна входить в ваши принимаемые монеты.

Если монета coin выбрана заранее, адрес для оплаты назначается и курс фиксируется сразу, поэтому pay_address и pay_amount заполнены, и вы можете показать платёжные данные в собственном интерфейсе.

curl

curl https://cryptomerchant.online/api/v1/invoices \
  -H "Authorization: Bearer $CM_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "49.90",
    "currency": "USD",
    "order_id": "1042",
    "description": "Annual plan",
    "customer_email": "[email protected]",
    "redirect_url": "https://yourstore.example/thanks",
    "metadata": { "plan": "annual" }
  }'

Node.js

const res = await fetch("https://cryptomerchant.online/api/v1/invoices", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CM_SECRET_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    amount: "49.90",
    currency: "USD",
    order_id: "1042",
    description: "Annual plan",
  }),
});

if (!res.ok) {
  const { error } = await res.json();
  throw new Error(`${error.code}: ${error.message}`);
}

const invoice = await res.json();
// Send the customer to invoice.checkout_url

Список счетов

GET/invoices

Возвращает ваши счета постранично, сначала новые.

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

statusНеобязательныйstring: Только счета с этим статусом, например paid. Должен быть одним из статусов выше.
limitНеобязательныйnumber: Сколько счетов вернуть, от 1 до 100. По умолчанию 20.
starting_afterНеобязательныйstring: ID счёта. Возвращает счета, идущие после него, для следующей страницы.

Счета находятся в data. Если has_more равно true, запросите следующую страницу, передав в starting_after ID последнего полученного счёта.

curl

curl "https://cryptomerchant.online/api/v1/invoices?status=paid&limit=20" \
  -H "Authorization: Bearer $CM_SECRET_KEY"

Ответ

{
  "object": "list",
  "data": [
    { "id": "inv_…", "object": "invoice", "status": "paid", … }
  ],
  "has_more": true
}

Получение счёта

GET/invoices/{id}

Возвращает один счёт по его ID.

curl

curl https://cryptomerchant.online/api/v1/invoices/$INVOICE_ID \
  -H "Authorization: Bearer $CM_SECRET_KEY"

Отмена счёта

POST/invoices/{id}/cancel

Отменяет счёт. Это работает, только пока счёт не оплачен и по нему не замечено ни одного платежа.

curl

curl -X POST https://cryptomerchant.online/api/v1/invoices/$INVOICE_ID/cancel \
  -H "Authorization: Bearer $CM_SECRET_KEY"

Балансы

GET/balances

Возвращает, сколько ваш бизнес хранит в каждой монете, общую сумму в долларах США и баланс газа.

data[].coin: ID монеты, например USDT.TRON.
data[].symbol: Символ монеты, например USDT.
data[].network: Сеть, в которой находится монета.
data[].amount: Сколько монеты у вас есть, десятичной строкой.
data[].usd: Её стоимость в долларах США по текущей цене.
total_usd: Стоимость всех ваших монет в долларах США.
gas_balance_usd: Ваш баланс газа в долларах США, используемый для оплаты комиссий за газ.

curl

curl https://cryptomerchant.online/api/v1/balances \
  -H "Authorization: Bearer $CM_SECRET_KEY"

Ответ

{
  "object": "balance",
  "data": [
    { "coin": "USDT.TRON", "symbol": "USDT", "network": "Tron", "amount": "…", "usd": "…" }
  ],
  "total_usd": "…",
  "gas_balance_usd": "…"
}

Принимаемые монеты

GET/coins

Возвращает монеты, которые вы принимаете сейчас, каждую с её id, symbol, name, network и decimals. Используйте id как coin при создании счёта. Например:

curl

curl https://cryptomerchant.online/api/v1/coins \
  -H "Authorization: Bearer $CM_SECRET_KEY"

Ответ

{
  "object": "list",
  "data": [
    {
      "id": "ETH.ETH",
      "symbol": "ETH",
      "name": "Ethereum",
      "network": "Ethereum",
      "decimals": 18
    },
    {
      "id": "USDT.ETH",
      "symbol": "USDT",
      "name": "Tether USD",
      "network": "Ethereum",
      "decimals": 6
    },
    {
      "id": "USDC.ETH",
      "symbol": "USDC",
      "name": "USD Coin",
      "network": "Ethereum",
      "decimals": 6
    }
  ]
}

Создание платёжной ссылки

POST/payment-links

Создаёт платёжную ссылку и возвращает её со статусом 201, включая её id и url для распространения.

Параметры тела

titleОбязательныйstring: Название того, за что платит клиент, до 120 символов.
amountНеобязательныйnumber | string: Фиксированная цена. Не указывайте её, чтобы сумму вводил клиент.
currencyНеобязательныйstring: Валюта цены. По умолчанию USD.
descriptionНеобязательныйstring: Дополнительные сведения для клиента, до 300 символов.

curl

curl https://cryptomerchant.online/api/v1/payment-links \
  -H "Authorization: Bearer $CM_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Consulting hour",
    "amount": "80",
    "currency": "USD"
  }'

Ответ

{
  "id": "…",
  "object": "payment_link",
  "title": "Consulting hour",
  "description": null,
  "amount": "80",
  "currency": "USD",
  "active": true,
  "url": "https://cryptomerchant.online/pay/l/…",
  "created_at": "2026-10-28T09:30:00.000Z"
}

Список платёжных ссылок

GET/payment-links

Возвращает 100 последних платёжных ссылок, сначала новые, в data.

curl

curl https://cryptomerchant.online/api/v1/payment-links \
  -H "Authorization: Bearer $CM_SECRET_KEY"

Объект выплаты

Вебхуки выплат (payout.sent и payout.failed) передают этот объект в data. Выплаты доли партнёра по распределению выручки используют тот же объект, с partner_share, равным true.

idstring: ID выплаты.
objectstring: Всегда payout.
coinstring: ID монеты, например USDT.TRON.
amountstring: Выплаченная сумма в этой монете.
network_feestring: Комиссия за газ при отправке, в этой монете.
to_addressstring: Адрес кошелька, на который отправлена выплата.
statusstring: queued, running, done или failed.
tx_hashstring | null: ID транзакции в блокчейне после отправки.
autoboolean: true, если выплата сделана автоматически, а не запрошена человеком.
partner_shareboolean: true, если эта выплата — доля партнёра по распределению выручки, отправленная на кошелёк партнёра.
created_atISO 8601: Когда выплата была создана.

payout

{
  "id": "…",
  "object": "payout",
  "coin": "USDT.TRON",
  "amount": "120",
  "network_fee": "…",
  "to_address": "T…",
  "status": "done",
  "tx_hash": "…",
  "auto": true,
  "partner_share": true,
  "created_at": "2026-10-28T09:30:00.000Z"
}

Далее настройте вебхуки, чтобы ваш сервер узнавал о платежах в момент их поступления.