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.