# USDT payouts

## 1. Request a quote

`POST /api/v1/merchant/crypto/payouts/quote`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `amount` | Decimal string | Yes | Positive recipient amount, up to six decimal places |
| `address` | String | Yes | Valid TRON recipient address |

```bash
curl -X POST https://api.niripay.com/api/v1/merchant/crypto/payouts/quote \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount":"200.000000","address":"YOUR_VALID_TRON_RECIPIENT_ADDRESS"}'
```

Replace the placeholder address before using the API. A quote response contains `quote_id`, `provider`, `amount`, `charge`, `total`, `destination`, `expires_at`, `currency`, and `network` under `data`.

The recipient receives the quoted `amount`; the `charge` is additional. Review the quote before submitting it.

## 2. Submit the quote

`POST /api/v1/merchant/crypto/payouts`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `quote_id` | String | Yes | Exact ID from the accepted quote |
| `idempotency_key` | String | Yes | 8–128 letters, digits, dots, underscores, or hyphens |
| `webhook_url` | String | No | Stable callback URL for this payout |

```bash
curl -X POST https://api.niripay.com/api/v1/merchant/crypto/payouts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "quote_id": "QUOTE_ID_FROM_RESPONSE",
    "idempotency_key": "payout-order-123",
    "webhook_url": "https://merchant.example/webhooks/crypto"
  }'
```

## 3. Track the original payout

Persist the returned transaction `id` and inspect its `state`. Query [transaction status](/crypto-transactions/) or process verified crypto callbacks. Request acceptance does not mean the blockchain transfer has completed.

## Retry rules

Reuse the same idempotency key, quote ID, and callback URL for retries of the same payout. A different request under the same key returns a conflict.

If the outcome is unknown, query the original payout; do not create a replacement. Expired or changed quotes need a fresh quote and review before a new, unsubmitted payout is authorized.

## Common errors

| Code | Next action |
| --- | --- |
| `FRAGMENTED_OR_INSUFFICIENT_LIQUIDITY` | Fund one eligible wallet or resolve pending collections |
| `INVALID_KEY` | Use a stable key with the documented format |
| `IDEMPOTENCY_CONFLICT` | Restore the original request values |
| `QUOTE_EXPIRED` / `QUOTE_CHANGED` | Review a fresh quote before initiating a new payout |
| `NOT_FOUND` | Check the quote ID and merchant ownership |