Перейти к содержимому
API
Открыть .md
На странице

Симуляция

Переведите тестовый возврат по инвойсу в статус completed, failed или cancelled и получите подписанный вебхук.

POST/v1/sandbox/refunds/:withdrawal_id/simulate

API-ключ: Payment (тестовый режим)

Только для песочницы. Переводит существующий тестовый возврат (is_test: true) в указанный финальный статус (completed, failed или cancelled), обновляет тестовый баланс и отправляет соответствующий вебхук withdrawal.completed, withdrawal.failed или withdrawal.cancelled с полным контрактом возврата.

Тело запроса

Параметр Тип Обязателен Описание
status string Да Целевой финальный статус: "completed", "failed" или "cancelled" 
{
  "status": "completed"
}

Ответ (200 OK)

{
  "withdrawal_id": "wdr_6Qm2fK8xR4vN7cT1bY9dL5",
  "invoice_id": "inv_7K2M9P4Q8R1X5Z3A0bC2dE",
  "mode": "full",
  "external_order_id": "refund-1042-full",
  "status": "completed",
  "is_final": true,
  "is_test": false,
  "amount": "100.00",
  "fee": "1.00",
  "currency": "USDT",
  "network": "TRC20",
  "destination_address": "TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9",
  "first_sender": "TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9",
  "tx_hash": "9f3b8c2a1d0e4f6789abc123def4567890abc123def4567890abc123def45678",
  "explorer_url": "https://tronscan.org/#/transaction/9f3b8c2a1d0e4f6789abc123def4567890abc123def4567890abc123def45678",
  "created_at": 1767225600,
  "completed_at": 1767225932,
  "type": "refund",
  "project_id": "prj_3F9xL2mN8pQ4rT6vW1yZ5b"
}

Правила

  • —Сначала создайте тестовый возврат через POST /v1/refunds с помощью тестового ключа Payment (pk_test_), а затем передайте его withdrawal_id в этот метод.
  • —Повторный вызов simulate для возврата, который уже находится в запрошенном финальном статусе, идемпотентен и возвращает 200 OK без повторной отправки вебхука.
  • —Вызов simulate с другим финальным статусом после завершения возврата возвращает 409 invalid_withdrawal_state.
  • —Симуляция "completed" фиксирует списание зарезервированных средств и присваивает синтетический tx_hash. Симуляция "failed" или "cancelled" разблокирует amount + fee обратно на тестовый баланс, позволяя создать новый возврат по инвойсу.

Ошибки

Код HTTP Когда возникает
payment_key_required 403 Запрос подписан ключом Payout (rk_)
refunds_not_enabled 503 Возвраты по инвойсам отключены в данном окружении
withdrawal_not_found 404 Идентификатор не существует, не относится к тестовому возврату или не входит в область видимости ключа
invalid_withdrawal_state 409 Возврат уже находится в другом финальном статусе
field_invalid_enum 400 Поле status не равно "completed", "failed" или "cancelled"

Полное описание работы в тестовой среде приведено в разделе Тестирование, а список всех кодов — в Кодах ошибок.

Назад Получить возврат Далее Получение балансов