PayCA exposes a compact object model for client integrations. Everything below is visible via public API responses or webhook payloads.

Entity Overview #

Entity Identifier What It Represents Created By
Master account accountId Primary client funds per currency. Listed via GET /v2/accounts. Provisioned by PayCA ops; topped up through treasury rails.
Card cardId Virtual or physical card funded from a master account. POST /v1/cards
Webhook subscription id Delivery destination for event feeds (card_transaction, account_transaction). POST /v1/webhooks

All internal provider settlement ledgers are managed by PayCA and are not part of the external integration surface.

How Balances Move #

  1. Fund master accounts through your agreed finance rail.
  2. Issue or top up cards from a master account.
  3. Process spend lifecycle (authorization, settlement, reversal, refund, decline).
  4. Reconcile account and card events using webhook payloads and referenceId.

Use GET /v2/accounts for current master-account balances and available BINs.

Key Payloads #

Master Account Snapshot #

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

Interpretation:

  • balance.available -> immediate spending power for card operations.
  • balance.pending -> funds held by unsettled authorizations.

Card Issuance Response #

{
  "cardId": "0b1e9c6e-5d87-4f90-8c4d-0ad6f4ce4be5",
  "linkedAccountId": "tenant-usd",
  "last4": "8642",
  "status": "active"
}
  • linkedAccountId ties the card to the debited master account.
  • Store cardId for lifecycle operations (topup, withdraw, freeze, close).

Webhook Correlation #

Event What to Store Why
card_transaction data.id, cardId, type, referenceId, linkedId, amount Trace card activity from auth to final settlement/refund.
account_transaction data.id, accountId, type, subtype, amount, referenceId Reconcile master-account impact (holds, fees, transfers).

Persist payloads keyed by data.id. Use referenceId to link all legs of the same money movement.

Data Handling Practices #

  • PII: Keep personal data out of metadata fields unless contractually approved.
  • Retention: Archive webhook payloads to your data warehouse for replay and audit.
  • Idempotency: Reuse the same Idempotency-Key only when retrying the exact same intent.

Common Questions #

Do I manage provider clearing accounts?
No. PayCA reconciles provider-side ledgers internally.

How do I know when to top up?
Use GET /v2/accounts and alert on low accounts[].balance.available.

Where do I see fees?
Fees appear in account_transaction webhooks (type=fee) and GET /v1/accounts/{id}/transactions.

Next, read Moving Funds & Reconciliation for operational flow and Webhook Balance Effects for balance-impact details by webhook type.