Simulieren

API-Schlüssel: Payment (Sandbox)

Nur in der Sandbox. Überführt eine bestehende Sandbox-Erstattung (is_test: true) in den angeforderten Endstatus (completed, failed oder cancelled), aktualisiert das Sandbox-Guthaben und sendet den entsprechenden Webhook withdrawal.completed, withdrawal.failed oder withdrawal.cancelled mit der vollständigen Erstattungs-Payload.

Anfragekörper

Parameter	Typ	Erforderlich	Beschreibung
status	string	Ja	Gewünschter Endstatus: "completed", "failed" oder "cancelled"

{
  "status": "completed"
}

Antwort (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"
}

Regeln

• —Erstellen Sie die Sandbox-Erstattung zuerst über POST /v1/refunds mit einem Sandbox-Payment-Schlüssel (pk_test_) und übergeben Sie anschließend deren withdrawal_id an diesen Endpunkt.
• —Ein erneuter Aufruf von simulate für eine Erstattung, die sich bereits im angeforderten Endstatus befindet, ist idempotent und gibt 200 OK zurück, ohne einen doppelten Webhook zu senden.
• —Ein Aufruf mit einem abweichenden Endstatus nach bereits erreichtem Endzustand liefert 409 invalid_withdrawal_state.
• —Die Simulation von "completed" schließt die Belastung des reservierten Guthabens ab und vergibt einen synthetischen tx_hash. Die Simulation von "failed" oder "cancelled" gibt amount + fee wieder für Ihr Sandbox-Guthaben frei, sodass Sie eine neue Erstattung für die Rechnung anlegen können.

Fehler

Code	HTTP	Wann
payment_key_required	403	Die Anfrage wurde mit einem Payout-Schlüssel (rk_) signiert
refunds_not_enabled	503	Rechnungserstattungen sind in dieser Umgebung deaktiviert
withdrawal_not_found	404	Die ID existiert nicht, ist keine Sandbox-Erstattung oder liegt außerhalb des Projektbereichs des Schlüssels
invalid_withdrawal_state	409	Die Erstattung befindet sich bereits in einem anderen Endstatus
field_invalid_enum	400	status ist nicht "completed", "failed" oder "cancelled"

Siehe Testen für den gesamten Sandbox-Ablauf und Fehlercodes für den vollständigen Katalog.