Pool Settlement

​

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

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

​

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

curl https://api.stablepay.global/v2/escrow/balance \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "success": true,
  "data": { "usdt": "0.00", "inr": "842500.00" }
}

​

Disburse INR

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"
  }'

{
  "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".

​

Prerequisites

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

​

Webhook Sequence

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

​

FAQ