Платежи
Чтобы начать работу с Payvo, вам необходимо зарегистрироваться и получить доступ к личному кабинету. Для аутентификации запросов в API вам понадобятся секретный ключ и идентификатор магазина из личного кабинета. Вы можете выполнить этот платеж в тестовом магазине. Процесс оплаты будет таким же, как и при реальных платежах, но деньги не переводятся.
Info
Если вы хотите оценить возможности API, но у вас пока нет личного кабинета в Payvo, зарегистрируйтесь, как тестовый магазин. Указывать данные компании и подписывать договор не нужно.
Чтобы принять оплату, необходимо создать объект платежа — Payment. Он содержит всю необходимую информацию для проведения оплаты (сумму, валюту и статус). У платежа линейный жизненный цикл, он последовательно переходит из статуса в статус.
Создание платежа
POST URL для запроса
https://api.payvo.ru/public/payments
Параметры запроса
Методы платежей
Актуальные платежные методы: https://help.payvo.ru/payments
| Параметр | Тип параметра | Обязательный | По умолчанию | Описание |
|---|---|---|---|---|
amount |
number |
Да | - | Сумма платежа. Иногда партнеры Payvo берут с пользователя дополнительную комиссию, которая не входит в эту сумму. |
description |
string |
Нет | - | Описание транзакции (не более 128 символов), которое вы увидите в личном кабинете Payvo, а пользователь — при оплате. Например: «Оплата заказа № 72 для user@payvo.ru». |
receipt |
object |
Нет | - | Данные для формирования чека. Только если вы пользователь Payvo.Чеки |
payment_method_id |
string |
Нет | - | ID платежного метода. Нужно если хотите провести автоплатеж. |
payment_method_type |
string |
Нет | - | Тип платежного метода |
confirmation |
object |
Нет | - | Данные, необходимые для инициирования выбранного сценария подтверждения платежа пользователем. |
confirmation.type |
string |
Да | - | Возможные значения: qr — отдать содержимое QR-кода (вернется в параметре confirmation.url, доступно только для СБП); redirect — произвести перенаправление пользователя на страницу (вернется в параметре confirmation.url) |
confirmation.return_url |
string |
Нет | - | Обязательно при confirmation.type=redirect. Ссылка на страницу, на которую нужно перенаправить пользователя после оплаты |
save_payment_method |
boolean |
Нет | - | Сохранение платежных данных для проведения автоплатежей. Возможные значения: true — сохранить способ оплаты (сохранить платежные данные); false — провести платеж без сохранения способа оплаты. |
metadata |
object |
Нет | - | Любые дополнительные данные, которые нужны вам для работы (например, ваш внутренний идентификатор заказа). Передаются в виде набора пар «ключ-значение» и возвращаются в ответе от Payvo. Ограничения: максимум 16 ключей, имя ключа не больше 32 символов, значение ключа не больше 512 символов, тип данных — строка в формате UTF-8. |
merchant_customer_id |
string |
Нет | - | Идентификатор покупателя в вашей системе, например электронная почта или номер телефона. Не более 200 символов. |
Пример тела ответа
Возможные значения параметра status: pending, succeeded, canceled
response
{
"errors": null,
"payment": {
"uuid": "bb549c85-1b16-425e-a38e-32bfcdbf52f5",
"status": "pending",
"is_test": 0,
"amount": 1000,
"merchant_customer_id": null,
"description": "Тестовый платеж",
"metadata": {
"test": 1
},
"refunded_amount": null,
"expires_at": "2025-04-10T20:22:18.000+03:00",
"created_at": "2025-04-10T20:12:18.000+03:00",
"income_amount": null,
"cancellation_details": null,
"confirmation": {
"type": "redirect",
"url": "https://my.payvo.ru/payment/bb549c85-1b16-425e-a38e-32bfcdbf52f5",
"return_url": "https://payvo.ru"
},
"payment_method": null,
"receipt": null
}
}
Информация о платеже
Запрос позволяет получить информацию о текущем состоянии платежа по его уникальному идентификатору.
POST URL для запроса
https://api.payvo.ru/public/payments/:uuid
Параметры запроса
Без параметров.
Пример тела ответа
response
{
"errors": null,
"payment": {
"uuid": "ef324b72-4b47-4222-95ca-8a18eef7863d",
"status": "succeeded",
"is_test": 0,
"amount": 25000,
"merchant_customer_id": null,
"description": "Подписка на 1 месяц",
"metadata": {
"id": "test"
},
"refunded_amount": null,
"expires_at": "2025-04-11T23:14:13.000+03:00",
"created_at": "2025-04-11T23:03:50.000+03:00",
"income_amount": 24350,
"cancellation_details": null,
"confirmation": {
"type": "redirect",
"url": "https://my.payvo.ru/payment/ef324b72-4b47-4222-95ca-8a18eef7863d",
"return_url": "https://payvo.ru"
},
"payment_method": {
"type": "sbp",
"saved": false,
"sbp_operation_id": "B12345678901234567890"
},
"receipt": {
"customer": {
"email": "user@payvo.ru",
"phone": null
},
"items": [
{
"description": "Подписка на 1 месяц",
"amount": 25000,
"vat_code": 1,
"quantity": 1,
"payment_subject": "service",
"payment_mode": "full_payment"
}
],
"url": "https://checks.payvo.ru/test",
"registration_status": "succeeded"
}
}
}
Коды ошибок
В процессе платежа что-то может пойти не так. Например, пользователю может не хватить денег для оплаты, эмитент может быть недоступен, Payvo может заподозрить попытку мошенничества. В этом случае платеж будет отменен и перейдет в статус canceled.
Чтобы вы могли лучше понимать, что произошло и что с этим делать, Payvo пришлет в объекте платежа комментарий к отмене платежа (cancellation_details). В нём будут указаны инициатор (cancellation_details.party) и причина отмены (cancellation_details.reason). Вы можете использовать эти данные для анализа и решения проблем, вывода сообщений пользователю и любых других целей.
Инициаторы отмены платежа
| Значение | Описание |
|---|---|
payvo |
Payvo |
payment_network |
Любые участники процесса платежа, кроме Payvo и вас (например, эмитент, сторонний платежный сервис) |
Причины отмены платежа
| Значение | Описание |
|---|---|
general_decline |
Причина не детализирована. Пользователю следует обратиться к инициатору отмены платежа за уточнением подробностей |
expired |
Истек срок оплаты: пользователь не подтвердил платеж за время, отведенное на оплату выбранным способом. Если пользователь еще хочет оплатить, вам необходимо повторить платеж, а пользователю — подтвердить его |
3d_secure_failed |
Не пройдена аутентификация по 3-D Secure. При новой попытке оплаты пользователю следует пройти аутентификацию, использовать другое платежное средство или обратиться в банк за уточнениями |
call_issuer |
Оплата данным платежным средством отклонена по неизвестным причинам. Пользователю следует обратиться в организацию, выпустившую платежное средство |
country_forbidden |
Нельзя заплатить банковской картой, выпущенной в этой стране. При новой попытке оплаты пользователю следует использовать другое платежное средство. |
fraud_suspected |
Платеж заблокирован из-за подозрения в мошенничестве. При новой попытке оплаты пользователю следует использовать другое платежное средство |
insufficient_funds |
Не хватает денег для оплаты. Пользователю следует пополнить баланс или использовать другое платежное средство |
invalid_card_number |
Неправильно указан номер карты. При новой попытке оплаты пользователю следует ввести корректные данные |
invalid_cvv |
Неправильно указан код CVV2 (CVC2, CID). При новой попытке оплаты пользователю следует ввести корректные данные |
issuer_unavailable |
Организация, выпустившая платежное средство, недоступна. При новой попытке оплаты пользователю следует использовать другое платежное средство или повторить оплату позже |
payment_method_limit_exceeded |
Исчерпан лимит платежей для данного платежного средства или вашего магазина. При новой попытке оплаты пользователю следует использовать другое платежное средство или повторить оплату на следующий день |
payment_method_restricted |
Запрещены операции данным платежным средством (например, карта заблокирована из-за утери, кошелек — из-за взлома мошенниками). Пользователю следует обратиться в организацию, выпустившую платежное средство |
permission_revoked |
Нельзя провести безакцептное списание: пользователь отозвал разрешение на автоплатежи. Если пользователь еще хочет оплатить, вам необходимо создать новый платеж, а пользователю — подтвердить оплату |
Пример объекта платежа в статусе canceled
response
{
"errors": null,
"payment": {
"uuid": "5e043fdc9-29b7-4f20-acef-1771d823ccab",
"status": "canceled",
"is_test": 0,
"amount": 1000,
"merchant_customer_id": null,
"description": "Тестовый платеж",
"metadata": {
"test": 1
},
"refunded_amount": null,
"expires_at": "2025-04-11T08:48:28.000+03:00",
"created_at": "2025-04-11T08:37:48.000+03:00",
"income_amount": 978,
"cancellation_details": {
"party": "payvo",
"reason": "expired"
},
"confirmation": {
"type": "redirect",
"url": "https://my.payvo.ru/payment/5e043fdc9-29b7-4f20-acef-1771d823ccab",
"return_url": "https://payvo.ru"
},
"payment_method": {
"type": "sbp"
},
"receipt": null
}
}