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

# Pool Settlement

> Fund an INR escrow balance from USDT, then disburse to your users

Pool settlement lets you send USDT into a central pool, have it converted to an INR balance held in your escrow, and then disburse INR to any of your verified users on demand — without managing per-user wallets.

## When to Use Pool Settlement

* You want to manage liquidity centrally (one pool instead of many wallets)
* You pre-fund with USDT and disburse INR on demand
* You want to control exactly when INR payouts happen

## Setup

Pool settlement requires a linked pool wallet on your account. Contact support to:

1. Set up your pool wallet
2. Get deposit addresses for each supported chain (Tron, Polygon, Ethereum)
3. Enable pool settlement on your account

Once enabled, you'll see your deposit addresses in the **Client Portal** under Pool Wallet.

## How It Works

1. **Load your pool** — Send USDT to your pool wallet deposit address on any supported chain.
2. **We sweep and convert** — StablePay sweeps the USDT and converts it to INR at the agreed deal rate, crediting your **INR escrow balance**. This is handled by StablePay operations; the INR appears on your balance once allocated.
3. **Check your balance** — Call `GET /v2/escrow/balance` to see your available INR before disbursing (also visible in the Client Portal).
4. **Disburse** — `POST /v2/transactions` with `type: "pool_settlement"` and `amountInr`. A **single call** debits your INR escrow, applies TDS if enabled, and pays the net to the user's verified bank account over IMPS.
5. **Payout completes** — You receive a `transaction.payout_completed` webhook with the UTR.

## Check Your INR Escrow Balance

The same balance shown in the Client Portal is available over the API, so you can confirm funds before disbursing:

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

```json theme={null}
{
  "success": true,
  "data": { "usdt": "0.00", "inr": "842500.00" }
}
```

`inr` is your available, withdrawable escrow balance — the amount you can disburse. Use `GET /v2/escrow/statement` for a paginated ledger of every credit and debit.

## Disburse INR

```bash theme={null}
curl -X POST https://api.stablepay.global/v2/transactions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "type": "pool_settlement",
    "userId": "usr_abc123",
    "amountInr": "100000",
    "partnerReference": "disbursal_789"
  }'
```

```json theme={null}
{
  "success": true,
  "data": {
    "transactionId": "tx-uuid",
    "type": "pool_settlement",
    "status": "payout_processing",
    "amountInr": "100000.00",
    "settlementInr": "99000.00",
    "tds": { "applicable": true, "percent": "1", "amountInr": "1000.00" },
    "recipient": { "bank": "HDFC Bank", "account": "XXXXXX7890", "name": "RAHUL KUMAR" },
    "payout": { "status": "processing", "amountInr": "99000.00", "rail": "imps" }
  }
}
```

* `amountInr` is the **gross** debited from your escrow; `settlementInr` is the **net** the user receives (gross − TDS). With TDS disabled the two are equal.
* **Single call** — the payout is initiated immediately. There is no separate step.
* `type: "payout"` is an accepted alias for `type: "pool_settlement"`.

<Note>
  A `200` means the bank rail **accepted** the transfer, not that it settled. Treat `transaction.payout_completed` / `transaction.payout_failed` as the source of truth.
</Note>

## Prerequisites

Before disbursing, ensure:

* **Your INR escrow balance covers the gross `amountInr`.** Checked at creation and again atomically at settlement (`INSUFFICIENT_BALANCE`).
* **User exists** and belongs to your account.
* **User has a verified bank account** linked. Always required (`NO_BANK_ACCOUNT`).
* **User KYC is verified** — enforced when identity KYC is enabled on your account (`KYC_INCOMPLETE`). See [KYC Flow](/guides/kyc-flow).

## Webhook Sequence

A successful disbursal fires, in order:

1. `transaction.created` — the disbursal was accepted
2. `transaction.payout_initiated` — the bank rail accepted the transfer
3. `transaction.payout_completed` — INR delivered, carries the UTR (or `transaction.payout_failed`)

## Idempotency & Retries

* **`Idempotency-Key` header** (required on `POST /v2/transactions`) caches the full response — a retried request returns the original result, never a second disbursal.
* **`partnerReference`** (optional) is a business-level guard: reusing one returns the original payout with `idempotentReplayed: true`.
* **No auto-retry.** A definitive provider failure reverses the escrow debit and marks the transaction `failed`. An indeterminate response leaves it `processing` for a background reconciler to resolve.
* **Bank-accepted-without-UTR.** Occasionally the bank accepts a transfer without immediately returning a UTR. The payout is held as `processing` — **not** marked completed — until it resolves: you then receive `transaction.payout_completed` with the UTR, or `transaction.payout_failed` with the escrow debit reversed.

## Supported Chains

| Chain    | Asset              | Deposit Address Format |
| -------- | ------------------ | ---------------------- |
| Tron     | USDT (TRC-20)      | `T...`                 |
| Polygon  | USDT/USDC (ERC-20) | `0x...`                |
| Ethereum | USDT/USDC (ERC-20) | `0x...`                |
| Arbitrum | USDT/USDC (ERC-20) | `0x...`                |
| Base     | USDC (ERC-20)      | `0x...`                |

## FAQ

**How long does the USDT → INR conversion take?**
The sweep is typically 1–5 minutes; INR is credited to your escrow once allocated at the deal rate.

**When does my INR balance appear?**
After StablePay allocates it. It is not credited automatically on sweep — check `GET /v2/escrow/balance`.

**What if the INR payout fails?**
The transaction moves to `failed` and you receive `transaction.payout_failed`. The escrow debit is **reversed**, so your balance is restored. Retry with a new `partnerReference`.

**Which rail is used?**
Always IMPS. Payouts are capped at ₹5,00,000 per transaction.

**Is TDS deducted?**
When enabled on your account, TDS (§194S) is withheld from the gross `amountInr`; the user receives `settlementInr`. TDS does not apply to withdrawing your own escrow balance.