DPT Learn — Эквайринг

Интеграция оплаты в USDC

Практическое инженерное руководство по подключению платежей в USDC к оформлению заказа: паттерны API, выбор сети, идемпотентность вебхуков и сбои, с которыми вы столкнётесь в продакшене.

Кратко

Интеграция оплаты в USDC следует знакомому паттерну: создайте платёжное намерение на своём сервере (сумма, валюта, предпочтения по сетям), получите от эквайера URL хостинговой страницы оплаты или конфигурацию виджета, дайте покупателю оплатить из своего кошелька и идемпотентно обработайте вебхук о подтверждении. Важнее всего инженерные решения в четырёх областях: выбор сети (по умолчанию Solana или Base с комиссиями меньше цента), идемпотентность вебхуков (используйте ID заказа + хеш транзакции), процесс возврата (собирайте адрес кошелька при оформлении заказа, предоставьте API возвратов) и удобный UX на этапе подписи в кошельке (диплинки в мобильные кошельки, QR-код как запасной вариант на компьютере). При правильной реализации оплата в USDC занимает менее 30 секунд от начала до конца и обходится мерчанту в 0.3%–1% в зависимости от эквайера.

Стандартная структура API

API эквайринга USDC в целом следуют паттерну платёжного намерения, который популяризировал Stripe. Минимальный набор:

  1. Сервер создаёт платёжное намерение

    POST /v1/payments с телом, содержащим amount, currency (USD, если цена указана в фиате; USDC, если цена указана в стейблкоине), settlement_preference (USDC или фиат), networks (список разрешённых сетей), order_id (ваш ключ идемпотентности), success_url, cancel_url и блок metadata для вашей собственной сверки.

  2. Эквайер возвращает URL страницы оплаты или конфигурацию виджета

    Для хостинговой страницы оплаты — URL, на который перенаправляется покупатель. Для встроенного виджета — клиентская конфигурация (публичный ключ, ID намерения), которую загружает виджет. Оба варианта обрабатывают определение кошелька, выбор сети и отображение котировки.

  3. Покупатель подписывает транзакцию в кошельке, ончейн-перевод отправляется в сеть

    На мобильных устройствах — переход по диплинку в MetaMask, Phantom, Trust и т. д. На компьютере — QR-код WalletConnect или всплывающее окно расширения браузера. Покупатель проверяет сумму и подписывает транзакцию.

  4. Эквайер дожидается подтверждений и отправляет вебхук

    POST your_webhook_url с данными, содержащими event_type: “payment.succeeded”, order_id, amount, tx_hash, network и подпись, которую вы проверяете с помощью секрета вебхуков эквайера.

  5. Сервер идемпотентно отмечает заказ как оплаченный

    Проверьте подпись вебхука, найдите (order_id, tx_hash) в своей БД, отметьте заказ как оплаченный, если это ещё не сделано, и запустите выполнение заказа.

Выбор сети

Выбор принимаемых сетей — это компромисс между UX и стоимостью:

  • Solana: сетевая комиссия меньше цента, подтверждение меньше чем за секунду. Лучший вариант по умолчанию при небольшом среднем чеке.
  • Base: сетевая комиссия в несколько центов, подтверждение за несколько секунд. Широкая поддержка кошельков; хороший вариант по умолчанию для криптоаудитории.
  • Polygon, Arbitrum: комиссии и скорость сопоставимы с Base. Их можно добавить, но это не обязательно.
  • Основная сеть Ethereum: сетевая комиссия $1–$8+ в зависимости от газа. Неудобно для покупателей при небольших заказах. Принимайте при высоком среднем чеке (>$500) или как запасной вариант.
  • Tron: если вы ориентируетесь на потоки USDT в Азии и Африке, стоит рассмотреть поддержку USDT в сети TRON наряду с USDC.

Идемпотентность вебхуков

Вебхуки отправляются повторно. Ваш обработчик должен быть идемпотентным. Стандартный паттерн:

  1. Проверьте подпись вебхука с помощью HMAC-SHA256 и секрета вашего эквайера.
  2. Извлеките (order_id, tx_hash) из данных.
  3. Найдите эту пару в своей таблице processed_payments.
  4. Если она найдена: верните 200 OK и больше ничего не делайте.
  5. Если не найдена: вставьте строку (с ограничением UNIQUE на эту пару), затем отметьте заказ как оплаченный в основной таблице заказов, затем запустите выполнение заказа.
  6. Выполняйте шаг 5 в одной транзакции БД, чтобы сбой посреди процесса не привёл к двойному выполнению заказа.

Большинство вебхуков эквайринга содержат ID доставки: записывайте его в журнал для отладки, но не используйте как ключ идемпотентности. Подтверждения в сети и повторные отправки эквайера могут порождать дублирующиеся события payment.succeeded с разными ID доставки, но одним и тем же tx_hash; дедупликация должна опираться на ончейн-идентификатор, а не на доставку.

Процесс возврата

Преобладают два паттерна:

  • Возврат отправителю: эквайер отправляет USDC обратно на адрес, с которого изначально платил покупатель. Самый удобный UX; работает, потому что ончейн-запись о платеже содержит адрес отправителя.
  • Возврат на указанный адрес: покупатель указывает адрес для возврата (он может отличаться от исходного, если оплата была с биржи или горячего кошелька). Большинство эквайеров поддерживают это через POST /v1/refunds с параметром destination_address.

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

Сбои в продакшене

  • Покупатель уходит после подписи. Ончейн-перевод отправлен в сеть, но покупатель закрывает вкладку до того, как сработает вебхук. Эквайер всё равно обнаруживает и подтверждает платёж благодаря мониторингу сети; выполнение заказа запускается по вебхуку, а не по переадресации.
  • Покупатель платит не ту сумму. Большинство эквайеров отклоняют несовпадающие суммы на этапе обнаружения в сети. Некоторые допускают приблизительное совпадение (в пределах допуска) и сообщают о расхождении в вебхуке.
  • Покупатель платит не в той сети. Если он подписал транзакцию в Ethereum, а вы принимаете только Solana, платёж полностью выпадает из мониторинга вашего эквайера. Большинство провайдеров возвращают средства через процедуру восстановления; у некоторых они теряются. Сделайте выбор сети при оформлении заказа понятным.
  • Покупатель платит с адреса биржи. Возврат на исходный адрес может не пройти или попасть не на тот счёт. Для любого продукта, где возвраты вероятны, явно запрашивайте адрес для возврата при оформлении заказа.
  • Потеря привязки стейблкоина. Редко, но случается. Если USDC значительно отклонится от привязки в короткий промежуток между котировкой и ончейн-расчётом, разницу покрывает мерчант или эквайер в зависимости от договора.

Добавьте оплату в USDC с DPT Acquiring

От 0.3% за транзакцию. Расчёты в тот же день в USDC или фиате. URL хостинговой страницы оплаты или встраиваемый виджет. Документация по SDK и вебхукам — на merchant.dpt.xyz.

DPT Acquiring · Варианты интеграции с Shopify и WooCommerce