Интеграция API RiskPayGo

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

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

Прежде чем мы начнём

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

Вам понадобятся следующие данные: Идентификатор продавца, ты API-токен, ты Секрет веб-перехватчика и базовый URL-адрес API.

Базовый URL-адрес выглядит следующим образом:

https://riskpaygo.com/portal/api/plugin

Аутентификация

Все API-запросы должны быть аутентифицированы. Для этого необходимо включить закрытый токен в заголовок запроса. Авторизация и идентификатор продавца в заголовке X-RPG-Merchant.

Необходимые заголовки следующие:

Accept: application/json
Content-Type: application/json
Authorization: Bearer TU_API_TOKEN
X-RPG-Merchant: TU_MERCHANT_ID

Эти учетные данные следует использовать только на сервере. Они не должны быть видны в JavaScript-коде браузера или в общедоступном коде.

Утвержденный домен

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

Если домен не соответствует ни одному из ваших утвержденных проектов, API отклонит запрос, даже если токен указан верно.

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

Создать платеж

Для осуществления платежа необходимо отправить запрос. ПОЧТА к конечной точке создания платежа.

POST https://riskpaygo.com/portal/api/plugin/payments/create

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

Типичный запрос будет включать такие поля, как... merchant_order_id, order_id, order_key, количество, валюта, клиент, сайт, notify_url, return_url и cancel_url.

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

{
  "merchant_order_id": "PED-1001",
  "order_id": 1001,
  "order_key": "pedido_1001_key",
  "amount": "149.99",
  "currency": "USD",
  "customer": {
    "email": "cliente@ejemplo.com",
    "first_name": "Nombre",
    "last_name": "Apellido",
    "phone": "+34123456789",
    "country": "ES",
    "date_of_birth": "1990-05-20"
  },
  "site": {
    "url": "https://tu-dominio.com/",
    "name": "Mi tienda",
    "platform": "custom",
    "plugin": "integracion-propia"
  },
  "notify_url": "https://tu-dominio.com/api/riskpaygo/webhook",
  "return_url": "https://tu-dominio.com/pago/completado",
  "cancel_url": "https://tu-dominio.com/pago/cancelado"
}

Поле количество Оно должно быть больше нуля. Валюта отправляется в валюта. В клиент Желательно указать хотя бы электронный адрес покупателя. сайт.url Необходимо предоставить утвержденный домен. notify_url Вы указываете, куда хотите получать уведомления о статусе платежа.

Ответ API

В случае успешного выполнения запроса RiskPayGo возвращает ответ с внутренним платежным идентификатором и URL-адресом оформления заказа. Этот идентификатор позволяет связать платеж с вашим заказом и отслеживать его в дальнейшем.

Ожидаемый ответ имеет следующий вид:

{
  "success": true,
  "data": {
    "payment_ref": "RPG-20260313-ABC12345",
    "checkout_url": "https://riskpaygo.com/portal/checkout.php?ref=RPG-20260313-ABC12345",
    "fee_percent": 20,
    "plan_slug": "free"
  }
}

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

Что делать с кассовым аппаратом?

Оплата обрабатывается через систему оформления заказа, размещенную на платформе RiskPayGo. Ваша система не должна считать заказ оплаченным только потому, что вы получили URL-адрес системы оформления заказа или потому, что пользователь вернулся на веб-сайт.

Рекомендуется сохранить ссылку. payment_refПеренаправьте покупателя и дождитесь окончательного подтверждения через веб-хук.

Он return_url Это позволяет вернуть пользователя на ваш сайт после оплаты, но окончательный статус должен определяться на основании полученного вами уведомления. notify_url.

Веб-перехватчик подтверждения

При изменении статуса платежа RiskPayGo отправит запрос. ПОЧТА по указанному URL-адресу notify_urlВ верхней части уведомления находится подпись. X-RPG-Signature.

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

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

X-RPG-Signature:

Уведомление RiskPayGo может содержать такую ​​информацию, как продавец, номер заказа, номер платежа, статус и идентификатор транзакции. Например:

{
  "merchant_id": "TU_MERCHANT_ID",
  "order_id": 1001,
  "order_key": "pedido_1001_key",
  "payment_ref": "RPG-20260313-ABC12345",
  "transaction_id": "RPG-20260313-ABC12345",
  "status": "paid",
  "provider_status": "success",
  "provider_event": "payment_succeeded",
  "source": "payera_webhook"
}

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

Статусы платежей

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

в ожидании Это означает, что платеж был инициирован, но еще не подтвержден.

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

неуспешный Это означает, что платеж не удался или был отклонен.

отменено Это означает, что платеж был отменен или истек срок его действия.

Общая рекомендация — использовать веб-хук в качестве основного источника достоверной информации и считать заказ оплаченным только после его получения. статус = оплачено.

Распространенные ошибки

Несанкционированный продавец

Если API выдает ошибку авторизации, первое, что следует проверить, это правильность отправленного значения. Авторизация быть правильным и что продавец отправил X-RPG-Merchant сопоставьте этот токен. Вам также необходимо подтвердить, что учетная запись одобрена и активна.

Домен не одобрен

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

Неверная сумма

Если API отклоняет сумму, убедитесь, что количество Оно отправлено корректно и имеет значение больше нуля.

Недействительная подпись веб-перехватчика

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

Использовать с WooCommerce

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

Основные значения, которые необходимо ввести, следующие:

API Base URL: https://riskpaygo.com/portal/api/plugin
Merchant ID: TU_MERCHANT_ID
API Token: TU_API_TOKEN
Webhook Secret: TU_WEBHOOK_SECRET

URL-адрес веб-перехватчика в WordPress обычно имеет следующий формат:

https://tu-dominio.com/wp-json/riskpaygo/v1/webhook

Заключительные рекомендации

Перед запуском в производство рекомендуется убедиться, что домен одобрен и что ваш notify_url Он корректно отвечает по протоколу HTTPS, который вы сохраняете. payment_ref в вашей системе и помечайте заказы как оплаченные только после получения окончательного подтверждения через веб-хук.

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

Прокрутить вверх