PayCA exposes a focused set of entities to your organisation. Everything described here is visible through the public API or webhook payloads.

Entity Overview

Entity Identifier What It Represents Created By
Tenant balance Reported in GET /v1/users/stats (liquidity) Your organisation’s available funds per currency. PayCA ops prefunds; you top up via the finance channel.
User userId End-customer profile, BIN catalogue, metadata. POST /v1/users
User wallet userAccountId Balance associated with a user. Moves when you call transfers or card spend occurs. Created with the user.
Card cardId Virtual or physical card issued to a user. POST /v1/cards
Webhook subscription id Destination for event notifications (card_transaction, user_account_transaction, account_transaction). POST /v1/webhooks

All other ledger plumbing (provider settlement wallets, fee sinks, etc.) is handled by PayCA automatically. You only need to reason about the entities above when integrating.

How Balances Move

  1. Top up tenant balance – Prefund via the finance rails agreed with PayCA.
  2. Allocate to users – Call POST /v1/users/transfer to move funds into a specific user wallet.
  3. Card spend & adjustments – Use card APIs or sandbox helpers; PayCA updates the user wallet and emits webhooks.
  4. Refunds & payouts – Issue refunds through /sandbox/transactions (for tests) or the appropriate production endpoint; user wallet increases accordingly.

The GET /v1/users/stats endpoint reports available balance, pending holds, total spend, and accumulated fees for each currency so you can reconcile your books.

Key Payloads

User Creation

{
  "id": "7f1e2b8e-5d0e-4c5a-9a3c-1a2b3c4d5e6f",
  "userAccountId": "b8b5e4e1-6afd-4b27-9b26-2bd5b30d6a77",
  "bins": [
    {
      "bin": "411111",
      "currencyCode": "USD",
      "fees": {
        "issueFee": "1.50",
        "authorization": [{"range": "0-100", "value": "0.35"}]
      }
    }
  ],
  "meta": {"segment": "pro"}
}
  • Persist both id and userAccountId.
  • Use meta to flag segment, KYC tier, or other downstream routing data.

Card Issuance

{
  "cardId": "0b1e9c6e-5d87-4f90-8c4d-0ad6f4ce4be5",
  "userId": "7f1e2b8e-5d0e-4c5a-9a3c-1a2b3c4d5e6f",
  "linkedAccountId": "2d4b1e1f-1c0e-4b75-8d34-51f1a01af0a0",
  "last4": "8642",
  "status": "active"
}
  • linkedAccountId helps you tie card webhooks back to a user wallet.
  • Store cardId for card lifecycle operations (freeze, replace, close).

Liquidity Snapshot

{
  "liquidity": {
    "usd": {
      "balance": "18500.00",
      "pending": "120.50",
      "spentThisMonth": "4275.90",
      "feesThisMonth": "120.80"
    }
  }
}

Interpretation:

  • balance – Immediate buying power for new transfers or card loads.
  • pending – Authorisations currently holding against the tenant balance.
  • spentThisMonth – Sum of settled card transactions.
  • feesThisMonth – Total fees accrued (see Fees & Revenue Recognition).

Webhook Correlation

Event What to Store Why
card_transaction data.id, cardId, type, referenceId, amount Track card activity and map to the owning user.
user_account_transaction data.id, userAccountId, amount, referenceId Reconcile user wallet balances after transfers or payouts.
account_transaction data.id, accountId, type, subtype, amount Monitor tenant-level movements (fees, top-ups).

Persist payloads keyed by data.id. Use referenceId to link card and account events originating from the same transaction.

Data Handling Practices

  • PII – Keep personal data out of meta unless your PayCA contract explicitly covers it.
  • Retention – PayCA stores history indefinitely; you can archive webhooks to your own data warehouse for analytics and audit trails.
  • Idempotency – Reuse the same Idempotency-Key when retrying POST/transfer requests to avoid duplicate entries.

Common Questions

Do I manage provider clearing accounts?
No. PayCA takes care of scheme settlement and reconciles it against your tenant balance. You only interact with the APIs outlined above.

How do I know when to top up?
Use GET /v1/users/stats and alerts on liquidity.balance to trigger treasury actions.

Where do I see fees?
Fees appear in feesThisMonth and in account_transaction webhooks with type=fee. The Fees & Revenue Recognition guide explains reporting.

Next, read Moving Funds & Reconciliation for step-by-step transfer workflows or Webhook Handling Patterns to design your ingestion pipeline.