Payment Docs
Способы оплаты

Оплата картами (H2H)

Приём данных карты на вашей странице и прохождение 3-D Secure через API

Перед тем как начать

Авторизация

Как подписывать запросы API-токеном.

Создание платежа

Базовый запрос на создание заказа, который расширяет эта страница.

Этот способ оплаты доступен не всем мерчантам. Уточните доступность у вашего менеджера.

Обзор

Есть два способа принимать карты:

ВариантКто собирает данные картыТребования
Платёжная страница (по умолчанию)Наша платёжная страницаНет: создайте обычный заказ
Host-to-host (H2H), эта страницаВаша страницаСоответствие PCI DSS, подключается менеджером

При H2H вы создаёте заказ, отправляете данные карты в API и сами проводите верификацию (3-D Secure, SMS-код). Плательщик не покидает ваш сайт.

Процесс

Создайте заказ

Создайте обычный заказ и сохраните его id.

Создание платежа

Отправьте данные карты

POST /v1/orders/{orderId}/h2h/card
ПолеТипОбязательноеОписание
cardNumberstring✅ ДаНомер карты
expiryDatestring✅ ДаСрок действия, MM/YY
cardholderNamestring✅ ДаИмя держателя карты
cvvstring✅ ДаКод CVV / CVC
curl -X POST "https://api.riopay.online/v1/orders/{orderId}/h2h/card" \
  -H "Content-Type: application/json" \
  -H "X-Api-Token: YOUR_API_TOKEN" \
  -d '{
    "cardNumber": "4111111111111111",
    "expiryDate": "12/25",
    "cardholderName": "John Doe",
    "cvv": "123"
  }'

Если в ответе вернулся объект заказа, данные карты приняты. Далее проверьте, требуется ли SMS-код.

Проверьте статус H2H

GET /v1/orders/{orderId}/h2h/status
curl -X GET "https://api.riopay.online/v1/orders/{orderId}/h2h/status" \
  -H "X-Api-Token: YOUR_API_TOKEN"
{
  "isSmsRequired": true,
  "status": "PROCESSING"
}
ПолеОписание
isSmsRequiredtrue: запросите у плательщика код из SMS его банка
statusТекущий статус H2H, см. Статусы H2H

Опрашивайте этот endpoint, пока статус INITIALIZING или PROCESSING.

Отправьте SMS-код (если требуется)

Вы передаёте в API код, который плательщик получил от своего банка. Этот endpoint не отправляет SMS плательщику.

POST /v1/orders/{orderId}/h2h/code
curl -X POST "https://api.riopay.online/v1/orders/{orderId}/h2h/code" \
  -H "Content-Type: application/json" \
  -H "X-Api-Token: YOUR_API_TOKEN" \
  -d '{ "code": "123456" }'

После успешного ответа продолжайте проверять статус H2H. Если isSmsRequired снова стало true, код был неверным: запросите у плательщика новый.

Дождитесь финального статуса заказа

SUCCESS на уровне H2H означает, что этап проверки карты завершён, а не что средства поступили. Финальный результат приходит как статус заказа через webhook или GET /v1/orders/{orderId}.

Статус заказа и webhook-уведомления

Статусы H2H

Статусы H2H описывают только этап проверки карты и не являются статусами заказа. Всегда подтверждайте финальный результат по статусу заказа.

СтатусФинальныйОписание
INITIALIZINGНетH2H-сессия инициализируется
PROCESSINGНетОбработка: валидация, 3-D Secure, антифрод-проверки
SUCCESSДаЭтап H2H успешно завершён; дождитесь финального статуса заказа через webhook
CANCELLEDДаH2H-платёж отменён
FAILEDДаH2H завершился с ошибкой
EXPIREDДаСрок действия H2H-сессии истёк
  • Опрашивайте статус, пока он INITIALIZING или PROCESSING.
  • На SUCCESS ждите webhook по заказу.
  • На CANCELLED, FAILED или EXPIRED прекращайте опрос и фиксируйте неуспех; для повторной попытки создайте новый заказ.

Данные карты в запросе на создание заказа

Некоторые терминалы принимают данные карты напрямую в POST /v1/orders через объект card вместе с полными данными плательщика. Это также требует соответствия PCI DSS и включается для каждого мерчанта отдельно.

Поля card

ПолеТипОбязательноеОписание
cardholderNamestring✅ ДаИмя держателя карты
cardNumberstring✅ ДаНомер карты
cvvstring✅ ДаКод CVV / CVC
expiryDatestring✅ ДаСрок действия, MM/YY

Поля customer

ПолеТипОбязательноеОписание
emailstring✅ ДаEmail плательщика
phonestring✅ ДаНомер телефона
firstNamestring✅ ДаИмя
lastNamestring✅ ДаФамилия
birthdaystring✅ ДаДата рождения, YYYY-MM-DD
countrystring✅ ДаСтрана, ISO 3166-1 alpha-2
citystring✅ ДаГород
regionstring✅ ДаШтат или регион
postcodestring✅ ДаПочтовый индекс
addressstring✅ ДаАдрес (улица, дом)

Пример запроса

{
  "amount": "10.99",
  "currency": "EUR",
  "successUrl": "https://example.com/success",
  "failUrl": "https://example.com/fail",
  "card": {
    "cardholderName": "Jane Doe",
    "cardNumber": "4444444444444444",
    "cvv": "123",
    "expiryDate": "12/26"
  },
  "customer": {
    "email": "customer@example.com",
    "phone": "1999999999",
    "firstName": "Jane",
    "lastName": "Doe",
    "birthday": "2000-05-05",
    "country": "PT",
    "city": "Maia",
    "region": "Porto",
    "postcode": "4450",
    "address": "Rua Example 1"
  }
}

Некоторым терминалам для оплаты картой на платёжной странице нужен только email плательщика:

{
  "amount": "10.99",
  "currency": "EUR",
  "successUrl": "https://example.com/success",
  "failUrl": "https://example.com/fail",
  "customer": {
    "email": "customer@example.com"
  }
}

Какой из этих форматов запроса применим к вам, зависит от терминала. Уточните у менеджера перед интеграцией.

Следующие шаги

Статус заказа и webhook-уведомления

Получайте уведомления о завершении оплаты.

Платежи по странам

Другие страны и способы оплаты.

Trustly

Банковские переводы из европейских банков через Trustly

Обзор выплат

Отправка средств с баланса мерчанта на карты, номера телефонов, кошельки и PIX-ключи

На этой странице

Перед тем как начатьОбзорПроцессСоздайте заказОтправьте данные картыПроверьте статус H2HОтправьте SMS-код (если требуется)Дождитесь финального статуса заказаСтатусы H2HДанные карты в запросе на создание заказаПоля cardПоля customerПример запросаСледующие шаги