Rather than polling GET /api/transaction/:paymentReference, register a webhook URL and Tradevu will POST a JSON payload to it whenever a collection’s status changes.

​
Registering your endpoint

​
Payload

​
string
The reference you supplied on POST /api/deposit — use this to match the webhook to your own records.
​
string
The Tradevu-generated memo shown in paymentInstruction.
​
number
How much has been paid in so far — compare against amount to detect partial payments.
​
number
amount - paidAmount. Zero means fully paid.
​
boolean / string
Whether the transaction completed, and a human-readable summary. A falsy status with a reason in message indicates failure.
There is currently no signature header on outbound webhooks. Don’t rely on the payload alone to authorize a state change in your system — always confirm status by calling GET /api/transaction/:paymentReference (or verify the webhook is arriving from an IP/hostname you trust) before crediting anything downstream.
Webhooks cover payment collections only. Payout completion is not pushed to your webhook — track payouts by the sessionId returned from POST /api/payout. See Payouts.

​
Delivery behavior

  • Delivery is a single POST attempt — there is currently no automatic retry-with-backoff if your endpoint is down or errors.
  • Respond quickly with a 2xx. Do your heavy processing asynchronously after acknowledging receipt.
  • Because there’s no built-in retry, treat polling (GET /api/transaction/:paymentReference) as your source of truth and webhooks as a low-latency notification layer on top of it — especially for anything settlement-critical.