Документация разработчика

Создать заказ на оплату стейблкоинами

Создавайте заказы USDT / USDC на сервере с подписанными API-запросами. Проверьте параметры, сеть, полную сумму, ссылку на оплату, срок действия и настройки Webhook.

POST /api/v1/order/create

Требуется аутентификация

Включите X-Bolt-Key, X-Bolt-Timestamp и X-Bolt-Signature. Используйте текущую миллисекунду timestamp и подпишите timestamp вместе с точным необработанным телом запроса.

USDTUSDC

Точное соответствие суммы

Почему сумма платежа в ответе API может быть немного больше?

План запуска

3 фиксированные цифры

Бизнес-профи

2–6 настраиваемых

Система округляет сумму вверх до настроенной точности. Если другой ожидающий заказ в той же сети, валюте и кошельке уже использует эту сумму, небольшой добавочный шаг отличает новый заказ. Сумма к оплате никогда не меньше исходной. Бесплатные аккаунты используют 3 знака; участники Pro могут выбрать 2–6. Используйте payment.amount из ответа.

Последовательность сопоставления

Создать заказ

1

amount

Ваш сервер отправляет сумму расчета, а BoltUtil возвращает сумму, подлежащую оплате в сети.

Показать оформление заказа

2

payment.amount

Отображение точной возвращаемой суммы, сети и адреса получения плательщику.

Сверка платежа в блокчейне

3

Webhook

Монитор сопоставляет сеть, адрес, токен, сумму и статус заказа, прежде чем уведомить вас.

Примечания по интеграции

1

Отображать payment.amount из ответа на создание заказа, а не сумму запроса или исходную цену продукта.

2

Не округляйте, не усекайте и не удаляйте небольшое десятичное смещение при отображении инструкций по платежу.

3

Изменение точности смещения влияет только на вновь созданные ордера, а не на существующие отложенные ордера.

4

Проверьте подпись Webhook и дедупликацию уведомлений перед выполнением с помощью externalOrderId и подтверждением статуса платежа. Платеж, ожидающий подтверждения, не считается успешным.

01. Тело запроса

JSON Payload
amount
Обязательно
Decimal

Исходная сумма продукта или бизнес-заказа в валюте, указанной в currency. Отправьте строку, чтобы избежать потери точности чисел с плавающей запятой. Плательщик должен оплатить возвращенный payment.amount, а не это значение.

Базовый минимум: 1.00. Также необходимо соблюдать минимум, настроенный для выбранных сети и валюты.Предел точности: до 6 знаков после запятойУгроза безопасности: строго запрещайте передачу сумм, рассчитанных во внешнем интерфейсе. Всегда извлекайте значения из внутренней базы данных.
externalOrderId
Обязательно
String

Ваш бизнес-заказ ID, используемый для связи с заказом BoltUtil. Запросы используют externalOrderId; ответ на создание возвращает merchantExternalId, а Webhooks возвращает externalOrderId.

Должен быть глобально уникальным для каждого продавцаПоддерживается: буквы, цифры, символы подчеркивания (_), дефисы (-)Ограничение длины: 6–64 символаДубликат ID возвращает ошибку, а не существующий порядок.
network
Обязательно
String

Выберите платежную сеть, используя одно из значений в верхнем регистре ниже. Например, используйте BASE для Base или ERC20 для Ethereum.

Пример значения

"network": "BASE"
Допустимые значения: TRC20, ERC20, BEP20, POLYGON, SOLANA, BASEПоказывать ту же сеть при оформлении заказа.
currency
Обязательно
String

Выберите валюту платежа. Передавайте только USDT или USDC; укажите сеть отдельно в network.

Пример значения

"currency": "USDC"
Допустимые значения: USDT, USDC⚠️ TRC20 поддерживает только USDT. Для других пар требуется включенный маршрут и действующий принимающий кошелек.
orderDesc
String

Необязательная сводка о продукте или бизнесе для записей заказов. Текущая проверка не отображает это поле.

Предлагаемый формат: пополнение – [учетная запись пользователя]Максимальная длина: 255 символов
notifyUrl
URL

Приёмник Webhook для этого заказа. Если этот параметр опущен, используется включенный адрес по умолчанию на панели управления продавца.

Должен быть HTTPSДолжен быть общедоступнымНеизменяемый: этот URL нельзя изменить после создания заказа.Перед созданием заказа настройте и включите Webhook и секрет подписи на панели управления. Этот параметр не заменяет эту конфигурацию.Максимальная длина: 255 символов
returnUrl
URL

После завершения оплаты или выбора пользователем возврата система оформления заказа перенаправляет браузер на этот URL. Это всего лишь навигационный пункт назначения, который не является подтверждением успешного платежа.

Подтвердите платеж с помощью подписанного Webhook или запроса статуса заказаЕсли этот параметр опущен, значением по умолчанию является https://boltutil.com.Максимальная длина: 255 символов
expiredMinutes
Long

Количество минут, в течение которых заказ остается подлежащим оплате после создания. Бесплатный план рассчитан на 30 минут; Участники Pro могут выбрать 15–60 минут.

Настраиваемый диапазон: 15–60 минутПо умолчанию: 30 минутТолько участники Pro могут настраивать это значение; бесплатный план рассчитан на 30 минутБесплатные учетные записи игнорируют пользовательские значения в допустимом диапазоне и используют 30 минут. В качестве фактического срока действия используйте time.expireTimestamp.
metadata
Map

Определенный продавцом JSON data. BoltUtil не изменяет его и возвращает неизмененным в ответе на создание заказа, ответе на статус заказа и Webhook.

Формат: стандартный объект JSONВозвращается без изменений и никогда не используется для сопоставления платежейНе более 10 ключей верхнего уровня

02. Подробности ответа

application/json
orderToken
BoltUtil Идентификатор заказа для открытия оформления заказа. Запросы продавца API используют externalOrderId.
merchantExternalId
Соответствует externalOrderId в запросе.
status
PENDING после успешного создания. Информацию о последующих состояниях оплаты и обратного вызова см. в документации по статусу заказа.
Проверка статуса заказа →
checkoutUrl
Эксклюзивная ссылка для оплаты при оформлении заказа.
returnUrl
Обратный адрес кассы. По умолчанию используется https://boltutil.com, если он опущен.
metadata
Пользовательский транзитный объект data.

data.payment { ... }

address
Кошелек продавца-получателя, используемый этим заказом. Этот адрес может использоваться несколькими заказами; новый адрес для каждого заказа не создается.
amount
Точная сумма к оплате, возвращается в виде строки. Отобразите его полностью, без округления и усечения.
rawAmount
Сумма в наименьшей единице токена, возвращаемая в виде целочисленной строки: payment.amount × 10^payment.decimal. Для decimal = 6 один токен равен 1 000 000 наименьших единиц.
currency
Символ валюты.
network
Идентификатор сети.
qrData
Строка адреса для создания платёжного QR-кода. Она не содержит сумму, валюту или сеть. Показывайте payment.amount, currency и network отдельно.
decimal
Точность токена в данной сети для пересчёта rawAmount. Это не точность, используемая для различения сумм заказов.

data.time { ... }

expireTimestamp
В data.time: срок действия ордера указывается в миллисекундах Unix timestamp.
serverTimestamp
В data.time: время сервера, когда был сгенерирован ответ, в миллисекундах Unix timestamp.

Распространенные ошибки

Это распространенные случаи. Используйте фактический статус HTTP и код/сообщение ответа для диагностики сбоев. Ответ с ошибкой не является результатом платежа.

  • 401: проверьте ключ API, необработанную подпись и текущую миллисекунду timestamp (в пределах 5 минут от часов сервера).
  • 400: externalOrderId уже существует. Запросите исходный заказ вместо создания дубликата бизнес-заказа.
  • 400: проверьте необходимые параметры, доступную сеть/актив, принимающий кошелек и включенную конфигурацию Webhook.
  • 429: превышен лимит запросов или дневная квота бесплатного создания заказов. Проверьте код ошибки и message.
create / cURL
# Run against your account only when ready; this sends an API request.
: "${BOLTUTIL_API_KEY:?Set your complete API Key}"
: "${BOLTUTIL_WEBHOOK_SECRET:?Set your Webhook secret}"
timestamp=$(python3 -c 'import time; print(int(time.time()*1000))')
body='{"amount":"25.00","currency":"USDT","network":"TRC20","externalOrderId":"INV-20260209-99281"}'
signature=$(printf '%s.%s' "$timestamp" "$body" | openssl dgst -sha256 -hmac "$BOLTUTIL_WEBHOOK_SECRET" | awk '{print $NF}')

curl --request POST "https://api.boltutil.com/api/v1/order/create" \
  --header 'Content-Type: application/json' \
  --header "X-Bolt-Key: $BOLTUTIL_API_KEY" \
  --header "X-Bolt-Timestamp: $timestamp" \
  --header "X-Bolt-Signature: $signature" \
  --data-binary "$body"

Примерами являются адреса, хеши транзакций и заказы. Замените их собственным тестом data.

Base URL

PROD
https://api.boltutil.com