Полный и частичный возврат

Клиент создаёт команду возврата для подтверждённого платежа. NUMUS определяет исходный платёж и маршрут самостоятельно. Можно вернуть указанную часть суммы либо весь доступный остаток. Результат операции сообщается асинхронно.

Для частичного возврата передайте amount строкой с двумя знаками после точки. Если amount отсутствует, NUMUS вернёт весь доступный остаток. Способ оплаты, банк и внутренний идентификатор маршрута передавать не нужно.

Какой идентификатор использовать

В путь запроса передаётся paymentID подтверждённого платежа. Получите его из data.paymentId события payment.completed либо из истории платежей. Не используйте здесь id платёжного intent из ответа создания QR или карты.

Создать возврат

POST https://api.numus.online/v1/payments/{paymentID}/refunds

POST /v1/payments/0190c5ad-2f51-7b1d-9f2e-e0a01d8f9a22/refunds HTTP/1.1
Host: api.numus.online
Authorization: {подписанный JSON}
Content-Type: application/json
Idempotency-Key: refund-order-42-20260806

{
  "amount": "80.00",
  "reason": "CUSTOMER_REQUEST",
  "description": "Покупатель запросил возврат заказа"
}

Поле	Правило
`amount`	Необязательная сумма этой операции возврата в RUB, например `"80.00"`. Передаётся строкой строго с двумя знаками после точки. Без поля возвращается весь доступный остаток.
`reason`	Одно из значений: `CUSTOMER_REQUEST`, `DUPLICATE`, `FRAUD` или `OTHER`.
`description`	Необязательное пояснение, до 500 символов. Не передавайте чувствительные платёжные данные.
`Idempotency-Key`	Новый ключ длиной 16–128 символов для новой команды; тот же ключ и тело для сетевого повтора.

Ответ 202 Accepted подтверждает сохранение команды:

{
  "refundId": "0190c5d8-249a-7d08-b18d-e0f51ad40124",
  "paymentId": "0190c5ad-2f51-7b1d-9f2e-e0a01d8f9a22",
  "status": "REFUND_PENDING",
  "amount": "80.00",
  "currency": "RUB",
  "reason": "CUSTOMER_REQUEST",
  "description": "Покупатель запросил возврат заказа",
  "createdAt": "2026-08-06T13:40:00Z",
  "updatedAt": "2026-08-06T13:40:00Z"
}

202 ещё не означает, что деньги возвращены. Не показывайте покупателю успешный возврат до состояния REFUND_COMPLETED.

Проверить результат

GET https://api.numus.online/v1/payments/{paymentID}/refunds/{refundID}

Статус	Значение	Действие
`REFUND_PENDING`	Команда сохранена и обрабатывается	Ждать callback или повторить GET
`REFUND_COMPLETED`	Указанная сумма возврата подтверждена	Зафиксировать возврат один раз по `refundId`
`REFUND_FAILED`	Возврат не подтверждён	Сохранить нормализованный `statusReason` и обратиться в NUMUS при необходимости
`REFUND_CANCELLED_MANUAL_REVIEW`	Автоматическая обработка остановлена	Дождаться решения NUMUS; повторную команду не создавать

Уведомления

NUMUS использует тот же callbackUrl, callback-секрет и алгоритм подписи. Возможные события:

refund.pending — команда принята;
refund.completed — указанная сумма возврата подтверждена;
refund.failed — возврат завершился ошибкой;
payment.refunded — подтверждённые возвраты достигли полной суммы платежа, исходный платёж переведён в состояние REFUNDED.

События одного платежа имеют возрастающий aggregateVersion. Каждое значение eventId обрабатывайте не более одного раза.

Конфликты и повторы

для платежа разрешены последовательные частичные возвраты;
сумма подтверждённых и незавершённых возвратов не может превышать исходную сумму платежа;
одновременно для платежа может существовать только один незавершённый возврат;
тот же Idempotency-Key с неизменным телом возвращает исходную команду;
тот же ключ с другим телом возвращает 409;
чужой или несуществующий paymentID возвращает одинаковый 404;
при неизвестном результате не создавайте новую команду — повторите исходную или выполните GET.