Account mapping

Vantrace evaluates the bank-owned account involved in the transaction. Correct account mapping is necessary for transaction history, velocity, KYC limits, and behavioural baselines.

Mapping table

Scenario	`txn_direction`	`source_account_id`	`beneficiary_account_id`	`evaluated_account_id`	`customer_id`
Outbound external	`outbound`	Bank-owned sender	External receiver reference, if known	Bank-owned sender	Owner of sender
Inbound external	`inbound`	External sender reference	Bank-owned receiver	Bank-owned receiver	Owner of receiver
Internal transfer	`inbound` or `outbound` from the primary subject’s perspective	Bank-owned sender	Bank-owned receiver	Primary account under review	Owner of primary account

Outbound external transfer

Customer account ──────────────────► External beneficiary
       ▲
       ├── source_account_id
       └── evaluated_account_id

{
  "source_account_id": 41001,
  "beneficiary_account_id": 91001,
  "evaluated_account_id": 41001,
  "txn_direction": "outbound"
}

The sender is the bank-owned evaluation subject.

Inbound external transfer

External sender ───────────────────► Customer account
                                           ▲
                                           ├── beneficiary_account_id
                                           └── evaluated_account_id

{
  "source_account_id": 91001,
  "beneficiary_account_id": 41001,
  "evaluated_account_id": 41001,
  "txn_direction": "inbound"
}

The beneficiary is the bank-owned evaluation subject. Do not substitute the external sender as the customer being evaluated.

Internal transfer

{
  "source_account_id": 41001,
  "beneficiary_account_id": 42002,
  "evaluated_account_id": 41001,
  "txn_direction": "outbound"
}

Both accounts are bank-owned. evaluated_account_id selects the primary account for this request while preserving both sides of the transfer.

New or previously unseen account

For an account that may not yet exist in Vantrace’s tenant-scoped registry:

Send the correct evaluated_account_id.
Send the matching customer.customer_id.
Include account_snapshot with the same account ID.

{
  "transaction": {
    "source_account_id": 43003,
    "evaluated_account_id": 43003,
    "txn_direction": "outbound"
  },
  "customer": {
    "customer_id": "CUST-3003"
  },
  "account_snapshot": {
    "account_id": 43003,
    "account_type": "current",
    "currency": "NGN"
  }
}

See Which ID should I use? for identifier ownership, stability, and retention guidance.