Webhook and REST polling matrix
Use this page when you cannot receive webhooks (on-prem ERP, middleware without inbound HTTPS) and need to poll REST list endpoints instead.
Subscribe to webhooks in Dashboard → Integrations → Webhook Event URLs when your stack supports them — see Webhook setup.
Merchant fees vs payer fees (polling)
| Fee type | What it is | Poll with |
|---|---|---|
| Merchant processing fees | Card/network cost to the merchant; finalized in Fee Events | GET /fees (List Fees) when authorized, or embedded fees[] on Get Payment |
| Payer fees (recoup / surcharge) | Amount added to payer checkout per Fees & Incentives | feeSplit on Get Payment; pre-payment via Split Fees |
See Payment and fee reconciliation for ERP mapping (payerTotalFees vs merchantTotalFees vs fees[].amount).
Global headers
Every REST call:
Authorization: Bearer {access_token}
X-CUSTOMER-ID: {merchant_customer_id}
Accept: application/json
Before calendar-day polling
- Obtain a token — Access Token
- Optional but recommended: Get Merchant Timezone and pass
f.timezoneon filtered lists — see Query and incremental sync
Matrix
| Webhook resource | Dashboard webhook docs | REST list (polling) | Pattern A date filter? | Notes |
|---|---|---|---|---|
| Payment | Payment Events | List Payments GET /payments/all | Yes | Also Pattern B: startDate / endDate. See Payment and fee reconciliation — Posted is not fee-final. |
| Fee (merchant processing) | Fee Events | List Fees GET /fees | No | Merchant processing fees only — not payer recoup. Integrations OAuth may return 401 — then poll Get Payment embedded fees[] or prefer fee webhooks. Payer-side split: feeSplit on Get Payment. |
| Receivable transaction | Receivable Transaction Events | List Receivable Transactions per receivable only | No (bulk) | Nested under GET /receivables/{id}/transactions only. Merchant bulk export is not in the public API today — see FAQ. |
| Refund | Refund Events | List Refunds or filtered List Refunds (filtered) | Yes | |
| Dispute | Dispute Events | List Disputes or filtered list | Yes | |
| Transfer | Transfer Events | List Transfers (filtered) or List Transfers | Yes (filtered /transfers) | |
| Withdrawal | (no dedicated public webhook page) | List Withdrawals (filtered) or List Withdrawals | Yes (filtered /withdrawals) | Payout-related; pair with transfers for cash reconciliation. |
| Receivable (invoice) | (via receivable transaction / payment flows) | List Receivables (filtered) | Yes | Simple pagination only on List Receivables (read). |
| Credit memo | (no public webhook type today) | List Credit Memos | No | Use f.querytype=own, by-payerCustomerId, or by-erpName only. Transactional master data for ERP — not payer master data. |
| Payer customer | (no public webhook type today) | List Customers | No | Master data; pagination only. |
Pattern A reminder
Date filters apply only when:
f.querytype=by-query-filters
Without it, f.datestart, f.dateend, and related params are ignored. Full details: Query and incremental sync.