Payment and fee reconciliation
Partners often need to align payment webhooks, fee charges, and ERP general ledger entries. This guide explains how Paystand surfaces those events and which APIs to use.
Merchant fees vs payer fees
Paystand exposes two distinct fee concepts. Do not mix them in ERP journal lines.
| Merchant fees (processing fees) | Payer fees (recoup / surcharge) | |
|---|---|---|
| What it is | Card/network processing cost Paystand charges the merchant for accepting a payment | Convenience fee or surcharge added to the payer's checkout total per Fees & Incentives |
| Who pays | Merchant (reduces net settlement) | Payer (increases amount charged at checkout) |
| Typical APIs | List Fees, Get Fee, Fee Events, embedded fees[] on Get Payment | Split Fees, Compute Fees (fee split), feeSplit on Get Payment |
| Key fields | fee.amount, fee.feeType (delayed → paystand) | payerTotalFees, merchantTotalFees, feeSplitType |
| ERP use | Cost of acceptance, processor reconciliation, net payout math | Invoice principal vs convenience-fee line before/after payment |
Rule of thumb: Fee Events and GET /fees rows are merchant processing fees. Split Fees and feeSplit on payments describe how principal vs payer-side fees were calculated at checkout — use feeSplitType to see whether the merchant absorbed cost or recouped from the payer.
Payment lifecycle
- A payer completes checkout — you may receive Payment Events with
status: Postedwhen funds are captured. - Paystand applies funds to receivables — Receivable Transaction Events describe allocations.
- Merchant processing fees may be assessed — separate Fee Events can arrive after the payment is posted (independent of payer-side recoup/surcharge on the invoice).
Posted vs fee timing
Webhook payloads can show a payment as Posted before all fee rows exist. For reconciliation:
- Store the payment when the Posted event arrives.
- Poll List Fees filtered by
resourceId/ payment ID when your token has access, or re-fetch Get Payment and read embeddedfees[]/feeSplit, or wait for Fee webhooks before closing the ERP journal entry. - Use payment
idas the stable key across calls (see Chaining IDs).
Polling when webhooks are unavailable
| Data | List endpoint |
|---|---|
| Payments | GET /payments/all — List Payments |
| Merchant processing fees | GET /fees — List Fees (may return 401 for Integrations OAuth — use Get Payment embedded fees[] for merchant fees, or feeSplit for payer-side split) |
| Payer fee split (estimate or actual) | POST /feeSplits/splitFees before payment; feeSplit on Get Payment after payment |
| Transfers (payouts) | GET /transfers or GET /transfers/all |
Apply date-range filters on payments, refunds, disputes, and transfers.
Transfers (bank payouts)
When funds move to your bank account, use Transfer Events or List Transfers. Match transfer totals to batched payments and fees in your ERP cash receipt workflow.
Refunds and disputes
- Refunds: Refund Events and List Refunds
- Disputes: Dispute Events and List Disputes
Fee setting plans and pre-payment estimates (payer fees)
These endpoints estimate payer-side recoup/surcharge and merchant-absorbed splits from Fees & Incentives — not finalized merchant processing fees from the card network.
Partners often need card/bank rates or a principal vs payer fee split before posting journals (for example $500.00 principal + $15.00 payer fee = $515.00 payer total).
| Need | API | Fee type |
|---|---|---|
| Estimate all rails from Fees & Incentives (recommended) | Split Fees — POST /feeSplits/splitFees with subtotal (+ optional payerId, invoiceId, feeSettingPlanId) | Payer fees (and merchant-absorbed portion via merchantTotalFees) |
| Single rail (e.g. card only) | Compute Fees (fee split) — POST /feeSplits/computeFees with feeType + subtotal + currency only | Payer fees |
| Read plan config by ID | Get Fee Setting Plan — GET /feeSettingPlan/{id} when you already have a plan ID | Plan config for payer fee rules |
| Low-level compute with your own rule | Compute Fee — POST /fees/compute (requires a rule object) | Generic fee math (integrators usually prefer Split Fees) |
Split Fees / Compute Fees return estimates from configured plans. After payment:
- Payer-side split: read
feeSpliton Get Payment. - Merchant processing fees: use Fee Events, List Fees (when authorized), or embedded
fees[]on Get Payment — especially for card payments where processing fees may change after Posted.
Mapping estimates to ERP journal lines
Inspect feeSplitType on Split Fees / Get Payment responses:
feeSplitType | ERP fee field (typical) |
|---|---|
recoup_custom_of_subtotal, recoup_all_fees, surcharge_and_recoup_all_fees | payerTotalFees (payer pays the fee) |
discount_fees, absorb_all_fees, default | merchantTotalFees (merchant absorbs) |
Merchants on payer recoup plans (for example recoup_custom_of_subtotal) map ERP convenience-fee lines to payerTotalFees, not merchantTotalFees. The Paystand X dummy merchant (recoup_custom_of_subtotal) validated in sandbox follows this pattern.
To inspect which plan was used for a payer, you may have a feeSettingPlanId on customer or payment context. Retrieve the plan with Get Fee Setting Plan when you have the ID from another API response.