AEPS · Agents

Onboard Agent

POST request

URL: https://uat-api.vizodigital.com/api/v1/aeps/agents

Body

{
    "channel": "APP",
    "ip_address": "49.47.133.99",
    "first_name": "Ramesh",
    "middle_name": "",
    "last_name": "Patel",
    "mobile_number": "9876543210",
    "email": "ramesh.patel@example.com",
    "pan_number": "ABCDE1234F",
    "aadhaar_number": "123456789012",
    "dob": "1990-05-15",
    "agent_code": "AC12345678",
    "agent_address": "C 101, Mansarovar, Jaipur",
    "agent_state_code": "RJ",
    "agent_city": "Jaipur",
    "agent_pin_code": "302006",
    "agent_bank_name": "ICICI Bank",
    "agent_bank_account_number": "001201601800000",
    "agent_bank_ifsc": "ICIC0000012",
    "shop_name": "Patel Communication",
    "shop_address": "Shop No 5, New Sanganer Road, Jaipur",
    "shop_state_code": "RJ",
    "shop_city": "Jaipur",
    "shop_pin_code": "302006",
    "shop_latitude": "26.9124",
    "shop_longitude": "75.7873",
    "is_physically_verified": true
}

Include a valid Bearer token with every request

Code sample

curl -X POST "https://uat-api.vizodigital.com/api/v1/aeps/agents" \
  -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 '{
    "channel": "APP",
    "ip_address": "49.47.133.99",
    "first_name": "Ramesh",
    "middle_name": "",
    "last_name": "Patel",
    "mobile_number": "9876543210",
    "email": "ramesh.patel@example.com",
    "pan_number": "ABCDE1234F",
    "aadhaar_number": "123456789012",
    "dob": "1990-05-15",
    "agent_code": "AC12345678",
    "agent_address": "C 101, Mansarovar, Jaipur",
    "agent_state_code": "RJ",
    "agent_city": "Jaipur",
    "agent_pin_code": "302006",
    "agent_bank_name": "ICICI Bank",
    "agent_bank_account_number": "001201601800000",
    "agent_bank_ifsc": "ICIC0000012",
    "shop_name": "Patel Communication",
    "shop_address": "Shop No 5, New Sanganer Road, Jaipur",
    "shop_state_code": "RJ",
    "shop_city": "Jaipur",
    "shop_pin_code": "302006",
    "shop_latitude": "26.9124",
    "shop_longitude": "75.7873",
    "is_physically_verified": true
}'

Success Response

{
    "status": "success",
    "message": "Agent onboarded successfully.",
    "data": {
        "agent_code": "AC12345678",
        "kyc_status": "pending",
        "created_at": "2026-10-02T10:30:45+05:30"
    }
}

Failure response

{
    "status": "error",
    "code": "provider_rejected",
    "message": "Invalid PAN number"
}

Overview

AEPS flow

Onboard Agent — one time per agent.
Agent Status — call before every session to see what is pending.
Agent KYC — one-time biometric KYC, when kyc_required is true.
Daily 2FA — once per day, when daily_2fa_required is true.
Generate OTP — only for cash withdrawals at or above otp_amount.
Transaction — cash withdrawal, balance enquiry or mini statement.
Transaction Status — confirm the final result.

Notes

AEPS is enabled per account. Contact us to activate it.
All steps are live. Sandbox keys give made-up answers and never move money.
Each agent_code can be used once per account and environment. A repeated one is refused with agent_code_taken.
Sandbox (UAT) keys never reach the bank network.
agent_code is your own unique ID for the agent (max 10 letters/digits). You use it in all later calls.
Send every field. For an optional field with no value, send an empty string.

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

Onboard Agent request body

Schema

{
    "type": "object",
    "required": [
        "channel",
        "ip_address",
        "first_name",
        "mobile_number",
        "email",
        "pan_number",
        "aadhaar_number",
        "dob",
        "agent_code",
        "agent_address",
        "agent_state_code",
        "agent_city",
        "agent_pin_code",
        "agent_bank_name",
        "agent_bank_account_number",
        "agent_bank_ifsc",
        "shop_name",
        "shop_address",
        "shop_state_code",
        "shop_city",
        "shop_pin_code",
        "shop_latitude",
        "shop_longitude",
        "is_physically_verified"
    ],
    "properties": {
        "channel": {
            "type": "string",
            "enum": [
                "APP",
                "WEB"
            ],
            "description": "Where the request comes from."
        },
        "ip_address": {
            "type": "string",
            "description": "Public IPv4 address of the agent device."
        },
        "first_name": {
            "type": "string",
            "description": "Letters and spaces only, max 50 characters."
        },
        "middle_name": {
            "type": "string",
            "description": "Optional. Send `\"\"` if none."
        },
        "last_name": {
            "type": "string",
            "description": "Optional. Send `\"\"` if none."
        },
        "mobile_number": {
            "type": "string",
            "description": "10-digit mobile number."
        },
        "email": {
            "type": "string",
            "description": "Agent email address."
        },
        "pan_number": {
            "type": "string",
            "description": "Agent PAN."
        },
        "aadhaar_number": {
            "type": "string",
            "description": "12-digit Aadhaar number."
        },
        "dob": {
            "type": "string",
            "description": "Date of birth, `YYYY-MM-DD`."
        },
        "agent_code": {
            "type": "string",
            "description": "Your unique ID for this agent, max 10 letters/digits."
        },
        "agent_address": {
            "type": "string",
            "description": "Home address, max 250 characters."
        },
        "agent_state_code": {
            "type": "string",
            "description": "2-letter state code, e.g. `RJ`, `BR`, `DL`."
        },
        "agent_city": {
            "type": "string"
        },
        "agent_pin_code": {
            "type": "string",
            "description": "6-digit PIN code."
        },
        "agent_bank_name": {
            "type": "string"
        },
        "agent_bank_account_number": {
            "type": "string"
        },
        "agent_bank_ifsc": {
            "type": "string"
        },
        "shop_name": {
            "type": "string",
            "description": "Max 100 characters."
        },
        "shop_address": {
            "type": "string",
            "description": "Max 250 characters."
        },
        "shop_state_code": {
            "type": "string",
            "description": "2-letter state code."
        },
        "shop_city": {
            "type": "string"
        },
        "shop_pin_code": {
            "type": "string",
            "description": "6-digit PIN code."
        },
        "shop_latitude": {
            "type": "string",
            "description": "Exactly 4 decimal places."
        },
        "shop_longitude": {
            "type": "string",
            "description": "Exactly 4 decimal places."
        },
        "is_physically_verified": {
            "type": "boolean",
            "description": "Whether you physically verified the shop."
        }
    }
}

Example

{
    "channel": "APP",
    "ip_address": "49.47.133.99",
    "first_name": "Ramesh",
    "middle_name": "",
    "last_name": "Patel",
    "mobile_number": "9876543210",
    "email": "ramesh.patel@example.com",
    "pan_number": "ABCDE1234F",
    "aadhaar_number": "123456789012",
    "dob": "1990-05-15",
    "agent_code": "AC12345678",
    "agent_address": "C 101, Mansarovar, Jaipur",
    "agent_state_code": "RJ",
    "agent_city": "Jaipur",
    "agent_pin_code": "302006",
    "agent_bank_name": "ICICI Bank",
    "agent_bank_account_number": "001201601800000",
    "agent_bank_ifsc": "ICIC0000012",
    "shop_name": "Patel Communication",
    "shop_address": "Shop No 5, New Sanganer Road, Jaipur",
    "shop_state_code": "RJ",
    "shop_city": "Jaipur",
    "shop_pin_code": "302006",
    "shop_latitude": "26.9124",
    "shop_longitude": "75.7873",
    "is_physically_verified": true
}

Responses

201 · application/json default

Success

Example

{
    "status": "success",
    "message": "Agent onboarded successfully.",
    "data": {
        "agent_code": "AC12345678",
        "kyc_status": "pending",
        "created_at": "2026-10-02T10:30:45+05:30"
    }
}

422 · application/json

Failed or rejected

Example

{
    "status": "error",
    "code": "provider_rejected",
    "message": "Invalid PAN number"
}

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."
}
```

service_not_enabled · HTTP 403

AEPS is not enabled for your account. Contact your account manager to activate it.

{
    "status": "error",
    "code": "service_not_enabled",
    "message": "AEPS is not enabled for your account. Contact your account manager to activate it."
}

RATE_LIMITED · HTTP 429

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

agent_code_taken · HTTP 409

You already have an agent with this agent_code.

{
    "status": "error",
    "code": "agent_code_taken",
    "message": "You already have an agent with this agent_code."
}

agent_limit_reached · HTTP 403

You have reached your limit of 10 agents.

{
    "status": "error",
    "code": "agent_limit_reached",
    "message": "You have reached your limit of 10 agents."
}

provider_rejected · HTTP 422

The bank network refused the request. The message says why.

{
    "status": "error",
    "code": "provider_rejected",
    "message": "The bank network refused the request. The message says why."
}

provider_unavailable · HTTP 502

The AEPS provider did not respond. Try again shortly.

{
    "status": "error",
    "code": "provider_unavailable",
    "message": "The AEPS provider did not respond. Try again shortly."
}

noble_credentials_unavailable · HTTP 503

Provider credentials are not available. Contact your partner.

{
    "status": "error",
    "code": "noble_credentials_unavailable",
    "message": "Provider credentials are not available. Contact your partner."
}

Rate Limits

100/min