> ## Documentation Index
> Fetch the complete documentation index at: https://developers.saapay.cm/llms.txt
> Use this file to discover all available pages before exploring further.

# How payments work

> Learn the quote-backed asynchronous payment model used by Saapay Business.

Saapay Business payment flows are quote-backed and asynchronous.

You first create a quote to lock pricing, routing, fees, FX, and amounts. Then you create the payment resource with that active quote. The create response usually returns a pending status, while the final status arrives later through webhooks or a `GET` endpoint.

## Single-leg payin or payout

```mermaid theme={"system"}
sequenceDiagram
    participant Merchant
    participant SaapayAPI
    participant Provider
    participant CustomerPhone

    Merchant->>SaapayAPI: POST /customers
    Merchant->>SaapayAPI: POST /quotes/payin or /quotes/payout
    Merchant->>SaapayAPI: POST /payins or /payouts
    SaapayAPI-->>Merchant: 201 pending
    SaapayAPI->>Provider: Async submission
    Provider->>CustomerPhone: Prompt or rail action
    Provider-->>SaapayAPI: Status callback
    SaapayAPI-->>Merchant: Webhook event
```

## Two-leg transfer

Transfers collect from a payer first and then disburse to a recipient. Use transfer quotes for cross-border or local two-leg flows where both legs must be tracked together.

## Important behaviors

* Quotes are valid for 15 minutes.
* Payins, payouts, and transfers are asynchronous.
* Final status should be reconciled through webhooks or `GET` endpoints.
* Write requests require `Idempotency-Key` unless the endpoint documentation says otherwise.
* Operator and corridor availability depends on your merchant account routing.