PayCA surfaces programme fees directly to your tenant. 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 in two places:

  1. feesThisMonth inside GET /v1/users/stats – running total per currency.
  2. account_transaction webhooks with type=fee – event-level detail.

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

Fee Catalogue

Scenario Webhook subtype Typical Timing
Authorization approved authorization_fee Immediately after card_transaction (authorization).
Provider decline decline_fee Alongside card_transaction (declined).
Settlement posted settlement_fee When the card clears.
Platform fee platform_fee According to your commercial agreement.

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": "authorization_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 the recognised fees back to treasury, transfer them out of the tenant balance:

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": "tenant-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.
  • Use feesThisMonth to sanity-check your daily exports.

Frequently Asked Questions

Do I need to account for provider settlement ledgers?
No. PayCA reconciles those internally and reduces your tenant 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.