Как интегрировать White Label криптоплатежный шлюз с OxaPay

Интеграция White Label криптоплатежного шлюза — это не только подключение к API. Она означает добавление полноценного процесса криптоплатежей на ваш сайт или в приложение с сохранением контроля над клиентским опытом.

С OxaPay White Label ваша компания может отображать платежный адрес, QR-код, сумму, сеть и статус платежа в собственном интерфейсе. При этом OxaPay управляет базовой платежной инфраструктурой, включая создание платежей, мониторинг блокчейнаи обновления транзакций.

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

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

Подходит ли White Label вашему бизнесу?

Перед началом интеграции важно определить, является ли White Label решение подходящим вариантом для вашего платежного процесса.

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

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

Это решение особенно полезно для компаний, которые хотят:

• сохранять единый брендинг на всем протяжении checkout
• удерживать клиентов внутри собственной платформы
• контролировать отображение платежных инструкций и статусов
• связывать криптоплатежи с существующим процессом обработки заказов
• не создавать блокчейн-платежную инфраструктуру с нуля

Главное отличие — уровень контроля. Ваша компания управляет клиентским интерфейсом и опытом, а OxaPay — платежной инфраструктурой за ним.

Что нужно перед началом работы

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

Ваш сайт или приложение должны иметь backend, который может безопасно взаимодействовать с API OxaPay, хранить платежную информацию и связывать каждый платеж с правильным заказом.

Также нужен callback endpoint , который может получать обновления платежей от OxaPay. Эти обновления позволяют системе понимать, когда клиент начал оплату и когда платеж завершен.

Наконец, платежный интерфейс должен уметь отображать основные данные, такие как:

• сумма платежа
• выбранная криптовалюта
• блокчейн-сеть
• платежный адрес
• QR-код
• оставшееся время оплаты
• последний статус платежа

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

Интеграция White Label криптоплатежного шлюза с OxaPay

1. Создайте Merchant-аккаунт OxaPay

Первый шаг — создать аккаунт OxaPay и открыть merchant-панель.

В панели можно управлять Merchant API Key, настройками платежей, поддерживаемыми валютами, записями транзакций и другими merchant-инструментами.

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

2. Создайте Merchant API Key

Затем создайте Merchant API Key в своем аккаунте OxaPay.

Этот ключ позволяет системе аутентифицировать платежные запросы, отправляемые в API OxaPay. Он всегда должен быть надежно сохранен на вашем backend-сервере.

Merchant API Key нельзя размещать во frontend-коде, публичных репозиториях, браузерных скриптах или в любом другом месте, доступном клиентам.

Backend должен использовать этот ключ при создании White Label платежных запросов. Frontend должен получать только те платежные данные, которые нужны для отображения клиенту.

3. Создайте White Label платежный запрос

Чтобы создать White Label платеж, система отправляет запрос на следующий endpoint:

POST https://api.oxapay.com/v1/payment/white-label

Два обязательных платежных поля:

• Сумма: сумма платежа
• pay_currency: криптовалюта, используемая для платежа

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

Например:

• currency задает валюту, в которой рассчитывается цена заказа, например USD.
• Сеть выбирает блокчейн-сеть, если криптовалюта доступна в нескольких сетях.
• order_id связывает платеж с заказом в вашей системе.
• callback_url указывает OxaPay, куда отправлять обновления платежа.
• lifetime определяет, как долго платеж остается действительным.
• under_paid_coverage определяет допустимую разницу между запрошенной и полученной суммой.

Руководство currency, Сеть, order_id, а также callback_url являются необязательными в API. Однако использование ID заказа и callback URL настоятельно рекомендуется компаниям, которым нужен надежный трекинг заказов.

При успешном запросе OxaPay создает платежную сессию и возвращает данные, необходимые системе для отображения платежа.

4. Получите и отобразите платежную информацию

После создания платежного запроса OxaPay возвращает структурированные платежные данные.

Они могут включать:

• уникальный track_id
• точную сумму платежа
• криптовалюту платежа
• блокчейн-сеть
• платежный адрес
• QR-код
• время истечения

Система должна сохранить track_id и связать его с правильным внутренним заказом. Этот идентификатор помогает отслеживать платеж и при необходимости исследовать его позднее.

Frontend может использовать возвращенные данные для создания брендированной платежной страницы.

Клиент должен иметь возможность:

• сканировать QR-код
• копировать платежный адрес
• копировать точную сумму
• видеть требуемую криптовалюту и сеть
• проверять оставшееся время
• отслеживать текущий статус платежа

Это главное преимущество модели White Label. Клиент завершает платеж в интерфейсе, который спроектирован и брендирован вашей компанией.

Платежная страница также должна предупреждать клиентов не отправлять средства после истечения платежа. Согласно документации OxaPay, сгенерированные White Label адреса действительны только в течение указанного lifetime платежа.

5. Отслеживайте статус платежа

После отправки криптовалюты клиентом OxaPay отслеживает платеж и сообщает о его ходе.

Статусы платежей OxaPay могут включать такие состояния:

• ожидание платежа
• платеж выполняется
• paid
• underpaid
• expired
• принято вручную
• refunded

Вашей компании не нужно показывать клиенту каждый внутренний статус. Интерфейс может преобразовывать их в простые сообщения: «Ожидание платежа», «Платеж обнаружен», «Платеж завершен» или «Срок платежа истек».

Важно, чтобы система не завершала заказ слишком рано.

OxaPay отправляет обновление paying после обнаружения платежной активности. Обычно система должна дождаться окончательного статуса paid перед выдачей товара, активацией услуги или переводом заказа в завершенное состояние.

6. Получайте и проверяйте обновления платежей

OxaPay отправляет обновления платежа на callback_url , указанный в платежном запросе.

Эти уведомления позволяют системе:

• определить связанный платеж
• обновить внутренний статус заказа
• информировать клиента о ходе платежа
• завершить заказ после успешной оплаты

Поскольку callback endpoint доступен публично, система должна проверять входящие уведомления до выполнения каких-либо действий.

OxaPay предоставляет защитную подпись вместе с callback-уведомлениями. Техническая команда должна проверить подпись и убедиться, что платежная информация соответствует сохраненным данным заказа.

Это не обязательно показывать клиенту, но это важная часть защиты платежного процесса.

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

OxaPay может повторить callback, если ваша система не подтвердила его успешное получение.

Обработка недоплаты

Иногда клиент может отправить меньше запрошенной суммы платежа.

OxaPay предоставляет настройку допуска недоплаты, которая позволяет merchant определить приемлемую разницу между ожидаемой и полученной суммой.

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

В зависимости от вашей бизнес-модели можно:

• попросить клиента доплатить оставшуюся сумму
• проверить платеж вручную
• принять платеж согласно внутренней политике
• отменить заказ или вернуть средства, когда это уместно

Недоплату не следует автоматически обрабатывать так же, как неуспешный платеж. Для нее должен быть понятный процесс, чтобы клиенты и служба поддержки знали, что произойдет дальше.

7. Протестируйте полный платежный процесс

Перед запуском интеграции протестируйте полный клиентский путь от создания платежа до завершения заказа.

Тесты должны включать:

• успешное создание платежа
• правильное отображение адреса и QR-кода
• точные данные о сумме платежа и сети
• обновления статуса платежа
• успешное завершение заказа
• истекшие платежи
• сценарии недоплаты
• повторные платежные уведомления
• задержанные обновления платежа

Также проверьте работу платежной страницы на мобильных устройствах. Многие клиенты будут сканировать QR-код другим устройством или копировать адрес прямо в мобильный кошелек.

Тестирования только первоначального API-запроса недостаточно. Весь процесс заказа, включая обновления платежа и fulfillment, должен надежно работать до того, как интеграция станет доступна клиентам.

Важные аспекты интеграции

Надежный White Label платежный опыт зависит от нескольких практических деталей.

Обработка истечения срока

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

Правильный выбор сети

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

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

Понятные платежные инструкции

Клиент должен сразу понимать:

• какую криптовалюту отправить
• какую сеть использовать
• сколько отправить
• куда отправить
• как долго платеж остается действительным
• что произойдет после оплаты

Понятная платежная страница уменьшает путаницу и делает checkout более надежным.

Схема White Label интеграции

Полный процесс можно представить в семи шагах:

1. Система создает внутренний заказ.
2. Backend отправляет White Label платежный запрос в OxaPay.
3. OxaPay возвращает платежные данные.
4. Ваш сайт или приложение отображает платеж в собственном интерфейсе.
5. Клиент отправляет требуемую криптовалюту.
6. OxaPay отслеживает транзакцию и отправляет обновления платежа.
7. Система подтверждает платеж и завершает заказ.

Заключение

Интеграция White Label криптоплатежного шлюза OxaPay позволяет компании контролировать платежный опыт без создания базовой блокчейн-инфраструктуры самостоятельно.

OxaPay управляет созданием платежей, мониторингом транзакций и обновлениями платежей. Ваша компания контролирует брендинг, клиентский интерфейс, управление заказами и финальный fulfillment.

Идея проста: ваша компания владеет клиентским опытом, а OxaPay предоставляет платежную инфраструктуру, стоящую за ним.

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