Workflow Guides
Workflow pages connect dashboard actions, API actions, pricing impact, and troubleshooting. Use this page when you want the full operating sequence instead of only endpoint examples.
Developer note: For SDK/API examples across fixed amount invoices, auto-detected payments, payout routes, dynamic payout recipients, and programmatic withdrawals, see Payment flows. Receive payments
Use this workflow when the payer should pay a specific amount for an order, checkout session, invoice, top-up, or service.
Before you begin
- Confirm the business is in the correct environment: sandbox or live.
- Confirm the token and
networkId are supported.
- Store API keys only on your backend.
- Configure webhook URL and signing secret.
- Decide what your system should do after
paid or overpaid.
What you do
- Create or find a customer.
- Create an invoice with
amount, token, chain, networkId, and your own order metadata.
- Show the hosted invoice link or render the payment address in your own checkout.
- Wait for PayChain to detect and confirm the transfer.
- Verify the webhook signature with the raw request body.
- Fetch the canonical invoice.
- Fulfill the order only after the canonical invoice is
paid or overpaid.
- Store the PayChain invoice ID, transaction hash, and your order reference together.
Expected result
- The invoice moves from
pending to confirming when payment is observed.
- The invoice moves to
paid after settlement confirmation.
- Eligible funds are swept or made available for treasury movement according to the supported rail and business policy.
- Your backend receives a signed webhook.
- Your own order moves to fulfilled once your handler verifies and fetches the invoice.
Pricing or gas impact
- The invoice fee applies when the invoice settles.
- Inbound payment detection does not consume gas credits.
- Automatic settlement or sponsored outbound movement after payment may consume gas credits.
Troubleshooting
| Issue | What to check |
|---|
Invoice stays pending | Confirm the payer used the exact network, token, and address. |
Invoice stays confirming | Wait for required network settlement confirmations. |
| Webhook did not arrive | Check webhook URL, delivery logs, retry state, and endpoint response code. |
| Customer paid wrong asset | Do not fulfill unless PayChain marks the invoice settled. |
| Customer underpaid | Wait for completion or follow your underpayment policy. |
Auto-detect payments
Use auto-detection when repeat payers deposit to reusable customer addresses and you do not want to pre-create every invoice.
Before showing a reusable customer address, ensure the customer has an address for the exact rail you are about to display. For Solana mainnet, use POST /api/v1/businesses/:businessId/customers/:customerId/addresses/ensure or paychain.customers.ensureAddress(...) with chain: "sol" and networkId: "sol-mainnet". If no Solana address is returned, fail setup instead of falling back to an EVM 0x... address.
What PayChain does
- Watches supported customer deposit addresses.
- Ignores non-positive observations.
- Ignores internal operational transfers.
- Applies auto-invoice minimum and dust thresholds.
- Creates an auto-generated invoice for a qualifying deposit.
- Emits the normal invoice webhook.
Dust and minimum rules
Auto-detected deposits use plan and network guardrails so tiny or operational transfers do not become customer revenue.
| Rule | Applies to | Behavior |
|---|
dustThresholdUsd | Auto-detected observations | Below-threshold observations are ignored. |
autoInvoiceMinUsd | Auto-generated invoices | Deposits below the auto-invoice minimum do not create revenue records. |
| Explicit invoice economics | Merchant-created invoices | Small invoices can be created if expected merchant net is positive. |
Dust protection note: Auto-detected dust protection does not mean customers cannot pay small explicit invoices. Explicit invoices are safer for exact small payments because the expected amount, asset, and network are known up front.
Settlement confirmation
PayChain separates “observed” from “settled.” A transfer can be seen before it is safe to treat as final.
| Stage | Meaning | Fulfillment guidance |
|---|
| Observed | A matching transfer was detected. | Do not fulfill yet. |
| Confirming | PayChain is waiting for required finality. | Keep showing pending/confirming. |
| Settled | Required confirmation/finality rules passed. | Fulfill after webhook verification and canonical fetch. |
| Rejected | Wrong asset, wrong network, invalid amount, or failed validation. | Do not fulfill. |
GET /api/v1/invoices/:invoiceId or the authenticated invoice detail endpoint. The response includes confirmationProgress.current, confirmationProgress.required, confirmationProgress.remaining, confirmationProgress.percent, and confirmationProgress.txHash when a matching transaction is detected.
Payout routes
A payout route is an approved template that tells PayChain how to split an invoice after it is fully paid. Use payout routes when the same split pattern repeats. Use dynamic payout recipients when each invoice has a one-time receiver, such as an on-ramp or marketplace order.
Each recipient leg counts as one payout API withdrawal for quota and fee purposes.
Payout route note: Payout routing triggers after full invoice settlement. It should not run for tolerated underpayments, failed invoices, or payments that do not match the invoice asset.
Withdraw funds
Withdrawals move business treasury funds to an external destination. Dashboard withdrawals are operator-driven; payout API withdrawals are backend-driven.
Pricing note: Programmatic withdrawals with payout API keys are allowed when policy and balance checks pass. Free plan businesses have 0 included payout API withdrawals, so the Free payout API fee applies from the first backend-created withdrawal.
Withdrawal lifecycle
- Quote the withdrawal.
- Review amount, token, network, fee, and destination.
- Create the withdrawal with a payout API key or dashboard action.
- PayChain queues the withdrawal.
- If the funds were just paid into an invoice or customer address, PayChain may wait for sweep completion before submitting the payout.
- PayChain submits the network transaction where applicable.
- PayChain sends withdrawal webhooks as the status changes.
Fresh-payment note: If your backend creates a withdrawal immediately after an invoice.paid webhook, the withdrawal can enter pending_funds while PayChain finishes moving sweepable funds into withdrawable treasury capacity. Poll the withdrawal or listen for withdrawal webhooks instead of treating this as a failed payout.
Edge cases
| Case | Meaning | Operator action |
|---|
pending_funds | Recent invoice funds appear eligible but are still sweeping into treasury capacity. | Wait for the withdrawal to continue processing. |
| Insufficient balance | Funds are not available, not sweepable, or below the requested amount after policy checks. | Lower amount, wait for settlement, or resolve recovery-required funds. |
| Funds reserved | Another withdrawal already reserved the same funds. | Wait for terminal state. |
gas_blocked | Sponsored network cost is not currently covered. | Top up gas credits. |
| Destination rejected | Destination failed policy or format checks. | Correct destination or policy. |
| Broadcasted but not completed | Network submission happened but final confirmation is pending. | Wait and track status. |
Reconcile balances
Reconcile invoices, payments, balances, withdrawals, and transactions together. Raw wallet balance is not the same as invoice truth.
Use the balance fields intentionally:
amounts.total is the merchant-facing withdrawable amount.amounts.totalHeld is the projected amount PayChain can see across active address rows.amounts.requiresRecovery is visible for reconciliation, but is not currently counted as withdrawable capacity.
See Reconciliation for examples.
Webhook lifecycle
PayChain sends a webhook after important state changes. Your endpoint should verify, deduplicate, fetch the canonical resource, act once, and return a 2xx quickly.
See Webhooks for payload examples, retry behavior, and replay guidance.