Payouts · Payout Requests

Request Payout

Ask for money from your payout wallet to be sent to your bank account.

POST request

URL: https://uat-api.vizodigital.com/api/v1/payouts

Body

{
    "reference_id": "PO2026101400001",
    "bank_account_id": 12,
    "amount": 1000
}

Include a valid Bearer token with every request

Code sample

curl -X POST "https://uat-api.vizodigital.com/api/v1/payouts" \
  -H "X-API-Key: YOUR_API_KEY_OR_TOKEN" \
  -H "X-Timestamp: $(TZ=Asia/Kolkata date '+%Y-%m-%d %H:%M:%S')" \
  -H "Content-Type: application/json" \
  -d '{
    "reference_id": "PO2026101400001",
    "bank_account_id": 12,
    "amount": 1000
}'

Success Response

{
    "status": "success",
    "message": "Payout requested. The amount is held until it is paid, rejected or cancelled.",
    "data": {
        "reference_id": "PO2026101400001",
        "amount": "1000.00",
        "fee": "10.00",
        "net_amount": "990.00",
        "status": "pending",
        "bank_account": {
            "id": 12,
            "account_last4": "0000"
        },
        "utr": null,
        "reject_reason": null,
        "created_at": "2026-10-14T11:20:00+05:30",
        "processed_at": null
    }
}

Failure response

{
    "status": "error",
    "code": "insufficient_payout_balance",
    "message": "Your payout wallet balance is too low for this amount."
}

Overview

Takes the amount from your payout wallet now and opens a payout with status: pending. We then send the money by bank transfer.

What happens next

paid: the money was sent. utr is the bank reference.
rejected: we could not pay. reject_reason says why, and the amount is back in your payout wallet.
cancelled: you cancelled it, and the amount is back in your payout wallet.

Notes

The bank account must be approved.
The amount must be at least the minimum, more than the fee, and at most your payout_balance. At most 2 decimals. See Payout Balance.
net_amount is amount minus fee. It is what reaches your bank.
You may have more than one pending payout.
Send a new reference_id for every payout. A repeated one is refused with 409 duplicate_reference_id and no money is taken, so it is safe to retry after a timeout with the same reference_id.

Testing in UAT With a UAT key no money moves. The sample payout balance is 25,000.00: an amount above it is refused with 402 insufficient_payout_balance. A reference_id starting with PAID- comes back paid with a sample UTR. One starting with FAIL- comes back rejected with a sample reject_reason. Any other reference_id stays pending until you cancel it.

Headers

X-API-Key · string required

Your credential: either your `rr_live_` API key, or the Bearer token from `POST /api/v1/auth/client-credentials` (the same token every other API uses). The token may instead be sent as `Authorization: Bearer <token>`. A token follows the same IP whitelist as your keys, and all your tokens share one requests-per-minute allowance.

Example: rr_live_xxxxxxxxxxxxx
X-Timestamp · string required

Current time in IST as `YYYY-MM-DD HH:MM:SS` (or `YYYY-MM-DDTHH:MM:SS`). Do not add a timezone suffix such as `+05:30`. Must be within 15 seconds of our server time.

Example: 2026-10-03 10:30:45
Content-Type · string required

Request content type.

Example: application/json

Body

application/json required

Request Payout request body

Schema

{
    "type": "object",
    "required": [
        "reference_id",
        "bank_account_id",
        "amount"
    ],
    "properties": {
        "reference_id": {
            "type": "string",
            "description": "Your own unique id for this payout. Letters, digits, `_` and `-`. Max 40 characters. Not `balance`, `transfers` or `bank-accounts`."
        },
        "bank_account_id": {
            "type": "integer",
            "description": "The `id` of an approved bank account."
        },
        "amount": {
            "type": "number",
            "description": "Rupees to pay out, at most 2 decimals."
        }
    }
}

Example

{
    "reference_id": "PO2026101400001",
    "bank_account_id": 12,
    "amount": 1000
}

Responses

201 · application/json default

Success

Example

{
    "status": "success",
    "message": "Payout requested. The amount is held until it is paid, rejected or cancelled.",
    "data": {
        "reference_id": "PO2026101400001",
        "amount": "1000.00",
        "fee": "10.00",
        "net_amount": "990.00",
        "status": "pending",
        "bank_account": {
            "id": 12,
            "account_last4": "0000"
        },
        "utr": null,
        "reject_reason": null,
        "created_at": "2026-10-14T11:20:00+05:30",
        "processed_at": null
    }
}

402 · application/json

Failed or rejected

Example

{
    "status": "error",
    "code": "insufficient_payout_balance",
    "message": "Your payout wallet balance is too low for this amount."
}

Errors

INVALID_API_KEY · HTTP 401

Invalid or revoked API key.
```
{
    "message": "Invalid or revoked API key."
}
```
TIMESTAMP_OUT_OF_RANGE · HTTP 400

Request timestamp is outside the ±15 second window.
```
{
    "message": "Request timestamp is outside the ±15 second window."
}
```
RATE_LIMITED · HTTP 429

Rate limit exceeded.
```
{
    "message": "Rate limit exceeded."
}
```

insufficient_payout_balance · HTTP 402

Your payout wallet balance is too low for this amount.

{
    "status": "error",
    "code": "insufficient_payout_balance",
    "message": "Your payout wallet balance is too low for this amount."
}

bank_account_not_found · HTTP 404

Bank account not found.

{
    "status": "error",
    "code": "bank_account_not_found",
    "message": "Bank account not found."
}

duplicate_reference_id · HTTP 409

This reference_id was already used. Send a new one.

{
    "status": "error",
    "code": "duplicate_reference_id",
    "message": "This reference_id was already used. Send a new one."
}

bank_account_not_approved · HTTP 422

This bank account is not approved yet, or was removed.

{
    "status": "error",
    "code": "bank_account_not_approved",
    "message": "This bank account is not approved yet, or was removed."
}

amount_below_minimum · HTTP 422

The smallest payout is Rs 100.00.

{
    "status": "error",
    "code": "amount_below_minimum",
    "message": "The smallest payout is Rs 100.00."
}

amount_not_above_fee · HTTP 422

The amount must be more than the payout fee of Rs 10.00.

{
    "status": "error",
    "code": "amount_not_above_fee",
    "message": "The amount must be more than the payout fee of Rs 10.00."
}

Rate Limits

100/min