Matching payments to customers

Every inflow credits your merchant wallet. What changes between rails and owners is whether the credit is attributed to one of your end-users, carried by the customer block on the wallet_funded webhook.

The customer block

"customer": {
  "id": "cus_xxxxxxxxxxxx",
  "customer_reference": "your-internal-user-id"
}

• Present when the credited account (VIBAN or registered Interac address) belongs to a customer.
• Omitted (not null) for merchant-pool / treasury inflows, so existing parsers are unaffected.
• Branch on event.customer?.id: never assume the key is there.

For the full payload + every field, see the wallet_funded field reference in Webhooks (don’t re-spec it here).

Crediting the right end-user

Use customer.customer_reference, the reference you set when you created the customer, to credit the matching user in your own system. The Swappr merchant (business) wallet is the account credited; per-user sub-ledgering is your responsibility. A typical handler:

async function handleWalletFunded(event: WalletFundedEvent) {
  if (event.customer?.id) {
    // Customer-attributed inflow — credit this end-user in your ledger.
    await creditUser(event.customer.customer_reference, event.amountMinor, event.currency);
  } else {
    // Merchant-pool / treasury inflow — record against your own books.
    await recordTreasuryCredit(event.amountMinor, event.currency);
  }
}

Per-customer history

Every inflow and outflow attributed to a customer is queryable as one time-ordered feed:

GET /v1/customers/{id}/transactions

See List customer transactions. The per-customer wallet filter GET /v1/wallets/{id}/transactions?customer_id= returns the raw ledger view of one customer’s movements (requires the customer_transaction_view permission).

Checking balances

Your wallet balances reflect every credit across all rails:

GET /v1/balances

See the Wallets API reference for summary balances, per-wallet balances, and ledger history.

Next

• Webhooks →: wallet_funded payload + field reference
• Customers API reference →: per-customer transaction history
• Wallets API reference →: balances + ledger

What’s next