PayCA surfaces programme fees directly to your master accounts. This guide explains when fees appear, how to capture them, and reports you can build on top of the data.

Fee Signals

You’ll see fees through:

  1. account_transaction webhooks with type=fee – event-level detail.
  2. GET /v1/accounts/{id}/transactions – historical backfill if you need it.

Each fee references the transaction that generated it via referenceId. No additional ledger digging is required.

Notes:

  • PayCA uses internal provider fee accounts to track fee sinks per provider/currency; those internal credits are not delivered as webhooks.
  • If you price fees to end-users, the user reimbursement appears as user_account_transaction events (withdraw_user from the user wallet and deposit_user to your master account) sharing the same referenceId.

Fee Catalogue

Scenario Webhook subtype Typical Timing
Authorization fee (held/released) settle_fee Charged when the authorization clears (settlement).
Provider decline decline_fee Alongside card_transaction (declined).
Card issue issue_fee During card issuance.
Account operation fee settle_fee When an account-level fee applies (not card auth fees).

All amounts match the card currency unless your contract specifies otherwise.

Sample Webhook

{
  "event": "account_transaction",
  "data": {
    "id": "fee-82f9",
    "accountId": "tenant-usd",
    "type": "fee",
    "subtype": "settle_fee",
    "amount": "0.35",
    "currency": "USD",
    "referenceId": "auth-789",
    "timestamp": "2025-06-02T11:24:12Z"
  }
}

Store the payload using data.id and link it back to the originating card transaction with referenceId. This lets you build customer-level fee summaries or aggregate by BIN, merchant, or programme.

Reporting Checklist

Report How to Build It
Daily fee tally Sum webhook amounts by subtype and currency.
Fee per user Join fee events (via cardId) to your user records.
Net programme revenue (authorization + decline + settlement + platform) - reversals.
Statement reconciliation Compare webhook totals with PayCA monthly invoice.

Revenue Sweeps

When you’re ready to move accumulated balances (e.g. fee reimbursements collected from users) back to treasury, transfer them out of the relevant master account:

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: sweep-jun-2025" \
  -d '{
    "fromAccountId": "master-usd",
    "toAccountId": "treasury-usd",
    "amount": "1450.20",
    "currency": "USD"
  }'

Tag the request with metadata (period, journal reference) if you plan to ingest it into an ERP.

Audit Considerations

  • Archive every fee webhook payload (S3, BigQuery, etc.).
  • Tie fee totals to specific card transactions via referenceId for audit trails.
  • Sanity-check your daily exports against your own fee aggregation and account transactions.

Frequently Asked Questions

Do I need to account for provider settlement ledgers?
No. PayCA reconciles those internally and reduces your master account balance when a fee applies.

Can I change fee tiers mid-month?
Contact your PayCA account manager. Updates apply prospectively; existing authorisations keep the original tier.

Can sandbox replay fees?
Yes—enable them during onboarding so you can test reporting before launch.

Next step: confirm your webhook ingestion is resilient by following Webhook Handling Patterns.