Возвраты

С помощью API можно возвращать платежи — полностью или частично. Порядок возврата зависит от способа оплаты (payment_method) исходного платежа. При оплате банковской картой деньги возвращаются на карту, которая была использована для проведения платежа.

Объект возврата (Refund) содержит актуальную информацию о возврате успешного платежа. Он приходит в ответ на любой запрос, связанный с возвратами. Объект может содержать параметры и значения, не описанные в этом Справочнике API. Их следует игнорировать.

Создание возврата

POST URL для запроса

https://api.payvo.ru/public/refunds

Параметры запроса

Параметр	Тип параметра	Обязательный	По умолчанию	Описание
payment_uuid	string	Да	-	Идентификатор платежа в Payvo.
amount	number	Нет	-	Сумма, которую нужно вернуть пользователю.
description	string	Нет	-	Комментарий к возврату, основание для возврата денег пользователю.

Пример тела ответа

response

{
    "errors": null,
    "refund": {
        "uuid": "3ce5717b-7dd0-4476-af90-4bbef30d7f5b",
        "payment_uuid": "2992af3a-98a2-477b-8041-5ee506fcbabc",
        "status": "succeeded",
        "amount": 1100,
        "description": null,
        "created_at": "2025-04-27T15:17:54.000+03:00",
        "receipt": null
    }
}

Информация о возврате

Запрос позволяет получить информацию о текущем состоянии возврата по его уникальному идентификатору.

POST URL для запроса

https://api.payvo.ru/public/refunds/:uuid

Параметры запроса

Без параметров.

Пример тела ответа

response

{
    "errors": null,
    "refund": {
        "uuid": "3ce5717b-7dd0-4476-af90-4bbef30d7f5b",
        "payment_uuid": "2992af3a-98a2-477b-8041-5ee506fcbabc",
        "status": "succeeded",
        "amount": 1100,
        "description": null,
        "created_at": "2025-04-27T15:17:54.000+03:00",
        "receipt": null
    }
}

Коды ошибок

В процессе возврата что-то может пойти не так. Например, может не хватать денег для возврата. В этом случае возврат будет отменен и перейдет в статус canceled.

Чтобы вы могли лучше понимать, что произошло и что с этим делать, Payvo пришлет в объекте возврата комментарий к отмене возврата (cancellation_details). В нём будут указаны инициатор и причина отмены возврата. Вы можете использовать эти данные для анализа и решения проблем, вывода сообщений пользователю и любых других целей.

Инициаторы отмены платежа

Значение	Описание
payvo	Payvo
refund_network	Любые участники процесса возврата, кроме Payvo и вас (например, эмитент банковской карты)

Причины отмены возврата

Значение	Описание
general_decline	Причина не детализирована. Для уточнения подробностей обратитесь в техническую поддержку.
insufficient_funds	Не хватает денег, чтобы сделать возврат: сумма платежей, которые вы получили в день возврата, меньше, чем сам возврат, или есть задолженность.
rejected_by_payee	Эмитент платежного средства или другой участник процесса возврата отклонил операцию по неизвестным причинам. Сделать возврат через Payvo нельзя.
rejected_by_timeout	Технические неполадки на стороне инициатора отмены возврата. Повторите запрос с новым ключом идемпотентности. Если результат не изменится, повторяйте запрос с возрастающим разумным интервалом (например, можно использовать последовательность Фибоначчи).

Пример объекта возврата в статусе cancelled

response

{
    "errors": null,
    "refund": {
        "uuid": "3ce5717b-7dd0-4476-af90-4bbef30d7f5b",
        "payment_uuid": "2992af3a-98a2-477b-8041-5ee506fcbabc",
        "status": "canceled",
        "amount": 1100,
        "description": null,
        "created_at": "2025-04-27T15:17:54.000+03:00",
        "receipt": null,
        "cancellation_details": {
            "party": "payvo",
            "reason": "rejected_by_timeout"
        }
    }
}