Moving Funds & Reconciliation

This guide shows how to load funds into PayCA, distribute them to users, and double-check that balances reflect each operation.

What You Control

• Master accounts – Primary client accounts PayCA holds on behalf of your organisation per currency.
• User wallets – Balances tied to individual users (userAccountId).
• Card transactions – Authorisations, settlements, refunds, and declines generated by your customers.

Everything else (provider clearing accounts, scheme fees, reconciliations) is managed by PayCA and surfaced back to you via APIs and webhooks.

Workflow Overview

1. Prefund your master accounts through the finance channel agreed with PayCA.
2. Transfer funds from a master account into a user wallet using the API.
3. Simulate card spend (sandbox) or let production traffic run.
4. Reconcile balances and events using API endpoints and webhook payloads.

Step 1 – List Master Accounts and Check Balance

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 – Available funds per currency.
• accounts[].balance.pending – Holds from outstanding authorisations.

Set an alerting threshold so operations teams know when to top up master accounts.

Step 2 – Allocate Funds to a User

curl -s -X POST "$PAYCA_BASE_URL/v1/users/transfer" \
  -H "Content-Type: application/json" \
  -H "x-client-id: $PAYCA_CLIENT_ID" \
  -H "x-client-secret: $PAYCA_CLIENT_SECRET" \
  -H "Idempotency-Key: transfer-user-123-20250602" \
  -d '{
    "fromAccountId": "<master-account-id>",
    "toAccountId": "<user-account-id>",
    "amount": "250.00",
    "currency": "USD"
  }'

Success response returns a transaction identifier. Store it together with the idempotency key so you can safely retry if the network fails.

Expect a user_account_transaction webhook describing the movement. Use it to update downstream systems (CRM, ERP, customer notifications).

Step 3 – Observe Card Activity

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

Watch for:

• card_transaction webhooks (authorization, cleared, refunded, declined).
• user_account_transaction updates reflecting balance changes.
• Optional account_transaction events that show master-account movements such as fees.

Step 4 – Reconcile

Daily or weekly, pull the data you need for reconciliation:

1. Balances – GET /v2/accounts for master accounts plus per-user GET /v1/users/{id}.
2. Activity – Export webhooks keyed by data.id for the relevant date range.
3. Fees – Sum account_transaction events where type=fee, or query GET /v1/accounts/{id}/transactions for backfill.
4. Variance – Compare API totals with your internal ledger. Investigate difference by tracing back through referenceId and idempotency keys.

Best Practices

• Always include an Idempotency-Key on transfers to guard against double posting.
• Store webhooks before processing to ensure you can replay or audit them later.
• Automate alerts for low master account balance and high decline rates.
• Tag transfers with metadata (e.g., statement period, campaign) to simplify reporting.

Troubleshooting

For more about webhook ingestion, head to Webhook Handling Patterns. To learn how fees are reported back to you, see Fees & Revenue Recognition. For a consolidated flow map, see Money Movement Overview.