API, совместимый с Cryptomus

blockwallets принимает USDT и USDC, а также BTC, LTC, DOGE, BCH и нативные монеты (зачисляются в долларах США по зафиксированному курсу): клиент платит, мы подтверждаем платёж в блокчейне и уведомляем вас. API, подписи и вебхуки такие же, как у Cryptomus — если вы уже интегрировали Cryptomus, смените домен, и всё. Сначала о том, как это работает, затем об API.

Два способа приёма

Оба принимают любую сумму: заказы с фиксированной ценой и пополнения, где клиент вводит сумму сам. После оплаты вы отгружаете заказ или зачисляете сумму на баланс клиента. Разница только в том, получает ли каждый платёж новый адрес.

Если сомневаетесь, используйте счета. Без кода подойдут платёжные ссылки в кабинете — это счета, которые создаются за вас. Ещё не продавец? Запросите доступ на главной странице; после одобрения войдите в кабинет продавца и начните с пункта «Пробный платёж» на главной странице кабинета, заплатив небольшую сумму (деньги поступят на ваш собственный баланс).

Как проходит счёт

В платеже участвуют четыре стороны: клиент, ваш сайт, blockwallets и блокчейн. Схема идёт сверху вниз по времени; правый столбец — статус счёта на каждом шаге.

Коротко, пять шагов:

1. Вы создаёте счёт (платёжная ссылка делает это за вас, либо ваш сервер вызывает /v1/payment), получаете url страницы оплаты и перенаправляете туда клиента.
2. На странице оплаты клиент выбирает монету и сеть, получает отдельный адрес и сумму и платит из кошелька или с биржи.
3. Мы видим перевод в блокчейне, ждём достаточного числа подтверждений, затем сверяем его со вторым поставщиком узлов (чтобы один узел не мог подделать платёж).
4. Счёт получает статус paid, и мы сразу отправляем POST с подписанным вебхуком на ваш url_callback; через несколько секунд страница оплаты возвращает клиента на ваш url_success.
5. Деньги зачисляются на ваш баланс; выводите их на свой кошелёк из кабинета продавца.

Статус счёта

Если is_final равен true, статус больше не изменится (кроме поздних платежей).

Платёжные ссылки (без кода)

Кабинет продавца → «Платежи › Платёжные ссылки» → введите описание и сумму (зафиксируйте сеть или дайте клиенту выбрать) → создайте. У каждой ссылки есть URL и QR-код.

• Каждое открытие ссылки создаёт новый счёт, поэтому одну ссылку можно использовать многократно (например, «Членство $99»).
• Каждый платёж виден в разделе «Платежи › Транзакции»; выводите деньги на свой кошелёк в разделе «Средства › Баланс и вывод».
• Если вы создали учётные данные и URL вебхука в разделе «Разработчикам › Интеграция и ключи», платежи по ссылкам тоже приходят уведомлениями в формате, описанном ниже.
• Чтобы прекратить приём, нажмите «Отключить» — ссылка перестанет работать сразу.

Интеграция по API

1. Учётные данные и подпись

Кабинет продавца → «Разработчикам › Интеграция и ключи» → создайте merchant (UUID) и API key. Есть один набор для Live и один для Test: Live принимает настоящие деньги, Test работает в тестовых сетях. Добавьте также домены сайта: url_callback, url_return и url_success должны находиться на них. API key показывается только один раз — храните его надёжно и только на сервере.

Базовый URL: https://blockwallets.io. Каждый эндпоинт — POST + JSON со следующими заголовками:

• merchant: UUID вашего продавца (он определяет Live или Test)
• sign: md5(base64(тело запроса) + API key), где тело — в точности та JSON-строка, которую вы отправляете

Успешный ответ: {"state": 0, "result": {…}}; ошибка: {"state": 1, "message": "…"} (см. Ошибки).

У основных эндпоинтов ниже есть панель «Попробовать»: введите Test merchant и API key, и страница подпишет запрос в вашем браузере, вызовет эндпоинт и покажет полный запрос и ответ (учётные данные остаются в памяти страницы). Если подпись не совпадает, сравните её по шагам в проверке подписи.

import crypto from "node:crypto";

async function call(path, data) {
  const body = JSON.stringify(data);
  const sign = crypto.createHash("md5").update(Buffer.from(body).toString("base64") + process.env.BW_API_KEY).digest("hex");
  const res = await fetch("https://blockwallets.io" + path, {
    method: "POST",
    headers: { merchant: process.env.BW_MERCHANT, sign, "Content-Type": "application/json" },
    body,
  });
  return res.json();
}

function bw_call(string $path, array $data): array {
    $body = json_encode($data, JSON_UNESCAPED_UNICODE);
    $sign = md5(base64_encode($body) . getenv('BW_API_KEY'));
    $ch = curl_init('https://blockwallets.io' . $path);
    curl_setopt_array($ch, [
        CURLOPT_POST => true, CURLOPT_POSTFIELDS => $body, CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => ['merchant: ' . getenv('BW_MERCHANT'), 'sign: ' . $sign, 'Content-Type: application/json'],
    ]);
    return json_decode(curl_exec($ch), true);
}

import base64, hashlib, json, os, requests

def bw_call(path: str, data: dict) -> dict:
    body = json.dumps(data, separators=(",", ":"), ensure_ascii=False)
    sign = hashlib.md5((base64.b64encode(body.encode()).decode() + os.environ["BW_API_KEY"]).encode()).hexdigest()
    headers = {"merchant": os.environ["BW_MERCHANT"], "sign": sign, "Content-Type": "application/json"}
    return requests.post("https://blockwallets.io" + path, data=body.encode(), headers=headers).json()

2. Создание счёта POST /v1/payment

Когда клиент оформляет заказ или вводит сумму на странице пополнения, вызовите https://blockwallets.io/v1/payment и перенаправьте его на возвращённый result.url.

{
  "amount": "42.00",
  "currency": "USD",
  "order_id": "order_1042",
  "url_callback": "https://shop.example/webhooks/crypto",
  "url_return": "https://shop.example/cart",
  "url_success": "https://shop.example/thanks?order=1042"
}

{
  "state": 0,
  "result": {
    "uuid": "6f1c2a7e-…",
    "order_id": "order_1042",
    "amount": "42.00",
    "currency": "USD",
    "network": null,
    "address": null,
    "payer_amount": null,
    "payment_amount": null,
    "url": "https://blockwallets.io/pay/inv_01J8…",
    "expired_at": 1760965200,
    "status": "check",
    "is_final": false
  }
}

network, address и payer_amount заполняются, когда клиент выбирает сеть.

3. Запрос счетов

• POST /v1/payment/info {"order_id": "…"} или {"uuid": "…"}: получить один счёт, попутно проверив блокчейн (не чаще раза в 10 секунд).
• POST /v1/payment/list: список, по 15 на страницу, необязательные date_from / date_to; следующая страница через возвращённый paginate.nextCursor (?cursor=…).
• POST /v1/payment/services: доступные сети и минимальная сумма для каждой.
• POST /v1/payment/resend {"order_id": "…"}: повторно отправить вебхук оплаченного или недоплаченного счёта.

Основной канал — вебхуки, запросы служат запасным вариантом (например, если ваш сервер не работал и пропустил вебхук).

4. Статические кошельки POST /v1/wallet

Открывает постоянный адрес для одного клиента в одной сети. Один и тот же order_id (обычно id вашего пользователя) + сеть всегда дают один и тот же адрес; все сети EVM (BNB Chain, Ethereum, Base, Polygon, Arbitrum, Optimism, Avalanche, X Layer) используют один адрес, а TRON, BTC, LTC, DOGE, BCH, Solana и TON — каждая свой. Всё, что отправит клиент, зачисляется, на каждый перевод приходит вебхук; переводы BTC / LTC / DOGE / BCH / TRX / BNB / ETH / POL / AVAX / OKB / SOL / TON пересчитываются в доллары США по курсу на момент, когда каждый перевод был замечен (payment_amount_usd).

{
  "order_id": "user_42",
  "currency": "USDT",
  "network": "tron",
  "url_callback": "https://shop.example/webhooks/crypto"
}

{
  "state": 0,
  "result": {
    "wallet_uuid": "0b9d…",
    "uuid": "5e2f…",
    "order_id": "user_42",
    "currency": "USDT",
    "network": "tron",
    "address": "TXy4…8kQ2",
    "url": "https://blockwallets.io/deposit/dac_01J8…"
  }
}

result.url — размещённая у нас страница пополнения (адрес + QR-код + последние поступления), которую можно дать клиенту. Переводы ниже минимума сети (обычно $1, BTC $5) автоматически не зачисляются; чтобы их зачислили, свяжитесь с нами. Блокировка адресов (/v1/wallet/block-address) пока не поддерживается.

Вебхуки

Когда меняется статус счёта (paid, paid_over, wrong_amount_waiting, wrong_amount, cancel) и при каждом переводе на статический кошелёк, мы отправляем POST с JSON на url_callback. Ответ 2xx считается доставкой; иначе повторяем через 1 минуту, 5 минут, 30 минут, 2 часа, 12 часов, 24 часа и ещё 24 часа. Можно также отправить повторно из кабинета или через /v1/payment/resend.

{
  "type": "payment",
  "uuid": "6f1c2a7e-…",
  "order_id": "order_1042",
  "amount": "42.00",
  "payment_amount": "42",
  "payment_amount_usd": "42.00",
  "merchant_amount": "41.58",
  "commission": "0.42",
  "is_final": true,
  "status": "paid",
  "from": "TQ8m…",
  "wallet_address_uuid": null,
  "network": "tron",
  "currency": "USD",
  "payer_currency": "USDT",
  "payer_amount": "42",
  "payer_amount_exchange_rate": "1",
  "additional_data": null,
  "txid": "9c1e…",
  "sign": "5f0c9b…"
}

Проверка подписи (обязательна)

Подпись — это поле sign тела вебхука: удалите sign, закодируйте остальное так же, как PHP json_encode (компактно, / экранируется как \/, не-ASCII символы не экранируются), и md5(base64(закодированное) + API key) должно совпасть с sign. Используйте API key того же режима. Один и тот же вебхук может прийти более одного раза — убирайте дубликаты по uuid + status.

Если проверка не проходит, вставьте исходное тело вебхука в проверку подписи: она показывает результат каждого шага и отмечает, где ваш результат отличается (всё выполняется в вашем браузере; API key никуда не отправляется). Любой вебхук из раздела «Разработчикам › Журнал вебхуков» в кабинете открывается в проверке одним щелчком.

import crypto from "node:crypto";

function verify(rawBody, apiKey) {
  const { sign, ...data } = JSON.parse(rawBody);
  const json = JSON.stringify(data).replaceAll("/", "\\/");
  const expected = crypto.createHash("md5").update(Buffer.from(json).toString("base64") + apiKey).digest("hex");
  return typeof sign === "string" && sign.length === expected.length && crypto.timingSafeEqual(Buffer.from(sign), Buffer.from(expected));
}

$data = json_decode(file_get_contents('php://input'), true);
$sign = $data['sign'] ?? '';
unset($data['sign']);
$expected = md5(base64_encode(json_encode($data, JSON_UNESCAPED_UNICODE)) . $apiKey);
if (!hash_equals($expected, $sign)) {
    http_response_code(401); exit;
}

import base64, hashlib, hmac, json

def verify(raw_body: bytes, api_key: str) -> bool:
    data = json.loads(raw_body)
    sign = data.pop("sign", "")
    encoded = json.dumps(data, separators=(",", ":"), ensure_ascii=False).replace("/", "\\/")
    expected = hashlib.md5((base64.b64encode(encoded.encode()).decode() + api_key).encode()).hexdigest()
    return hmac.compare_digest(expected, sign)

Тестовый режим

Счета, созданные с Test merchant и API key, работают в тестовых сетях без настоящих денег. На странице оплаты есть кнопка «Симулировать оплату» (полная / половина / переплата), так что вы увидите смену статусов и вебхуки, не добывая тестовые монеты.

• POST /v1/test-webhook/payment, /v1/test-webhook/wallet: отправляют подписанный пример вебхука на url_callback (передайте обязательный url_callback на одном из ваших зарегистрированных доменов, а также currency, network, при желании status, order_id), чтобы отладить код проверки.
• Кабинет «Разработчикам › Интеграция и ключи» → «Отправить тестовое уведомление»: отправляет пример на ваш URL вебхука.
• Кабинет «Разработчикам › Журнал вебхуков»: каждая попытка доставки с временем, целевым URL, HTTP-статусом, длительностью, телом запроса и ответом вашего сервера (первые 4 КБ); фильтр по заказу или статусу и повторная отправка одним щелчком. Хранится 30 дней.

Переход с Cryptomus

1. Кабинет «Разработчикам › Интеграция и ключи» → создайте merchant и API key.
2. Замените в коде https://api.cryptomus.com на https://blockwallets.io и используйте новые merchant и API key.
3. Добавьте свои домены в разделе «Домены сайта» (url_callback / url_return / url_success принимают только их).

Поддерживаются: /v1/payment, /v1/payment/info, /v1/payment/list, /v1/payment/services, /v1/payment/resend, /v1/wallet, /v1/test-webhook/payment, /v1/test-webhook/wallet. Отличия: счета выставляются только в USD / USDT / USDC (все 1:1, без курсового спреда); commission — наша комиссия платформы (полученная сумма × ставка продавца на момент создания счёта — стандартная 1%, по обороту вплоть до 0.5%; с доли, которую покрывает клиент, ничего не берётся дважды), а merchant_amount = получено − commission; когда клиент платит в BTC / LTC / DOGE / BCH / TRX / BNB / ETH / POL / AVAX / OKB / SOL / TON, мы берём медиану нескольких бирж, зафиксированную на 30 минут — payer_amount это количество монет к отправке, payer_amount_exchange_rate — стоимость одной монеты в долларах США, а платёж пересчитывается в payment_amount_usd по зафиксированному курсу (монеты остаются у нас, ничего не обменивается); сети tron / bsc / eth / base / polygon / arbitrum / optimism / avalanche / xlayer / btc / ltc / doge / bch / sol / ton; минимальный срок жизни счёта 10 минут; нет is_refresh и блокировки статических кошельков; по умолчанию вебхуки приходят с меняющихся IP; если вы используете список разрешённых IP, включите в кабинете «Вебхуки с фиксированного IP» в разделе «Разработчикам › Интеграция и ключи», и вебхуки будут приходить только с 18.163.145.41 — список разрешённых адресов лишь дополнительный слой, продолжайте проверять sign.

Переходите с NOWPayments или Coinbase Commerce? У нас есть совместимые API для обоих — смените базовый URL и ключи; см. руководство по переходу.

Сети и суммы

Комиссии ERC-20 высоки, поэтому минимум $5; комиссии Bitcoin тоже немалые, минимум $5; во всех остальных сетях $1. Клиенты должны отправлять в той сети, которая указана на странице оплаты — деньги, отправленные в другой сети, автоматически не зачисляются. BTC / LTC / DOGE / BCH отображаются как «обнаружен» сразу, как попадают в мемпул, и засчитываются, когда наберут достаточно подтверждений; заменённые (RBF) или отброшенные транзакции не засчитываются. Нативные монеты (TRX, BNB, ETH, POL, AVAX, OKB, SOL, TON) котируются по зафиксированному курсу и зачисляются в долларах США, как BTC / LTC / DOGE / BCH; указывайте и сеть, и монету: для счетов network: "bsc", to_currency: "BNB", для статических кошельков network: "bsc", currency: "BNB". Одна сеть без монеты по умолчанию означает USDT в этой сети (USDC в Base). Переводы, сделанные контрактами (мультиподпись, пакетные выплаты), тоже принимаются; в некоторых сетях хеш их транзакции недоступен, и txid в вебхуке равен null.

Ошибки

{ "state": 1, "message": "amount must be a number like 10.28" }

Если подпись неверна (Invalid Sign.), в ответе есть объект debug: body_base64 — base64 тела запроса, которое мы получили (ваше собственное содержимое, но никогда не API key), а body_bytes — его длина. Сравните с base64, которое вы подписывали: если они различаются, отправленное вами тело не совпадает с подписанной строкой (ваш фреймворк сериализовал его заново, прокси изменил кодировку, добавился завершающий перевод строки); если совпадают, неверен API key. Вставьте его в проверку подписи, чтобы увидеть первое отличие.

{
  "state": 1,
  "message": "Invalid Sign.",
  "debug": {
    "body_base64": "eyJhbW91bnQiOiI0Mi4wMCIsImN1cnJlbmN5IjoiVVNEIiwi…",
    "body_bytes": 158,
    "sign_formula": "md5(body_base64 + API key)"
  }
}

Вопросы

Клиенты пополняют на любую сумму — какой способ выбрать?

Счета. Пусть клиент вводит сумму на вашей странице пополнения, создайте на неё счёт и зачислите payment_amount_usd, когда платёж придёт. Статические кошельки нужны, только если клиенты должны сохранить один адрес и многократно отправлять на него.

Что, если клиент заплатил меньше?

До истечения срока клиент может отправить разницу на странице оплаты (она показывает, сколько ещё нужно; статус wrong_amount_waiting, а если при первой недоплате до конца оставалось менее 30 минут, срок переносится на 30 минут вперёд). Если к истечению всё ещё не хватает, счёт получает статус wrong_amount, а payment_amount_usd в вебхуке — полученная сумма; сервисы с пополнением могут просто зачислить её.

Что, если клиент заплатил поздно или дважды?

Деньги, пришедшие после истечения срока, всё равно зачисляются и приходят уведомлением; деньги, пришедшие после полной оплаты счёта, тоже фиксируются и видны в кабинете.

Что, если клиент отправил в неверной сети?

Например, счёт в TRON, а он отправил из BNB Chain: платёж автоматически не зачисляется — напишите нам, и мы разберём его вручную.

Сколько это стоит?

1% с каждого полученного платежа, ставка автоматически снижается по обороту прошлого месяца (0.9% от $50,000, 0.8% от $100,000, 0.7% от $250,000, 0.6% от $500,000 и 0.5% от $1,000,000), без абонентской платы и платы за подключение. Комиссию сети клиент платит при отправке; чтобы переложить её на клиента, задайте subtract при создании счёта или значение по умолчанию в кабинете. За вывод дополнительная комиссия не взимается. См. цены.

Когда деньги попадут ко мне?

Они зачисляются на ваш баланс сразу после подтверждения платежа. Запросите вывод на свой кошелёк в разделе «Средства › Баланс и вывод»; после нашего одобрения мы выплачиваем, и транзакция в блокчейне появляется в истории выводов.

Можно также включить автовывод: когда доступный баланс достигает заданной вами суммы или раз в сутки в 00:00 UTC выводится весь доступный баланс. Автоматические выводы проверяются так же, и каждое изменение настроек отправляет уведомление на вашу почту.