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

# Transaction Lifecycle

> Understanding transaction states and transitions

## How Payout Works

| Type              | Steps         | Payout                                                                                                  |
| ----------------- | ------------- | ------------------------------------------------------------------------------------------------------- |
| `sell`            | 1 API call    | **Automatic** — INR is sent as soon as the deposit is confirmed on-chain. No second call needed.        |
| `pool_settlement` | 2 API calls   | **You trigger it** — after the sweep is confirmed, call `POST /transactions/:id/payout` to release INR. |
| `buy`             | *Coming soon* | —                                                                                                       |

***

## Sell

User deposits crypto to their wallet address → StablePay detects and confirms → INR payout is **automatic**.

```mermaid theme={null}
sequenceDiagram
    participant User
    participant Merchant
    participant StablePay
    participant Beneficiary

    Merchant->>StablePay: Create Transaction (type: sell)
    StablePay-->>Merchant: depositAddress + quote
    Merchant->>User: Show deposit address
    User->>StablePay: Send USDT to deposit address
    StablePay-->>Merchant: Webhook: deposit_detected
    StablePay-->>Merchant: Webhook: deposit_confirmed
    StablePay->>Beneficiary: INR payout via IMPS
    StablePay-->>Merchant: Webhook: payout_completed (UTR)
```

| Status              | What's happening                                       |
| ------------------- | ------------------------------------------------------ |
| `deposit_pending`   | Waiting for user to send crypto. Quote valid 24h.      |
| `deposit_detected`  | Deposit seen on blockchain. Waiting for confirmations. |
| `deposit_confirmed` | Confirmations met. Payout initiated **automatically**. |
| `payout_processing` | INR bank transfer in progress.                         |
| `completed`         | INR delivered. UTR available.                          |

***

## Pool Settlement

Merchant sweeps USDT from their pool wallet → StablePay confirms sweep → merchant triggers INR payout.

```mermaid theme={null}
sequenceDiagram
    participant Merchant
    participant StablePay
    participant Beneficiary

    Merchant->>StablePay: Create Transaction (type: pool_settlement)
    StablePay->>StablePay: Sweep USDT from pool → settlement wallet
    StablePay-->>Merchant: Webhook: sweep_confirmed
    Merchant->>StablePay: POST /transactions/:id/payout
    StablePay->>Beneficiary: INR payout via IMPS
    StablePay-->>Merchant: Webhook: payout_completed (UTR)
```

| Status              | What's happening                                                                   |
| ------------------- | ---------------------------------------------------------------------------------- |
| `sweep_processing`  | USDT being swept from pool wallet for settlement.                                  |
| `sweep_confirmed`   | Sweep confirmed. **You must call** `POST /transactions/:id/payout` to trigger INR. |
| `payout_processing` | INR bank transfer in progress.                                                     |
| `completed`         | INR delivered. UTR available.                                                      |

***

## Buy (Onramp) — *Coming soon*

User pays fiat and receives stablecoins in their wallet. Contact us for early access.

***

## Error States

| Status         | What happened         | What to do                                        |
| -------------- | --------------------- | ------------------------------------------------- |
| `failed`       | Bank transfer failed  | Auto-retries up to 3x, then our team investigates |
| `cancelled`    | Partner cancelled     | Create a new transaction                          |
| `expired`      | No deposit in 24h     | Create a new transaction for fresh quote          |
| `sweep_failed` | Sweep failed on-chain | Funds safe in pool. Retry with new transaction    |

***

## Confirmation Times

| Network  | Confirmations | Time     |
| -------- | ------------- | -------- |
| Polygon  | 20            | \~1 min  |
| Ethereum | 12            | \~3 min  |
| Arbitrum | 20            | \~30 sec |
| Base     | 20            | \~30 sec |
| Tron     | 19            | \~1 min  |

***

## Webhooks

| Event                           | When                              |
| ------------------------------- | --------------------------------- |
| `transaction.created`           | Transaction created               |
| `transaction.deposit_detected`  | Crypto deposit seen on blockchain |
| `transaction.deposit_confirmed` | Required confirmations met        |
| `transaction.sweep_confirmed`   | Pool sweep confirmed on-chain     |
| `transaction.sweep_failed`      | Pool sweep failed                 |
| `transaction.payout_initiated`  | INR bank transfer started         |
| `transaction.payout_completed`  | INR delivered, UTR available      |
| `transaction.payout_failed`     | Bank transfer failed              |

See the [Webhooks guide](/guides/webhooks) for payload format and signature verification.

***

## Polling

```bash theme={null}
curl https://api.stablepay.global/v2/transactions/{transactionId} \
  -H "Authorization: Bearer YOUR_API_KEY"
```