Skip to content
Vantrace Developer Docs

Which ID should I use?

Identifier Created by Purpose Unique / stable Retry-safe Store it
reference_id Client Connects the Vantrace attempt to your transaction Stable per financial transaction; use your own uniqueness policy Reuse for reconciliation, but it does not make a retry idempotent Yes
trx_id Vantrace Identifies the committed Vantrace transaction Unique Vantrace identifier Do not create or guess it Yes, when returned
X-Request-ID Client Traces one HTTP request attempt Required fresh UUID per attempt Useful for tracing, not duplicate prevention Yes
source_account_id Client Identifies the account funds originated from Stable account identifier Preserve the true source on every attempt Yes with transaction facts
evaluated_account_id Client Selects the bank-owned account Vantrace evaluates Stable account identifier Preserve the same evaluation subject Yes with transaction facts
beneficiary_account_id Client Identifies the receiving account Stable when known Preserve the true beneficiary Yes with transaction facts

Retry and reconciliation rules

Section titled “Retry and reconciliation rules”
  1. Assign reference_id before sending the request.
  2. Generate and log a fresh UUID in X-Request-ID for the attempt.
  3. Store trx_id if a response arrives.
  4. If the request times out, keep the original identifiers and mark the outcome unknown.
  5. Reconcile before deciding whether another submission is safe.