Blockchain API для платежей в e-commerce
Как интернет-магазин принимает и выплачивает криптовалюту через blockchain API: адрес на заказ, вебхуки, подтверждения, возвраты и проверка в тестовой сети.
Проверил(а) Maurice Sobiera
Blockchain API для e-commerce — это REST-интерфейс, который позволяет интернет-магазину создавать платёжные адреса, обнаруживать входящие криптоплатежи и отправлять возвраты или выплаты без запуска собственных нод блокчейна. Магазин обращается к API по HTTPS и получает вебхуки, когда приходит платёж. Ключи и правила подтверждений остаются под контролем магазина.
Как интернет-магазин принимает криптоплатежи через API?
Выделите каждому заказу собственный адрес для депозита, отслеживайте его вебхуком и отмечайте заказ оплаченным, когда подтверждённая сумма совпадает. Процесс состоит из пяти шагов:
- Создайте адрес для заказа через
POST /api/v2/{blockchain}/addresses. - Зарегистрируйте вебхук для этого адреса через
POST /api/v2/{blockchain}/webhooksи передайте ID заказа в полеreference. - Покажите клиенту адрес, сумму и срок действия.
- Когда придёт вебхук, проверьте заголовок
X-Signatureи сверьте сумму и токен в блокчейне. - Выдайте товар после того количества подтверждений, которое вы выбрали.
Один адрес на заказ снимает неопределённость: любой платёж на этот адрес относится к этому заказу. Руководство по платёжным вебхукам показывает код приёмника, а руководство по Laravel показывает тот же процесс во фреймворке PHP.
Что должна хранить запись заказа?
Храните достаточно данных, чтобы самостоятельно решить, завершён ли платёж. Вебхук сообщает, что что-то произошло. Запись заказа сообщает, что должно было произойти.
| Поле | Назначение |
|---|---|
| ID заказа | Также передаётся в reference вебхука, чтобы сопоставить событие |
| Сеть и токен | Блокчейн и контракт, которые должен использовать клиент |
| Адрес депозита | Адрес, созданный для этого заказа |
| Ожидаемая сумма | Пересчитанная из цены магазина в момент выставления счёта |
| Срок действия счёта | Время, после которого цена больше не действительна |
| Необходимые подтверждения | Правило, которое вы выбрали для этой сети и размера заказа |
| Статус | Ожидает оплаты, оплачен частично, оплачен, истёк или возвращён |
С этими полями обработчик вебхука становится коротким сравнением. Найдите заказ по reference, проверьте, что сеть и токен совпадают, прибавьте сумму к уже полученной и обновите статус. Платёж не того токена на правильный адрес — обычный случай, который обработчик должен ловить, потому что адрес может получить любой токен своей сети.
Сколько подтверждений должен ждать магазин?
Это зависит от сети и стоимости заказа. В документации разработчиков Bitcoin по обработке платежей сказано, что транзакции с нулём подтверждений не стоит доверять без анализа рисков, а программное обеспечение, которое обрабатывает транзакции высокой стоимости, должно ждать минимум шесть подтверждений, что занимает около часа. В TRON блок считается зафиксированным (solidified), когда его построили как минимум 19 из 27 Super Representatives. По документации по консенсусу TRON это занимает около минуты в обычных условиях.
Выберите правило для каждой сети и для каждого размера заказа, запишите его и примените в коде. Цифровой товар с низкой стоимостью можно отправить после одного подтверждения. Физический товар высокой стоимости должен ждать дольше.
Что делать с изменением цен?
Фиксируйте цену в вашей валюте, пересчитывайте её при выставлении счёта и давайте счёту истекать. Документация Bitcoin отмечает, что курсы обмена меняются, что счета, привязанные к фиату, должны истекать, и что большинство платёжных систем закрывают счета через 10–20 минут. Более короткое окно снижает риск курса, но повышает вероятность того, что клиент заплатит с опозданием.
Заранее решите, что делать с запоздавшим или частичным платежом. Большинство магазинов возвращают его или просят клиента доплатить разницу на тот же адрес.
Как работают возвраты и выплаты?
Отправляйте их как обычные транзакции с адреса, который контролируете вы. Для нативной монеты используйте POST /api/v2/{blockchain}/transactions, а для токенов — эндпоинты токенов, например transactions/erc20, transactions/bep20 или transactions/trc20. Для возврата нужен обратный адрес клиента, который приходится запрашивать отдельно. Отправитель платежа не всегда тот кошелёк, на который должны вернуться деньги, например когда платёж пришёл с биржи.
Держите средства на адресах заказов недолго. Переводите входящие платежи в кошелёк, который вы храните офлайн, и используйте адреса заказов только для приёма. Наши советы по безопасности объясняют, как хранить ключи.
Как контролировать сетевые комиссии?
Закладывайте комиссии на стороне отправителя. Перенос токенов с адреса заказа стоит газа в сетях EVM и Energy или Bandwidth в TRON, и на адресе заказа должно быть достаточно нативной монеты для этого. В TRON спонсирование или аренда Energy снижает стоимость переводов TRC-20. Наша документация по TronFuel и устаревшему Paymaster описывает текущий вариант. TronFuel — отдельный сервис со своей документацией.
Как проверить интеграцию перед запуском?
Используйте тестовые сети. Добавьте заголовок X-Network: testnet к любому запросу, и тот же вызов выполнится в тестовой сети без реальных средств. Проверьте полный заказ, недоплату, переплату, опоздавший платёж и вебхук, который не дошёл до вашего сервера. Неудачные вебхуки не повторяются автоматически. Они появляются по адресу GET /webhooks/notifications/failed и могут быть отправлены повторно, поэтому магазин должен проверять этот список.
Нужно ли проверять клиентов?
Это зависит от вашей юрисдикции и бизнес-модели, и API за вас этого не решает. Chaingateway работает без кастодии. Прочитайте нашу статью о KYC для криптоплатежей, прежде чем решать, какие проверки применяются к вашему магазину.
Готовы собрать это сами? Получите свой API-ключ — 7-дневный пробный период, без карты — или посмотрите API блокчейна для полного справочника по эндпоинтам.