Перейти к содержанию

Система Быстрых Платежей (SBP)

Вариант интеграции PX

Система Быстрых Платежей по платежным данным (SBP Data)

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

  1. Покупатель нажимает Оплатить на сайте торговца.
  2. Торговец отображает покупателю страницу с суммой транзакции, реквизитами банка и номером телефона, на который нужно осуществить платеж.
  3. Покупатель копирует номер телефона и другие данные и осуществляет оплату удобным для себя способом в течение 15 минут.
  4. Для ускорения платежа, торговец может реализовать у себя на сайте кнопку подтверждения оплаты, при нажатии на которую после оплаты будет отправлен запрос подтверждение транзакции. Этот шаг не обязателен.
  5. Торговец получает автоматическое уведомление о результатe транзакции.
  6. В случае успешной транзакции (статус successful), сумма транзакции начисляется в личном кабинете покупателя.
  7. Если покупатель осуществляет оплату по истечении отведенного 15-минутного интервала, возвращается статус failed.
  8. Если покупатель совершил оплату, но в личном кабинете на сайте торговца баланс не изменился, покупатель может связаться с торговцем с просьбой о начислении средств в личном кабинете, приложив документы об оплате.
  9. Торговец отправляет в Riverbanq запрос на доказательство оплаты, приложив файл с документами об оплате. При этом каждый документ размещается на отдельной странице файла. Запросы доказательства оплаты с "payment_status": "pending" или "payment_status": "successful" будут отклонены.
  10. Далее возможны следующие сценарии:
Статусы в ответе на запрос статуса Описание
"payment_status": "successful"

"proof_status": "successful"		 Доказательство оплаты подтверждено. Торговцу будет выслано автоматическое уведомление с обновленным статусом и суммой оплаты.
"payment_status": "failed"

"proof_status": "failed"		 Доказательство оплаты отклонено. Торговцу будет выслано автоматическое уведомление со статусом failed для двух объектов.
"payment_status": "pending" или "payment_status": "failed"

"proof_status": "successful"		 Доказательство оплаты на рассмотрении. Торговцу следует дождаться статуса successful по транзакции оплаты (в ответе на запрос статуса или в автоматическом уведомлении) прежде чем финализировать транзакцию.

Note

Торговец не должен отправлять повторный запрос на доказательство оплаты, если он еще не получил повторное автоматическое уведомление по платежу после предыдущего запроса. Как правило, запрос на доказательство оплаты рассматривается от 1 часа до 2 рабочих дней. Максимальное количество таких запросов по одной транзакции: 3.

Оплата

Запрос

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

Параметр Тип данных Описание
request object
return_url * обязательный
 string URL, на который будет возвращен покупатель после завершения операции в платёжной системе.
method object Секция параметров способа оплаты.
type
* обязательный

 string sbp_data
channel
* обязательный

 string Укажите SBP. Обратите внимание, что значение этого параметра должно быть указано прописными буквами.

Note

Сумма в поле amount должна быть округленной целой суммой, указанной в минимальных денежных единицах. Например, 50000 (500 рублей).

Note

Допустимый диапазон значений поля amount 50000—15000000 (500—150000 RUB).

Пример запроса 
 {
  "request":{
      "amount":100000,
      "currency":"RUB",
      "description":"description",
      "test": true,    
      "tracking_id":"11111111",      
      "language":"en",
      "notification_url":"https://merchant.ltd/notification",
      "return_url":"https://merchant.ltd/return",      
      "method":{
        "type": "sbp_data",
        "channel": "SBP"

      }
  }
}
Ответ

Ответ будет содержать следующие дополнительные поля:

Параметр Тип данных Описание
sbp_data object
mark
* обязательный

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

 string Номер телефона, на который следует осуществить платеж.
bank_type * обязательный
 string Банк-эмитент карты получателя.
expired_at
* обязательный

 string Время в формате ISO-8601, до которого следует осуществить платеж. Формат: YYYY-MM-DDThh:mm:ssTZD, где YYYY – год (например, 2019), MM – месяц (например, 02), DD – день (например, 09), hh – часы (например, 18), mm – минуты (например, 20), ss – секунды (например, 45), TZD – часовой пояс (+hh:mm или –hh:mm относительно UTC).
Пример ответа 
{
  "transaction": {
    "uid": "0f654679-0485-4061-8638-d8690e6505e5",
    "type": "payment",
    "status": "pending",
    "amount": 100000,
    "currency": "RUB",
    "description": "description",
    "created_at": "2024-05-22T13:40:45Z",
    "updated_at": "2024-05-22T13:40:45Z",
    "method_type": "sbp_data",
    "receipt_url": "https://my.riverbanq.com/customer/transactions/0f654679-0485-4061-8638-d8690e6505e5/2c4d0ab640d08934dc1d9aca64aa652fc41c4bfb51830c2319bacc5e5b8260a9?language=en",
    "payment": {
      "status": "pending",
      "gateway_id": 3898,
      "ref_id": "40abf7cd-aa9f-43c5-a523-f4c10aed7e83",
      "message": "Transaction was initialized."
    },
    "sbp_data": {
      "type": "sbp_data",
      "mark": "",
      "target_card": "+1111",
      "expired_at": "2024-05-22 13:55:46+0000",
      "bank_type": "TINKOFF"
    },
    "customer": {
      "email": null,
      "ip": null
    },
    "manually_corrected_at": null,
    "message": "Transaction was initialized.",
    "tracking_id": "11111111",
    "test": true,
    "language": "en",
    "additional_data": {
      "payment_method": {
        "type": "alternative"
      }
    },
    "gateway": {
      "iframe": false
    }
  }
}

Доказательство оплаты

Запрос

POST https://apm.riverbanq.com/beyag/transactions/{uid}/proof

Параметр Тип данных Описание
request object
skip_duplicate_check boolean Если false, отклоняет запрос, если в течение 30 секунд до этого был прислан запрос с таким же uid. По умолчанию, false.
amount * обязательный
 bigInteger Сумма доказательства оплаты, указанная в минимальных денежных единицах без копеек.
currency * обязательный
 string (3) Валюта транзакции в формате ISO-4217 alpha-3 code.
document object
content_type * обязательный
 string application/pdf
file_name * обязательный
 string Имя файла доказательства оплаты, включая расширение.
file_size * обязательный
 integer Размер файла в байтах.
content * обязательный
 string Файл c доказательствами оплаты в кодировке base64. Все документы, подтверждающие оплату, должны быть присланы в одном файле, при этом каждый подтверждающий документ должен быть размещен на отдельной странице в этом файле.
checksum * обязательный
 string Контрольная сумма файла в SHA256.
Пример запроса 
{
  "request": {
    "skip_duplicate_check": false,
    "amount": 322400,
    "currency": "RUB",
    "document": {
      "content_type": "application/pdf",
      "file_name": "3224.pdf",
      "file_size": 198149,
      "content": "cmVmCjE5Yzd2NwolJUVPRgo=",
      "checksum": "45EA3C910A727823079CF1E7DAB4B8BA"
    }
  }
}
Ответы на запрос статуса

После отправки запроса на доказательство транзакции, ответ на запрос получения статуса транзакции будет содержать объект proof с одним из трех статусов: pending, failed или successful.

После обработки запроса доказательства оплаты, торговец получит автоматическое уведомление или со статусом failed в объектах payment и proof или со статусом successful в обоих объектах.

Пример ответа на запрос статуса со статусом pending по доказательству оплаты 
{
    "transaction": {
        "uid": "d17a3b46-1a49-4d0d-b814-b20f414d82ab",
        "type": "payment",
        "status": "failed",
        "amount": 100000,
        "currency": "RUB",
        "description": "tesdhgfljkdfhg;dfh",
        "created_at": "2023-08-16T05:59:40Z",
        "updated_at": "2023-08-16T07:35:09Z",
        "method_type": "card_transfer",
        "receipt_url": "https://my.riverbanq.com/customer/transactions/d17a3b46-1a49-4d0d-b814-b20f414d82ab/12f6a5a5677022c46745076308bf5c97557c6c75557666e8f690ce084936bd34?language=ru",
        "payment": {
            "status": "failed",
            "gateway_id": 2976,
            "ref_id": "c909f8ad-5b3e-4903-b08f-e209ced37950",
            "message": "Transaction was declined."
        },
        "sbp_data": {
            "mark": "160385A",
            "type": "sbp_data",
            "expired_at": "2023-08-16T06:14:41Z",
            "bank_type": "SBP",
            "target_card": "9999999999999999"
        },
        "customer": {
            "email": "[email protected]",
            "phone": "56356464674",
            "country": "BY",
            "device_id": "f02ee44965442d87de97cf54bffb906f",
            "ip": null
        },
        "message": "Transaction was declined.",
        "tracking_id": "3e32451b-cb3a-4094-b40c-3e83883e2f4c",
        "test": false,
        "language": "ru",
        "paid_at": "2023-08-16T06:01:08Z",
      ...
        "proof": {
            "ref_id": "97be822d-6c34-4ead-9579-21a8f42a92e1",
            "gateway_id": 2976,
            "status": "pending",
            "message": "Proof was initialized."
        }
    }
}
Пример ответа на запрос статуса со статусом successful по доказательству оплаты 
{
    "transaction": {
        "uid": "d17a3b46-1a49-4d0d-b814-b20f414d82ab",
        "type": "payment",
        "status": "successful",
        "amount": 100000,
        "currency": "RUB",
        "description": "tesdhgfljkdfhg;dfh",
        "created_at": "2023-08-16T05:59:40Z",
        "updated_at": "2023-08-16T07:35:09Z",
        "method_type": "card_transfer",
        "receipt_url": "https://my.riverbanq.com/customer/transactions/d17a3b46-1a49-4d0d-b814-b20f414d82ab/12f6a5a5677022c46745076308bf5c97557c6c75557666e8f690ce084936bd34?language=ru",
        "payment": {
            "status": "failed",
            "gateway_id": 2976,
            "ref_id": "c909f8ad-5b3e-4903-b08f-e209ced37950",
            "message": "Transaction was successfully processed."
        },
        "sbp_data": {
            "mark": "160385A",
            "type": "sbp_data",
            "expired_at": "2023-08-16T06:14:41Z",
            "bank_type": "SBP",
            "target_card": "9999999999999999"
        },
        "customer": {
            "email": "[email protected]",
            "phone": "56356464674",
            "country": "BY",
            "device_id": "f02ee44965442d87de97cf54bffb906f",
            "ip": null
        },
        "message": "Transaction was successfully processed.",
        "tracking_id": "3e32451b-cb3a-4094-b40c-3e83883e2f4c",
        "test": false,
        "language": "ru",
        "paid_at": "2023-08-16T06:01:08Z",
      ...
        "proof": {
          "ref_id": "f8casdf56-1e85-r456-9842-fasdfasdf",
          "gateways_id": 2985,
          "status": "successful",
          "message": "Proof was successfully processed."
        }
    }
}
Пример ответа на запрос статуса со статусом failed по доказательству оплаты 
{
    "transaction": {
        "uid": "d17a3b46-1a49-4d0d-b814-b20f414d82ab",
        "type": "payment",
        "status": "failed",
        "amount": 100000,
        "currency": "RUB",
        "description": "tesdhgfljkdfhg;dfh",
        "created_at": "2023-08-16T05:59:40Z",
        "updated_at": "2023-08-16T07:35:09Z",
        "method_type": "card_transfer",
        "receipt_url": "https://my.riverbanq.com/customer/transactions/d17a3b46-1a49-4d0d-b814-b20f414d82ab/12f6a5a5677022c46745076308bf5c97557c6c75557666e8f690ce084936bd34?language=ru",
        "payment": {
            "status": "failed",
            "gateway_id": 2976,
            "ref_id": "c909f8ad-5b3e-4903-b08f-e209ced37950",
            "message": "Transaction was declined."
        },
        "sbp_data": {
            "mark": "160385A",
            "type": "sbp_data",
            "expired_at": "2023-08-16T06:14:41Z",
            "bank_type": "SBP",
            "target_card": "9999999999999999"
        },
        "customer": {
            "email": "[email protected]",
            "phone": "56356464674",
            "country": "BY",
            "device_id": "f02ee44965442d87de97cf54bffb906f",
            "ip": null
        },
        "message": "Transaction was declined.",
        "tracking_id": "3e32451b-cb3a-4094-b40c-3e83883e2f4c",
        "test": false,
        "language": "ru",
        "paid_at": "2023-08-16T06:01:08Z",
      ...
        "proof": {
            "ref_id": "f8casdf56-1e85-r456-9842-fasdfasdf",
            "gateways_id": 2985,
            "status": "failed",
            "message": "Proof was declined."
        }
    }
}

Подтверждение транзакции

Запрос

POST https://apm.riverbanq.com/beyag/transactions/{uid}/confirm

Параметр Тип данных Описание
skip_duplicate_check boolean Если false, отклоняет запрос, если в течение 30 секунд до этого был прислан запрос с таким же uid. По умолчанию, false.
Ответ
Пример успешного ответа 
{
    "response": {
        "parent_uid": "2-310b0da80b", 
        "type": "confirm",
        "status": "successful", 
        "message": "Confirm was successfully processed",
        "created_at": "2023-05-11T12:04:59+03:00",
        "amount": 332400,
        "currency":"RUB"
    }
}
Пример ответа со статусом failed 
{
    "response": {
        "parent_uid": "2-310b0da80b",
        "type": "confirm",
        "status": "failed",
        "message": "Confirm was failed",
        "created_at": "2023-05-11T12:04:59+03:00",
        "amount": 50,
        "currency": "RUB"
    }
}
Пример ответа, если транзакция не найдена 
{
        "response": {
            "message": "Record not found",                
        }
}