Возвраты

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

Возврат отправляет плательщику деньги успешного платежа, целиком или частью. Его создаёт сервер мерчанта. Возврат идёт тем же путём, что платёж, и в валюте платежа.

Порядок

  1. Создайте возврат с ключом повтора и суммой:

    curl -sS -X POST https://api.paydex.co.uk/api/v1/payments/pr_8k3m2q7w9x4t6v5n2b8c4d/refunds \
      -H "Authorization: Bearer $PAYDEX_API_KEY" \
      -H "Content-Type: application/json" \
      -H "Idempotency-Key: 0b8e4f3a-6c21-4d7e-9a15-2f4c8b7d1e90" \
      -d '{
        "reference": "refund-1001-1",
        "amountMinor": "500",
        "description": "Partial refund, ticket T-5521",
        "metadata": {
          "ticket": "T-5521"
        }
      }'

    Ответ 201 несёт возврат в том состоянии, в каком он есть после обращения к провайдеру. Поля: справочник.

  2. Дождитесь исхода: уведомление refund.updated (Уведомления) или чтение возврата. Возврат в PENDING дочитывайте и сами, даже если ждёте уведомлений: недоставленное уведомление не досылается.

    curl -sS https://api.paydex.co.uk/api/v1/payments/pr_8k3m2q7w9x4t6v5n2b8c4d/refunds/rf_5n7q2w8x4k3m9t6v2b8c4d \
      -H "Authorization: Bearer $PAYDEX_API_KEY"
  3. Все возвраты платежа отдаёт GET /api/v1/payments/:id/refunds, от новых к старым.

Суммы «вернуть всё» по умолчанию нет: сумму называют всегда. Платёж после возврата остаётся SUCCEEDED, вернувшееся видно в его поле refundedMinor.

Что можно вернуть

Только платёж в статусе SUCCEEDED, созданный через API и не в разборе. Остаток к возврату это paidMinor минус все возвраты платежа, кроме неуспешных. У платежа не больше 50 возвратов, кроме неуспешных, и 200 всего. Что мешает возврату, называет отказ 409: справочник.

Мерчант, которого выключил администратор, возвраты создавать и читать может; остальной API ему закрыт.

Ключ повтора

Заголовок Idempotency-Key у возврата обязателен: без него отказ 400 с правилом idempotency_key_required.

  • Тот же ключ и то же тело у того же платежа: тот же возврат в нынешнем виде и заголовок Idempotency-Replayed: true, второго возврата нет.
  • Отказ 409 с правилом, например refund_exceeds_remaining, занимает ключ: повтор с тем же ключом получит тот же отказ, исправленный запрос отправляйте с новым ключом. Исключение request_in_progress: запрос с этим ключом ещё идёт, повторите его тем же ключом и тем же телом. refund_in_progress значит, что у платежа идёт другой возврат: прочитайте возвраты платежа, и если идущий не ваш, повторите после его исхода тем же ключом.
  • Отказ ключа API, мерчанта или контура при верном секрете (401 api_key_disabled, api_key_revoked, api_key_expired, 403 merchant_not_active, environment_closed) тоже занимает ключ: повтор с тем же ключом получит тот же отказ, даже когда ключ API включат или мерчанта откроют. Отозванный или просроченный ключ API занимает ключ повтора только сутки после конца ключа; позже его 401 ключ не занимает, но записанное по тому же телу он ещё получает повтором. Записан ли 401, по первому ответу не видно: повторите тот же запрос с тем же ключом повтора действующим ключом API, записанный отказ придёт с Idempotency-Replayed: true.
  • После таймаута, обрыва связи или ответа 5xx повторите создание тем же ключом и тем же телом: возврат мог быть заведён. Ответ 503 dependency_unavailable у возврата не отказ, а «ответа нет», какое бы правило он ни назвал. Новый ключ и новый номер возврата завели бы второй.
  • Ключи общие с ключами создания платежа: ключ, уже использованный платежом, на возврате получит idempotency_key_reused.

Номер возврата reference уникален у мерчанта в контуре: второй возврат с тем же номером получит отказ refund_reference_exists с номером уже заведённого.

Статусы

СтатусЧто значит
PENDINGВозврат идёт или его исход неизвестен
SUCCEEDEDДеньги ушли плательщику
FAILEDВозврата не было; причина в reason

Незнакомый статус читайте как PENDING. Неизвестный исход это PENDING с inReview: true, а не отказ: деньги могли уйти, и второй возврат тех же денег не заводят. Исход называет доспрос провайдера: часто в первый час, раз в час до суток, потом раз в сутки и раз в неделю, до 90 суток. Возврат, который провайдер через API не проводит, и возврат, исход которого провайдер не назвал или назвал противоречиво, решают сотрудники Paydex: SUCCEEDED, если возврат сделан у провайдера, или FAILED с причиной operator_declined, если его не было. До решения такой возврат остаётся PENDING. Читайте его раз в час в первые сутки и раз в сутки дальше; если он PENDING дольше суток, спросите поддержку, назвав id возврата. Если провайдер вернул другую сумму, возврат остаётся PENDING с inReview: true, пока его не исправят вручную: спросите поддержку, назвав id возврата.

У FAILED и SUCCEEDED по позднему ответу провайдера может появиться inReview: true при том же статусе. О возврате через API провайдера, у которого можно спросить статус, переспрашивают после его отказа трое суток, после решения сотрудников до 90 суток от создания возврата и не меньше трёх суток после решения, а по его сообщению о возврате и позже. Такой разбор сам не снимается: тех же денег не возвращайте ни новым возвратом, ни другим путём и спросите поддержку, назвав id возврата. Об этом приходит refund.updated; перед возвратом тех же денег другим путём всё равно перечитайте возврат.

Тестовые данные

В тестовом контуре возврат исполняет подставной провайдер, исход задаёт метка в metadata.sandbox возврата. Без метки возврат принимается и проходит при первой проверке. Метки: paid, pending, declined, declined_later, declined_then_paid, not_sent, timeout_paid, timeout_declined, timeout_unknown, unparsed, wrong_amount. Незнакомая метка даёт FAILED с причиной technical_failure.

API v1 · собрано 18.11.2026 · выпуск f13e6bf

Справочник методов собирается из кода сервера: он не описывает адрес, которого нет.