Интеграция оплаты в USDC
Практическое инженерное руководство по подключению платежей в USDC к оформлению заказа: паттерны API, выбор сети, идемпотентность вебхуков и сбои, с которыми вы столкнётесь в продакшене.
Кратко
Интеграция оплаты в USDC следует знакомому паттерну: создайте платёжное намерение на своём сервере (сумма, валюта, предпочтения по сетям), получите от эквайера URL хостинговой страницы оплаты или конфигурацию виджета, дайте покупателю оплатить из своего кошелька и идемпотентно обработайте вебхук о подтверждении. Важнее всего инженерные решения в четырёх областях: выбор сети (по умолчанию Solana или Base с комиссиями меньше цента), идемпотентность вебхуков (используйте ID заказа + хеш транзакции), процесс возврата (собирайте адрес кошелька при оформлении заказа, предоставьте API возвратов) и удобный UX на этапе подписи в кошельке (диплинки в мобильные кошельки, QR-код как запасной вариант на компьютере). При правильной реализации оплата в USDC занимает менее 30 секунд от начала до конца и обходится мерчанту в 0.3%–1% в зависимости от эквайера.
Стандартная структура API
API эквайринга USDC в целом следуют паттерну платёжного намерения, который популяризировал Stripe. Минимальный набор:
Сервер создаёт платёжное намерение
POST /v1/paymentsс телом, содержащимamount,currency(USD, если цена указана в фиате; USDC, если цена указана в стейблкоине),settlement_preference(USDC или фиат),networks(список разрешённых сетей),order_id(ваш ключ идемпотентности),success_url,cancel_urlи блокmetadataдля вашей собственной сверки.Эквайер возвращает URL страницы оплаты или конфигурацию виджета
Для хостинговой страницы оплаты — URL, на который перенаправляется покупатель. Для встроенного виджета — клиентская конфигурация (публичный ключ, ID намерения), которую загружает виджет. Оба варианта обрабатывают определение кошелька, выбор сети и отображение котировки.
Покупатель подписывает транзакцию в кошельке, ончейн-перевод отправляется в сеть
На мобильных устройствах — переход по диплинку в MetaMask, Phantom, Trust и т. д. На компьютере — QR-код WalletConnect или всплывающее окно расширения браузера. Покупатель проверяет сумму и подписывает транзакцию.
Эквайер дожидается подтверждений и отправляет вебхук
POST your_webhook_urlс данными, содержащимиevent_type: “payment.succeeded”,order_id,amount,tx_hash,networkи подпись, которую вы проверяете с помощью секрета вебхуков эквайера.Сервер идемпотентно отмечает заказ как оплаченный
Проверьте подпись вебхука, найдите
(order_id, tx_hash)в своей БД, отметьте заказ как оплаченный, если это ещё не сделано, и запустите выполнение заказа.
Выбор сети
Выбор принимаемых сетей — это компромисс между UX и стоимостью:
- Solana: сетевая комиссия меньше цента, подтверждение меньше чем за секунду. Лучший вариант по умолчанию при небольшом среднем чеке.
- Base: сетевая комиссия в несколько центов, подтверждение за несколько секунд. Широкая поддержка кошельков; хороший вариант по умолчанию для криптоаудитории.
- Polygon, Arbitrum: комиссии и скорость сопоставимы с Base. Их можно добавить, но это не обязательно.
- Основная сеть Ethereum: сетевая комиссия $1–$8+ в зависимости от газа. Неудобно для покупателей при небольших заказах. Принимайте при высоком среднем чеке (>$500) или как запасной вариант.
- Tron: если вы ориентируетесь на потоки USDT в Азии и Африке, стоит рассмотреть поддержку USDT в сети TRON наряду с USDC.
Идемпотентность вебхуков
Вебхуки отправляются повторно. Ваш обработчик должен быть идемпотентным. Стандартный паттерн:
- Проверьте подпись вебхука с помощью HMAC-SHA256 и секрета вашего эквайера.
- Извлеките
(order_id, tx_hash)из данных. - Найдите эту пару в своей таблице
processed_payments. - Если она найдена: верните 200 OK и больше ничего не делайте.
- Если не найдена: вставьте строку (с ограничением UNIQUE на эту пару), затем отметьте заказ как оплаченный в основной таблице заказов, затем запустите выполнение заказа.
- Выполняйте шаг 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.