Создание платежа
Создайте заказ и перенаправьте плательщика на платёжную страницу
Платёж начинается с заказа. Вы создаёте его одним запросом, получаете paymentLink и перенаправляете на него плательщика. Остальное берёт на себя платёжная страница.
Запросы подписываются заголовком X-Api-Token, см. Авторизация.
Эндпоинт
POST /v1/ordersПараметры запроса
| Поле | Тип | Обязательное | Описание |
|---|---|---|---|
amount | string (decimal) | ✅ Да | Сумма заказа |
currency | string | Зависит от терминала | Валюта заказа (ISO 4217). Обязательна для мультивалютных терминалов |
serviceId | integer | ✅ Да, для новых аккаунтов | Сервис, через который провести платёж |
externalId | string / null | ❌ Нет | ID заказа в вашей системе. Возвращается в webhook-уведомлениях; используйте его для сопоставления записей |
externalUserId | string / null | ❌ Нет (обязательно для некоторых методов) | ID пользователя в вашей системе |
isFeeOnUser | boolean | ❌ Нет | Переложить комиссию на плательщика |
purpose | string / null | ❌ Нет | Назначение платежа, которое видит плательщик |
successUrl | string / null | ❌ Нет (если указан в настройках) | URL для редиректа после успешной оплаты |
failUrl | string / null | ❌ Нет | URL для редиректа после неуспешной оплаты |
callbackUrl | string / null | ❌ Нет | URL для webhook-уведомлений по этому заказу. Если не указан, используется адрес из настроек мерчанта |
Объекты для отдельных способов оплаты
Для некоторых стран и способов оплаты требуются дополнительные данные о плательщике или способе оплаты. Они передаются в том же запросе в виде дополнительных полей:
| Поле | Тип | Назначение |
|---|---|---|
customer | object | Данные плательщика: имя, email, телефон, страна, документ. Обязателен для большинства локальных методов |
extraParams | string | Выбирает конкретный способ оплаты на терминале, например Apple Pay или Trustly |
card | object | Данные карты для прямых карточных платежей |
Точный набор обязательных полей зависит от страны и метода. Найдите свой случай в разделах Платежи по странам или Способы оплаты.
Пример запроса
curl -X POST "https://api.riopay.online/v1/orders" \
-H "Content-Type: application/json" \
-H "X-Api-Token: YOUR_API_TOKEN" \
-d '{
"amount": "1000.50",
"serviceId": 3,
"externalId": "order_1234",
"externalUserId": "user_987",
"isFeeOnUser": true,
"purpose": "Payment for order #1234",
"successUrl": "https://example.com/success",
"failUrl": "https://example.com/fail",
"callbackUrl": "https://example.com/webhooks/payments"
}'Ответ
Успешный запрос возвращает объект заказа. Тот же объект возвращается эндпоинтом статуса и отправляется в webhook-уведомлениях.
{
"id": "a1b2c3d4-e5f6-7g8h-i9j0-k1l2m3n4o5p6",
"status": "CREATED",
"statusMessage": "Ok",
"purpose": "Payment for order #1234",
"amount": "1000.5",
"commission": "1.5",
"received": "999.0",
"currency": "EUR",
"paymentType": null,
"shopId": "a1b2c3d4-e5f6-7g8h-i9j0-k1l2m3n4o5p6",
"terminalId": "a1b2c3d4-e5f6-7g8h-i9j0-k1l2m3n4o5p6",
"merchantId": "a1b2c3d4-e5f6-7g8h-i9j0-k1l2m3n4o5p6",
"externalId": "order_1234",
"externalUserId": "user_987",
"paymentLink": "https://example.com/payment?id=a1b2c3d4-e5f6-7g8h-i9j0-k1l2m3n4o5p6",
"successUrl": "https://example.com/success",
"failUrl": "https://example.com/fail",
"callbackUrl": "https://example.com/webhook",
"metadata": null,
"fingerprint": null,
"ipAddress": null,
"gatewayTransactionId": null,
"payedAt": null,
"updatedAt": "2023-03-21T12:34:56Z",
"createdAt": "2023-03-21T12:34:56Z"
}Поля объекта заказа
| Поле | Тип | Описание |
|---|---|---|
id | string (UUID) | ID заказа в нашей системе. Используйте его для проверки статуса |
status | string | Текущий статус заказа, см. Статусы заказа |
statusMessage | string / null | Текстовое описание статуса |
purpose | string / null | Назначение платежа |
amount | string | Сумма заказа |
commission | string / null | Комиссия, удержанная за заказ |
received | string / null | Сумма, зачисленная на ваш баланс |
currency | string | Валюта заказа (ISO 4217) |
paymentType | string / null | Способ оплаты, которым воспользовался плательщик |
shopId | string (UUID) | ID магазина |
terminalId | string (UUID) | Терминал, через который обрабатывается заказ |
merchantId | string (UUID) | ID вашего мерчанта |
externalId | string / null | ID заказа в вашей системе (переданное вами значение) |
externalUserId | string / null | ID пользователя в вашей системе (переданное вами значение) |
paymentLink | string | Ссылка на платёжную страницу. Перенаправьте на неё плательщика |
successUrl | string / null | URL для редиректа после успешной оплаты |
failUrl | string / null | URL для редиректа после неуспешной оплаты |
callbackUrl | string / null | URL для webhook-уведомлений по этому заказу (null — используются настройки мерчанта) |
metadata | object / null | Дополнительные данные |
fingerprint | string / null | Отпечаток устройства плательщика |
ipAddress | string / null | IP-адрес плательщика |
gatewayTransactionId | string / null | ID транзакции на стороне провайдера |
payedAt | string / null | Время оплаты (ISO 8601) |
createdAt | string | Время создания (ISO 8601) |
updatedAt | string | Время последнего обновления (ISO 8601) |
Статусы заказа
| Статус | Финальный | Описание |
|---|---|---|
CREATED | Нет | Заказ создан, платёжная ссылка ещё не открыта |
PENDING | Нет | Ожидает оплаты |
COMPLETED | Да | Платёж успешно завершён, средства получены |
FAILED | Условно | Ошибка оплаты |
CANCELED | Условно | Заказ отменён системой |
EXPIRED | Условно | Срок действия заказа истёк до оплаты |
BLOCKED | Условно | Транзакция заблокирована банком |
REFUND | Да | Платёж возвращён плательщику. Устанавливается после COMPLETED |
CHARGEBACK | Да | Платёж оспорен плательщиком и отменён банком. Устанавливается после COMPLETED |
FAILED, CANCELED, EXPIRED и BLOCKED не являются строго финальными. Если банк позже подтверждает платёж из-за ошибки на своей стороне, заказ переходит в COMPLETED, и webhook-уведомление об этом отправляется автоматически. Будьте готовы получить COMPLETED по заказу, который вы уже отметили как неуспешный.
Некоторые поля могут быть null в зависимости от стадии обработки. Актуальные схемы запросов и ответов всегда доступны в Swagger-документации (ссылка в верхнем меню).
Перенаправление плательщика
Перенаправьте плательщика на paymentLink из ответа. После оплаты плательщик будет перенаправлен на successUrl или failUrl.
Не считайте редирект на successUrl подтверждением оплаты. Только статус COMPLETED, полученный через webhook-уведомление или эндпоинт статуса, подтверждает, что средства поступили.