PayCA surfaces programme fees directly on master accounts. This guide explains where those fees appear and how to reconcile them.

Fee Signals

You can track fees through:

  1. account_transaction webhooks with type=fee.
  2. GET /v1/accounts/{id}/transactions for historical backfill.

Each fee event includes referenceId to correlate with the originating card flow.

Notes:

  • Provider-side fee sink ledgers are internal and not exposed as separate webhook feeds.
  • All fee accounting for client integrations is represented on account_transaction.

Fee Catalogue

Scenario Webhook subtype Typical Timing
Authorization fee (held/released) settle_fee Charged when authorization settles.
Provider decline decline_fee Emitted with declined card flow.
Card issue issue_fee During card issuance.
Account operation fee settle_fee On account-level operations where applicable.

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"
  }
}

Persist by data.id and join with related card movements via referenceId.

Reporting Checklist

Report How to Build It
Daily fee tally Sum account_transaction amounts by subtype and currency.
Fee by card programme Join fee events with card metadata (BIN, product, tenant labels).
Net programme revenue (authorization + decline + settlement + platform) - reversals.
Statement reconciliation Compare webhook totals with PayCA monthly invoice.

Audit Considerations

  • Archive all fee webhook payloads.
  • Keep immutable referenceId join keys for card-flow evidence.
  • Reconcile daily exports against API backfill queries.

Frequently Asked Questions

Do I need to account for provider settlement ledgers?
No. PayCA reconciles provider-side fee ledgers internally.

Can I change fee tiers mid-month?
Coordinate with your PayCA account manager; updates apply prospectively.

Can sandbox replay fees?
Yes. Enable fee simulation during onboarding to validate reports before go-live.

Next step: verify ingestion resilience in Webhook Handling Patterns.