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.