Интеграция 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-адрес вашего магазина или приложения.

Как работает выбор товаров при оформлении заказа

В зависимости от страны покупателя, RiskPayGo использует два разных процесса оформления заказа:

  • Если страна отправила клиент.страна является НАС тот ЧТОПокупатель будет перенаправлен на страницу оформления заказа для США/Канады.
  • Если страна указана как любая другая, покупатель будет перенаправлен на международную страницу оформления заказа.

Для ручного выбора пункта оформления заказа не требуется заполнять дополнительное поле. Выбор осуществляется автоматически на основе значения параметра. клиент.страна.

Поэтому важно, чтобы страна покупателя была корректно указана в каждом заказе.

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

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

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",
    "country": "US"
  },
  "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 Вы указываете URL-адрес, на который хотите получать подтверждение статуса платежа.

Примеры поведения по странам

Если вы отправляете письмо из страны, не входящей в США/Канаду:

{
  "customer": {
    "email": "cliente@ejemplo.com",
    "first_name": "John",
    "last_name": "Smith",
    "country": "US"
  }
}

Покупатель будет перенаправлен на страницу оформления заказа для США/Канады.

Если вы отправляете из другой страны:

{
  "customer": {
    "email": "cliente@ejemplo.com",
    "first_name": "Carlos",
    "last_name": "García",
    "country": "ES"
  }
}

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

Ответ 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Вы должны перенаправить покупателя на указанный адрес, чтобы он мог завершить оплату.

Даже если выбор способа оформления заказа основан на стране покупателя, процесс интеграции остается тем же: всегда следует использовать... checkout_url возвращается API.

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

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

Рекомендуемый подход заключается в следующем:

  1. Создайте платеж в административной панели.
  2. Сохраните ссылку payment_ref в вашей системе.
  3. Перенаправить покупателя на checkout_url.
  4. Дождитесь окончательного подтверждения через веб-перехватчик.

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

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

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

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

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

X-RPG-Signature: <firma_base64_hmac_sha256>

Уведомление 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 отклоняет сумму, убедитесь, что количество Оно отправлено корректно и имеет значение больше нуля.

Неполная информация о покупателе

Если запрос не удается из-за данных клиента, проверьте это в клиент Вы должны отправить как минимум следующие поля:

first_name
last_name
email
country

Помните об этом телефон и Дата рождения В данной интеграции они больше не нужны.

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

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

Использование 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

Если в процессе оплаты плагин использует страну покупателя, то выбор между оформлением заказа в США/Канаде и международным оформлением заказа будет осуществляться по той же логике, что описана выше.

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

Перед запуском в производство рекомендуется проверить все следующие параметры:

  • Что домен был отправлен сайт.url Он одобрен в RiskPayGo.
  • Что ты notify_url При использовании протокола HTTPS ответ отправляется корректно.
  • Какие охранники payment_ref в вашей системе, чтобы иметь возможность связать платеж с заказом.
  • Чтобы вы отправили правильно клиент.странапотому что именно это значение определяет, какую страницу оформления заказа увидит покупатель.
  • Заказы помечаются как оплаченные только после получения окончательного подтверждения через веб-хук. статус = оплачено.

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

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