Status Lifecycles
PayChain exposes statuses so your system can decide what to do next. Build your integration around lifecycle states, not raw transaction observations alone.
Fulfillment rule: Fulfill customer orders from confirmed invoice state, not from raw balance changes or unverified transaction history.
Invoice statuses
| Status | Meaning | Typical action |
|---|
pending | Invoice has been created and is waiting for payment. | Show payment instructions. |
confirming | Payment has been observed and is waiting for required settlement confirmation. | Wait. Do not fulfill yet. |
paid | Invoice is fully settled. | Fulfill the order after webhook verification and canonical fetch. |
overpaid | More than the requested amount was settled. | Fulfill according to your policy; reconcile the excess. |
underpaid | Less than the requested amount was settled. | Wait for completion or follow your underpayment policy. |
failed | Invoice is no longer valid or was rejected. | Do not fulfill. |
expired | Invoice expired before settlement. | Ask customer to create or request a new invoice. |
cancelled | Invoice was cancelled. | Do not accept it for fulfillment. |
Confirmation progress: When an invoice is confirming, invoice detail responses include confirmationProgress so your UI can show current confirmations, required confirmations, remaining confirmations, progress percent, and transaction hash.
Withdrawal statuses
| Status | Meaning | Typical action |
|---|
quoted | A quote was generated but no withdrawal has been created. | Confirm terms before creating. |
queued | Withdrawal is accepted and waiting for processing. | Show pending state. |
processing | PayChain is preparing or submitting the transfer. | Wait for final state. |
broadcasted | Transaction has been submitted to the network. | Track hash if available. |
completed | Withdrawal completed. | Mark payout as complete. |
failed | Withdrawal failed. | Review failure reason and retry only when safe. |
cancelled | Withdrawal was cancelled before completion. | Do not retry automatically without operator intent. |
gas_blocked | Sponsored outbound operation is waiting for gas credits. | Top up gas credits or wait for operator action. |
Payout routing statuses
| Status | Meaning |
|---|
pending | Invoice has routing instructions but settlement has not triggered routing yet. |
processing | PayChain is creating withdrawal legs. |
completed | All routing legs completed. |
failed | Routing setup failed or all created legs failed. |
cancelled | Routing was cancelled before execution. |
Gas-blocked state
Gas-blocked means PayChain can see the payment or operation, but an eligible sponsored outbound action is paused because gas credits are insufficient.
Inbound payment detection does not stop when gas credits run out. Sponsored outbound actions may pause, including:
- Automatic settlement.
- Sponsored withdrawals.
- Payout route withdrawal legs.
- Dynamic payout recipient withdrawal legs.
- Contract execution where PayChain sponsors network cost.
Status handling rules
- Treat unknown statuses as non-final.
- Make fulfillment idempotent.
- Store PayChain IDs and your own order references together.
- Fetch the resource after webhook verification.
- Do not assume a transaction hash alone means the invoice is payable or fulfilled.