PayCA keeps the user lifecycle intentionally small. You create a user, activate them, move money in their wallet, issue cards, and control everything through one status field.

Mental model

  • A user is your customer record.
  • Every user has one user account (ledger wallet) created automatically.
  • A user can have many cards, all tied to that user account.
  • Webhooks mirror activity: card_transaction, user_account_transaction, account_transaction.

Lifecycle at a glance

  1. POST /v1/users creates the user. Status defaults to pending.
  2. PATCH /v1/users/{id}/status sets the user to active after KYC.
  3. POST /v1/users/transfer moves funds in or between wallets.
  4. POST /v1/cards issues cards against the user account.
  5. Setting a user to frozen or blocked automatically freezes or closes their cards.

Create and activate

  1. Create the user with POST /v1/users.
    • Persist userId + userAccountId from the create response, then fetch GET /v1/users/{id} when you need status and account.id.
  2. Update profile or BIN pricing when needed:
    • POST /v1/users/{id}/bins to add or update BIN configuration.
  3. Activate when ready:
    • PATCH /v1/users/{id}/status with { "status": "active" }.

Fetch the current record any time via GET /v1/users/{id}.

Move money

  • Check balances: GET /v2/accounts for master accounts and GET /v1/users/{id} for user wallets.
  • Transfer between PayCA accounts: POST /v1/users/transfer.
    • Both source and destination users must be active.
    • Always send an Idempotency-Key to avoid duplicate transfers.
  • Audit activity:
    • GET /v1/users/{id}/account/transactions
    • GET /v1/users/{id}/card/transactions

Cards

  1. Issue a card with POST /v1/cards and the user’s userAccountId.
  2. Optional card controls:
    • Freeze/unfreeze: POST /v1/cards/{id}/freeze, POST /v1/cards/{id}/unfreeze.
    • Close: DELETE /v1/cards/{id}.
  3. Card issuance and money-moving card actions are allowed only when the owning user is active.

Status-driven control (latest)

Change lifecycle state with PATCH /v1/users/{id}/status. The response is the refreshed user resource.

Status Meaning What PayCA enforces
active Normal operations Cards and transfers work normally.
pending Not yet cleared Read-only; no new debits or transfers.
frozen Temporary stop All cards are frozen automatically.
blocked Permanent stop All cards are closed automatically.

Use this endpoint instead of managing each card individually when you need to pause or terminate a user.

Webhooks you’ll see

  • card_transaction for spends and card state changes (freeze/unfreeze/close).
  • user_account_transaction for user wallet movements (deposits, withdrawals, transfers).
  • account_transaction for tenant-level mirror/revenue/fee entries.

Related guides