Возвраты
Как вернуть плательщику успешный платёж целиком или частью и как узнать, что деньги ушли.
Возврат отправляет плательщику деньги успешного платежа, целиком или частью. Его создаёт сервер мерчанта. Возврат идёт тем же путём, что платёж, и в валюте платежа.
Порядок
Создайте возврат с ключом повтора и суммой:
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 несёт возврат в том состоянии, в каком он есть после обращения к провайдеру. Поля: справочник.
Дождитесь исхода: уведомление
refund.updated(Уведомления) или чтение возврата. Возврат вPENDINGдочитывайте и сами, даже если ждёте уведомлений: недоставленное уведомление не досылается.curl -sS https://api.paydex.co.uk/api/v1/payments/pr_8k3m2q7w9x4t6v5n2b8c4d/refunds/rf_5n7q2w8x4k3m9t6v2b8c4d \ -H "Authorization: Bearer $PAYDEX_API_KEY"- Все возвраты платежа отдаёт
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, 403merchant_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.