Перейти к основному содержимому

Интеграция со смарт-контрактами

Принимайте криптовалюту напрямую на свой кошелёк через смарт-контракты Volet.com. Клиенты подключают свои криптокошельки и подтверждают транзакции, а смарт-контракт проводит платёж и распределяет средства и комиссию за обработку ончейн.

Ни вам, ни вашим клиентам не нужен аккаунт Volet.com. Кошелёк для приёма средств под вашим контролем, а подтверждение платежей выполняет ваше собственное приложение.

Важно: в этой интеграции не используются Hosted Checkout и инвойсы Merchant API. Страницу оплаты предоставляет ваше приложение, и оно же проверяет платежи напрямую в блокчейне. Уведомлений о статусе платежа Volet.com в этом сценарии не отправляет.

Как это работает​

В некастодиальной платёжной интеграции участвуют три компонента:

  • Ваше приложение: создаёт заказы, инициирует платежи и проверяет транзакции.
  • Кошелёк клиента: подключается к вашему приложению и подписывает платёжные транзакции.
  • Смарт-контракт Volet.com: проводит платежи, переводит средства на ваш кошелёк и удерживает комиссию за обработку.

Порядок платежа​

  1. Создайте заказ. Ваш бэкенд сохраняет сумму платежа, актив, блокчейн-сеть и кошелёк мерчанта для приёма средств.
  2. Подключите кошелёк клиента. Ваше приложение запрашивает подключение совместимого криптокошелька.
  3. Рассчитайте платёж. Функция смарт-контракта previewPayment() возвращает комиссию за обработку и сумму, которую должен заплатить клиент.
  4. Запросите оплату. Клиент проверяет и подписывает транзакцию. Для оплаты токенами, например USDT, сначала может потребоваться отдельное одобрение.
  5. Транзакция обрабатывается. Смарт-контракт переводит средства на ваш кошелёк и удерживает комиссию за обработку.
  6. Сохраните транзакцию. Ваше приложение сохраняет хеш транзакции (txid) и связывает его с заказом.
  7. Проверьте платёж. Ваш бэкенд самостоятельно проверяет транзакцию: статус, сеть, контракт, актив, получателя, сумму и финальность в блокчейне.
  8. Завершите заказ. После успешной проверки приложение помечает заказ как оплаченный и выполняет его ровно один раз.

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

Выберите сеть​

Выберите руководство по интеграции для тех сетей и активов, которые хотите принимать.

СетьАктивы в этих руководствахКошельки клиентовРуководство по интеграции
Ethereum и BNB Smart ChainETH, BNB, USDT (ERC-20 и BEP-20)MetaMask и кошельки с поддержкой WalletConnectИнтеграция EVM
TRONTRX, USDT (TRC-20)TronLink; WalletConnect через отдельную интеграциюИнтеграция TRON

Для других сетей и активов может понадобиться отдельная реализация. Обзор продукта и доступных вариантов — в статье Некастодиальные криптоплатежи.

Перед началом​

Вам понадобятся:

  • Кошелёк мерчанта: криптокошелёк под вашим контролем для приёма платежей.
  • Приложение: сайт или приложение со страницей оплаты.
  • Бэкенд и база данных: чтобы создавать заказы, хранить данные транзакций и проверять платежи.
  • Интеграция кошельков: библиотека подключения кошельков, совместимая с выбранной сетью.
  • Данные смарт-контракта: адреса контрактов-процессоров, ABI и параметры от Volet.com.
  • Доступ к блокчейну: RPC-провайдер или облачный блокчейн-сервис для проверки транзакций.

В зависимости от интеграции также может понадобиться WalletConnect Project ID или API-ключ TronGrid.

Свяжитесь с нашей командой, чтобы получить данные смарт-контракта и обсудить интеграцию.

Комиссия за обработку​

Смарт-контракт рассчитывает комиссию за обработку через previewPayment(). Ваше приложение выбирает, кто её платит:

  • Платит клиент: комиссия добавляется к сумме платежа. Мерчант получает запрошенную сумму.
  • Платит мерчант: комиссия вычитается из запрошенной суммы. Мерчант получает остаток.

Комиссии блокчейн-сети, например газ в Ethereum или Energy и Bandwidth в TRON, оплачиваются отдельно от комиссии Volet.com за обработку.

Всегда используйте суммы, которые возвращает previewPayment(), а не рассчитывайте комиссию вручную.

Параметры контракта и расчёт комиссии описаны в справочнике по смарт-контрактам.

Руководства по интеграции​

Чтобы завершить интеграцию:

  1. Реализуйте платёжный сценарий. По руководству для Ethereum и BNB Smart Chain или руководству для TRON подключите кошельки клиентов, настройте смарт-контракты и отправляйте платежи.
  2. Реализуйте проверку платежей. По статье Проверка платежей и отслеживание заказов сопоставляйте транзакции в блокчейне с заказами и исключите повторное выполнение заказов.
  3. Протестируйте интеграцию. Перед запуском проверьте успешные и неуспешные платежи, одобрения токенов, отклонённые транзакции и проверку платежей.

Дополнительно:

Примеры интеграции​

В руководствах для каждой сети есть HTML-примеры, которые можно открыть в браузере или скачать:

  • Пример для EVM (example-evm.html): подключение кошелька, расчёт комиссии, платежи в ETH, BNB и USDT, отслеживание транзакций.
  • Пример для TRON (example-tron.html): подключение TronLink, расчёт комиссии, платежи в TRX и USDT, отслеживание транзакций.

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

Важно: оба примера работают с контрактами в основной сети (mainnet). Любой платёж, подтверждённый в кошельке, — это реальные средства. Для тестовых платежей нужны два кошелька: один для отправки средств, другой для получения.

Ограничения демо: примеры хранят историю транзакций в localStorage браузера. В них нет рабочего бэкенда и полной проверки платежей. Доработайте и протестируйте их, прежде чем принимать реальные платежи клиентов.

Интеграция с помощью AI-ассистента​

Встроить платежи через смарт-контракты Volet.com в ваше приложение может помочь AI-ассистент для программирования.

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

Передайте AI-ассистенту промпт, исходный код приложения и нужные руководства по интеграции.

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