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
Master account accountId Your organisation’s primary funds per currency. Listed via GET /v2/accounts. 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. Fund master accounts – Prefund via the finance rails agreed with PayCA.
  2. Allocate to users – Call POST /v1/users/transfer from a master account 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.

Use GET /v2/accounts for current master account balances and enabled BINs per currency.

Key Payloads

User Creation

Create request (body):

{
  "userId": "7f1e2b8e-5d0e-4c5a-9a3c-1a2b3c4d5e6f",
  "status": "pending",
  "bins": [
    {
      "bin": "411111",
      "currencyCode": "USD",
      "provider": "visa",
      "settings": { "minCardBalance": "25.00" },
      "isTokenizable": true,
      "fees": {
        "minCardBalance": "25.00",
        "issueFee": "1.50",
        "monthlyFee": "0.00",
        "authorization": [{ "range": "0-100", "value": "0.35" }],
        "decline": [{ "range": "0-100", "value": "0.10" }]
      }
    }
  ],
  "meta": { "segment": "pro" }
}

Create response (201):

{
  "userId": "7f1e2b8e-5d0e-4c5a-9a3c-1a2b3c4d5e6f",
  "userAccountId": "b8b5e4e1-6afd-4b27-9b26-2bd5b30d6a77"
}
  • Persist both userId and userAccountId. Fetch the full user resource via GET /v1/users/{id} when you need status, account.id, or enabled BINs.
  • 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).

Master Account Snapshot

{
  "accounts": [
    {
      "id": "tenant-usd",
      "currency": "USD",
      "balance": { "available": "18500.00", "pending": "120.50" },
      "status": "active"
    }
  ]
}

Interpretation:

  • balance.available – Immediate buying power for new transfers or card loads.
  • balance.pending – Authorisations currently holding against the account (master accounts and user wallets can both have pending holds).

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 master-account 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 master accounts. You only interact with the APIs outlined above.

How do I know when to top up?
Use GET /v2/accounts and alerts on accounts[].balance.available to trigger treasury actions.

Where do I see fees?
Fees appear in account_transaction webhooks with type=fee and in GET /v1/accounts/{id}/transactions. 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.