Возврат платежа

POST/integration/transactions/{uuid}/refund

Полный путь: /api/v1/integration/transactions/{uuid}/refund. Используйте UUID транзакции Cashera из ответа создания платежа, а не идентификатор провайдера. Транзакция должна принадлежать мерчанту, указанному API-ключом.

Это заявка, а не мгновенный возврат

Новая заявка получает статус requested и проходит ту же проверку администратором, что и возврат из личного кабинета. Только после одобрения система проверяет возможность возврата у провайдера и отправляет его. Сам POST не меняет баланс и не вызывает провайдера. 201 Created не означает, что плательщик уже получил деньги.

Условия

Поддерживается полный возврат оплаченного входящего платежа со статусом paid
На первом этапе поддерживаются транзакции Platega с сохранёнными реквизитами провайдера. Возможность возврата конкретного платежа дополнительно проверяется при одобрении
Частичный возврат не поддерживается. Не передавайте сумму, валюту, реквизиты получателя или статус
Одна транзакция — одна заявка, независимо от того, создана она через API или личный кабинет

Авторизация

Для создания и чтения нужны X-Api-Key, X-Timestamp и X-Signature. Используется тот же HMAC-SHA256 алгоритм, что для выплат, но с путём возврата и соответствующим методом POST или GET. Секрет храните только на сервере. Действуют ограничения мерчанта и список разрешённых IP.

Поле	Тип	Описание
`uuid`обязательное	`uuid (path)`	UUID исходной транзакции Cashera. external_id платежа можно найти через поиск транзакции
`Тело запроса`	`пустое`	Отправляйте пустое тело или пустой JSON-объект `{}`. Любые параметры, в том числе amount: null, отклоняются с 422. Подписывайте точные отправляемые байты

Создание заявки

# Экспортируйте CASHERA_API_KEY, CASHERA_API_SECRET и CASHERA_TRANSACTION_UUID
export CASHERA_REFUND_PATH="/api/v1/integration/transactions/$CASHERA_TRANSACTION_UUID/refund"
export CASHERA_REFUND_TIMESTAMP=$(date +%s)
signature=$(python3 - <<'PY'
import hashlib, hmac, os
parts = [os.environ["CASHERA_REFUND_TIMESTAMP"], "POST",
         os.environ["CASHERA_REFUND_PATH"], hashlib.sha256(b"").hexdigest()]
print(hmac.new(os.environ["CASHERA_API_SECRET"].encode("utf-8"),
               "\n".join(parts).encode("utf-8"), hashlib.sha256).hexdigest())
PY
)
curl --fail-with-body --request POST \
  "https://api.cashera.cash/api/v1/integration/transactions/$CASHERA_TRANSACTION_UUID/refund" \
  --header "X-Api-Key: $CASHERA_API_KEY" \
  --header "X-Timestamp: $CASHERA_REFUND_TIMESTAMP" \
  --header "X-Signature: $signature" \
  --header 'Accept: application/json'

Повторный POST по той же транзакции возвращает ту же заявку с текущим статусом и кодом 201. Новый external_id не нужен: ключом идемпотентности служит UUID транзакции. Повтор не открывает заново отклонённый или завершённый возврат.

Получение статуса

GET/integration/transactions/{uuid}/refund

Тот же UUID исходной транзакции, пустое тело и новая подпись для метода GET. Ответ 200 OK содержит тот же объект заявки. Если заявки ещё нет, вернётся 404.

Поле	Тип	Описание
`uuid`	`string`	Идентификатор заявки на возврат. В URL используется transaction_uuid, а не это поле
`transaction_uuid`	`string`	UUID возвращаемого платежа
`status`	`string`	Статус заявки из таблицы ниже
`decision_reason`	`string \| null`	Причина решения администратора, если указана
`created_at / updated_at`	`string`	Время создания и последнего изменения, ISO 8601

Поле	Тип	Описание
`requested`	`Ожидает решения`	Заявка создана, нужно одобрение администратора
`checking`	`Проверка`	Проверяется возможность возврата у провайдера
`check_failed`	`Ошибка проверки`	Проверка не завершилась; дальнейшую сверку выполняет администратор
`unsupported`	`Возврат недоступен`	Провайдер не разрешил возврат. Повторный POST не отправляет его заново
`submitting`	`Отправка`	Запрос возврата отправляется провайдеру
`submitted`	`Принят провайдером`	Ожидается подтверждение результата
`manual_review`	`Ручная проверка`	Провайдер запросил ручную обработку
`ambiguous`	`Результат неизвестен`	Требуется сверка, например после таймаута. Не отправляйте отдельный возврат напрямую провайдеру
`rejected`	`Отклонён`	Администратор отклонил заявку; см. decision_reason
`superseded`	`Больше не применим`	Состояние исходного платежа изменилось, например зарегистрирован chargeback
`completed`	`Возврат подтверждён`	Получено подтверждение провайдера, финансовые изменения отражены в системе

Статус заявки и статус платежа различаются: submitted ещё не означает refunded. После подтверждённого возврата исходная транзакция получает статус refunded, и отправляется обычный вебхук изменения платежа. Отдельное уведомление о каждом промежуточном статусе заявки не отправляется — используйте GET.

Ошибки

Поле	Тип	Описание
`401`	`Unauthorized`	Нет или неверны ключ, подпись, timestamp; время запроса вышло за допустимое окно
`403`	`Forbidden`	Мерчант отключён, баланс заморожен, секрет не настроен или IP не разрешён
`404`	`Not Found`	Платёж не найден, принадлежит другому мерчанту, некорректен UUID или отсутствует заявка при GET
`409`	`Conflict`	Для новой заявки исходный платёж должен быть paid
`422`	`Unprocessable Entity`	Неподдерживаемый тип/провайдер платежа, нет идентификаторов провайдера, повреждён JSON или переданы параметры запроса
`429`	`Too Many Requests`	Превышен лимит интеграционного API

После сетевого сбоя проверьте заявку через GET или повторите POST с тем же UUID и свежей подписью