This guide covers the master-account operating model: fund accounts, issue or top up cards, then reconcile account and card ledgers.

What You Control #

  • Master accounts: Primary client accounts per currency.
  • Card lifecycle actions: Issue, top up, withdraw, freeze, close.
  • Webhook ingestion: card_transaction and account_transaction streams.

Everything else (provider settlement internals, scheme-side clearing plumbing) is handled by PayCA.

Workflow Overview #

  1. Prefund master accounts through the agreed finance channel.
  2. Issue cards and assign opening balances from master accounts.
  3. Operate cards (topup/withdraw) as needed.
  4. Reconcile balances and movements using APIs and webhooks.

Step 1 - List Master Accounts and Check Balances #

curl -s "$PAYCA_BASE_URL/v2/accounts" \
  -H "x-client-id: $PAYCA_CLIENT_ID" \
  -H "x-client-secret: $PAYCA_CLIENT_SECRET"

Focus on:

  • accounts[].balance.available -> spendable funds.
  • accounts[].balance.pending -> holds from unsettled activity.

Step 2 - Issue or Top Up a Card #

Issue:

curl -s -X POST "$PAYCA_BASE_URL/v1/cards" \
  -H "Content-Type: application/json" \
  -H "x-client-id: $PAYCA_CLIENT_ID" \
  -H "x-client-secret: $PAYCA_CLIENT_SECRET" \
  -d '{
    "accountId": "<master-account-id>",
    "bin": "411111",
    "balance": "250.00",
    "idempotencyKey": "issue-20260212-001"
  }'

Top up:

curl -s -X POST "$PAYCA_BASE_URL/v1/cards/<card-id>/topup" \
  -H "Content-Type: application/json" \
  -H "x-client-id: $PAYCA_CLIENT_ID" \
  -H "x-client-secret: $PAYCA_CLIENT_SECRET" \
  -d '{
    "accountID": "<master-account-id>",
    "amount": "50.00",
    "idempotencyKey": "topup-20260212-001"
  }'

Store transaction identifiers and idempotency keys for safe retries.

Step 3 - Observe Card Activity #

In sandbox, trigger events via POST /sandbox/transactions. In production, ingest live webhooks.

Watch for:

  • card_transaction: authorization, settle, refund, cancel, decline.
  • account_transaction: holds, releases, fees, and account-level transfers.

Step 4 - Reconcile #

Daily or weekly:

  1. Balances: GET /v2/accounts for master-account totals.
  2. Activity: Export webhooks by data.id and group by referenceId.
  3. Fees: Sum account_transaction events where type=fee.
  4. Variance: Compare PayCA totals with your internal ledger and investigate by referenceId + idempotency keys.

Best Practices #

  • Always include Idempotency-Key on write operations.
  • Persist webhook payloads before business processing.
  • Alert on low master-account balance and elevated decline rates.
  • Keep a reconciliation job that checks expected vs actual balance deltas.

Troubleshooting #

Issue Likely Cause Next Step
Operation rejected with ErrInvalidArg Currency mismatch or invalid account/card ID. Validate currency and identifiers first.
Authorization denied with insufficient_liquidity Low master-account balance. Top up funding and retry.
Duplicate operation detected Reused idempotency key with different payload. Generate a new key per unique intent.
Missing webhook Receiver returned non-2xx or timed out. Fix receiver, then call /v1/webhooks/resend.

For ingestion hardening, see Webhook Handling Patterns. For subtype-level balance effects, use Webhook Balance Effects.