← Блог
10 мин чтения
|
Опубликовано
|
Обновлено

Blockchain API для платежей в e-commerce

Как интернет-магазин принимает и выплачивает криптовалюту через blockchain API: адрес на заказ, вебхуки, подтверждения, возвраты и проверка в тестовой сети.

Главы
C
Chaingateway Team
Эксперты по блокчейну

Проверил(а) Maurice Sobiera

Blockchain API для e-commerce — это REST-интерфейс, который позволяет интернет-магазину создавать платёжные адреса, обнаруживать входящие криптоплатежи и отправлять возвраты или выплаты без запуска собственных нод блокчейна. Магазин обращается к API по HTTPS и получает вебхуки, когда приходит платёж. Ключи и правила подтверждений остаются под контролем магазина.

Как интернет-магазин принимает криптоплатежи через API?

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

  1. Создайте адрес для заказа через POST /api/v2/{blockchain}/addresses.
  2. Зарегистрируйте вебхук для этого адреса через POST /api/v2/{blockchain}/webhooks и передайте ID заказа в поле reference.
  3. Покажите клиенту адрес, сумму и срок действия.
  4. Когда придёт вебхук, проверьте заголовок X-Signature и сверьте сумму и токен в блокчейне.
  5. Выдайте товар после того количества подтверждений, которое вы выбрали.

Один адрес на заказ снимает неопределённость: любой платёж на этот адрес относится к этому заказу. Руководство по платёжным вебхукам показывает код приёмника, а руководство по 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 блокчейна для полного справочника по эндпоинтам.

C
Chaingateway Team
Эксперты по блокчейну

Команда Chaingateway стремится упростить интеграцию блокчейна для разработчиков по всему миру.