# 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.

{% hint style="info" %}
**Developer note:** For SDK/API examples across fixed amount invoices, auto-detected payments, payout routes, dynamic payout recipients, and programmatic withdrawals, see Payment flows.
{% endhint %}

### 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

1. Create or find a customer.
2. Create an invoice with `amount`, `token`, `chain`, `networkId`, and your own order metadata.
3. Show the hosted invoice link or render the payment address in your own checkout.
4. Wait for PayChain to detect and confirm the transfer.
5. Verify the webhook signature with the raw request body.
6. Fetch the canonical invoice.
7. Fulfill the order only after the canonical invoice is `paid` or `overpaid`.
8. 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.
* 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.

#### What PayChain does

1. Watches supported customer deposit addresses.
2. Ignores non-positive observations.
3. Ignores internal operational transfers.
4. Applies auto-invoice minimum and dust thresholds.
5. Creates an auto-generated invoice for a qualifying deposit.
6. 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.    |

{% hint style="warning" %}
**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.
{% endhint %}

### 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.                                         |

Settlement rules can differ by network. Your integration should consume invoice status, not guess finality from a block explorer.

### 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.

{% hint style="warning" %}
**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.
{% endhint %}

### Withdraw funds

Withdrawals move business treasury funds to an external destination. Dashboard withdrawals are operator-driven; payout API withdrawals are backend-driven.

#### Withdrawal lifecycle

1. Quote the withdrawal.
2. Review amount, token, network, fee, and destination.
3. Create the withdrawal with a payout API key or dashboard action.
4. PayChain queues and processes the transfer.
5. PayChain submits the network transaction where applicable.
6. PayChain sends withdrawal webhooks as the status changes.

#### Edge cases

| Case                          | Meaning                                                        | Operator action                      |
| ----------------------------- | -------------------------------------------------------------- | ------------------------------------ |
| Insufficient balance          | Treasury funds are not available for the requested amount.     | Lower amount or wait for settlement. |
| 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.

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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.paychainhq.io/paychainhq-documentation-page/dashboard-guides/workflow-guides.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.