This guide walks through every stage of the PayCA user lifecycle—from onboarding to card closure—and highlights the API calls, events, and operational controls you need to wire into your product.

1. Core Entities

Concept Description Primary APIs
User Logical customer profile holding BIN configuration, metadata, and lifecycle status. POST /v1/users, GET /v1/users/{id}
User Account Ledger wallet that backs user-driven transfers and card settlements. GET /v1/users/{id} (account block), POST /v1/users/transfer
Cards Instruments linked to a user account; inherit status controls and liquidity. POST /v1/cards, GET /v1/cards/{id}
Webhooks Event fan-out for user, account, and card activity. POST /v1/webhooks, POST /v1/webhooks/resend

2. Onboarding Flow

  1. Pre-flight checks – confirm BIN coverage, webhook registration, and tenant liquidity (see User Onboarding Checklist).
  2. Create the user – call POST /v1/users with:
    • bins: per-currency BIN assignments and fee overrides.
    • status (optional): defaults to pending; set to active, frozen, or blocked to enforce onboarding gates.
    • meta: structured KYC data (tier, risk score, residency, etc.).
  3. Persist identifiers – capture userId, userAccountId, and status from the response.
  4. Attach metadata – use PATCH /v1/users/{id} to sync compliance updates; payloads bubble into user-focused webhooks.

Tip: Store the PayCA UUIDs in your CRM/SCRM so that support agents can reconcile API traffic with human-friendly references.

3. Funding & Internal Transfers

User accounts are standard ledger wallets that you control.

  1. Fetch current balances with GET /v1/users/{id} (embedded account balances) or GET /v1/users/stats for a tenant-wide snapshot.
  2. Move funds between internal accounts using POST /v1/users/transfer.
    • Requires fromAccountId, toAccountId, and positive amount.
    • Provide an Idempotency-Key header to guarantee once-only execution.
  3. Review history via GET /v1/users/{id}/account/transactions.

Every transfer generates a webhook (user_account_transaction) so downstream systems can reconcile balance changes.

4. Card Lifecycle

Step API Notes
Issue POST /v1/cards Pass userAccountId to tie the card to the user wallet. Respect user status restrictions (see Section 5).
Tokenize POST /v1/cards/{id}/tokenize Optional Apple/Google Pay provisioning.
Freeze/Unfreeze POST /v1/cards/{id}/freeze / POST /v1/cards/{id}/unfreeze Mirrors user status (blocked/frozen users see automatic cascades).
Top up / Withdraw POST /v1/cards/{id}/topup / POST /v1/cards/{id}/withdraw Allowed only when the owning user status permits operations.
Close DELETE /v1/cards/{id} Used automatically when a user is blocked.

Operational telemetry:

  • card_transaction webhook for spends, refunds, freezes, and closures.
  • account_transaction webhook for ledger entries tied to card activity.

5. User Status Model & Controls

PayCA enforces lifecycle states via the status field and the new PATCH /v1/users/{id}/status endpoint.

Status Intent Allowed Actions Cascading Behaviour
active Normal operations Card issuance, top-ups, withdrawals, transfers Frozen cards are thawed.
pending KYC review or delayed activation Same as active (configurable) No cascade; treat as soft hold.
frozen Temporary lock (investigation) Read-only APIs only; no card or account debits All open cards are frozen.
blocked Permanent termination No financial operations permitted All cards are closed.

Status change workflow

  1. Call PATCH /v1/users/{id}/status with { "status": "frozen" } (valid values: active, pending, frozen, blocked).
  2. PayCA updates both the client user and the linked account status in the ledger.
  3. Cards belonging to the user are cascaded:
    • Frozen → ChangeCardFreezeState workflow (idempotent).
    • Blocked → CloseCard workflow (idempotent; skips already-closed cards).
  4. Webhooks:
    • user_status_changed
    • card_transaction (freeze, unfreeze, or close)

The API responds with the refreshed user resource, so you can immediately reflect the new state in your UI.

6. Enforcing Status in Your Product

  • Before funding or card commands: Fetch GET /v1/users/{id} or cache the status to prevent disallowed operations (frozen/blocked).
  • Account transfers: The server validates that both source and destination user accounts belong to users whose status allows operations.
  • Idempotency: Always supply stable idempotency keys when automating status transitions to avoid duplicate cascades.
  • Audit trail: Pair status changes with internal CRM notes; PayCA’s webhooks include the actor (clientId) and correlation IDs for downstream reconciliation.

7. Operational Playbook

  1. Monitoring:
    • Subscribe to user_status_changed webhooks.
    • Track freeze/blocked counts for compliance dashboards.
  2. Rollback:
    • Unfreeze via PATCH /v1/users/{id}/status ("status": "active").
    • Blocked users require manual review; cards remain closed.
  3. Support tooling:
    • Show user, account, and card statuses side-by-side.
    • Surface last status change timestamp (from user response updatedAt field if present in your integration).

8. Related Guides

Keep this document handy when designing automations or investigating escalations—the lifecycle logic centralizes all user-related controls in one place.