Возвраты

С помощью 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": "bb9a9c85-1b16-425e-a38e-32bfcdbf52f5",
        "payment_uuid": "bb9a9c85-1b16-425e-a38e-32bfcdbf52f5",
        "status": "pending",
        "amount": 1000,
        "description": "Тестовый платеж",
        "created_at": "2025-04-10T20:12:18.000+03:00",
        "cancellation_details": null,
    }
}

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

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

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

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

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

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

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

response

{
  "id": "216749f7-0016-50be-b000-078d43a63ae4",
  "status": "succeeded",
  "amount": {
    "value": "1.00",
    "currency": "RUB"
  },
  "created_at": "2017-10-04T19:27:51.407Z",
  "payment_id": "216749da-000f-50be-b000-096747fad91e"
}

Коды ошибок

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

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

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

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

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

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

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

response

  {
    "id": "216749f7-0016-50be-b000-078d43a63ae4",
    "status": "canceled",
    "amount": {
      "value": "2.00",
      "currency": "RUB"
    },
    "created_at": "2017-10-04T19:27:51.407Z",
    "payment_id": "21740069-000f-50be-b000-0486ffbf45b0",
    "cancellation_details": {
        "party": "yoo_money",
        "reason": "insufficient_funds"
    }
  }