OverviewAuthentication & environmentsStaging faucetCore conceptsReceive paymentsAuto-detect paymentsConfirm settlementWithdraw fundsContract interactionsReconcile balancesBusiness identitySettings & complianceCustomers & invoicesWithdrawals & treasuryContracts & automationReference data & billingWebhooks & eventsUse-case playbooksErrors & edge casesGo-live guideChangelog
Operations
Errors, edge cases, and operator cautions
These are the cases that most often break production integrations if they are not designed up front.
Invoice edge cases
| Case | Trigger | What PayChainHQ returns | Your next action |
|---|---|---|---|
| Underpayment within tolerance | Shortfall is below configured raw tolerance. | `status=paid`, `settledByTolerance=true`, `toleranceShortfall` populated. | Fulfill, but store the actual paid amount and shortfall metadata. |
| Underpayment above tolerance | Shortfall exceeds configured tolerance. | `status=partially_paid` until top-up or expiry. | Do not fulfill; keep polling or wait for additional payment. |
| Expired partial | `expiresAt` passes before enough funds arrive. | Invoice becomes effectively expired and may surface as `expired (partial)` in UI. | Stop counting it as open and route to manual support. |
| Overpayment | More matching asset value arrives than expected. | `status=overpaid` with actual paid amount. | Fulfill and apply your refund / credit policy. |
| Wrong asset or internal transfer | Native gas or unsupported token arrives on the deposit address. | Invoice does not settle from that asset. | Do not infer payment from address activity alone. |
Withdrawal edge cases
| Case | Meaning | What to do |
|---|---|---|
| `forceSweepAll` | Sweep all eligible non-treasury balances, including dust. | Use only when operationally necessary. It still cannot create funds that do not exist net-to-treasury. |
| `Cannot fulfill withdrawal` | Net treasury plus sweepable funds cannot satisfy the payout. | Do not retry blindly. Wait for more funds or change the requested amount. |
| `retrying` | A transient condition delayed completion. | Respect `nextRetryAt` and keep the payout non-terminal. |
| Fee mismatch confusion | Requested amount is not equal to payout amount. | Store requested, fee, and payout amounts separately in your system. |
Environment and auth cautions
- Sandbox activation and live approval are separate. Keep your operator messages explicit.
- Do not move business API keys into browser clients or mobile apps.
- Use payout API keys only from trusted backend workers, and keep destination policy and spend limits narrower than the business treasury policy.
- A notification or hosted invoice page can update faster than a table view if your internal polling is too slow; always key operational truth from API resource state.
- When your system sees a visible in-app toast or webhook, reconcile the underlying invoice or withdrawal object rather than trusting the UI state alone.