Vizo Digital Api
Sign in
guide

AEPS Express Integration Guide

This guide explains how to integrate the high-speed AEPS Express switch on Vizodigital API, featuring instant processing, real-time status queries, and exclusive Cash Deposit capability.

1. Before you start

  • Your developer account must have AEPS enabled.
  • Send Authorization: Bearer {token} or X-API-Key on every call.
  • Always send Accept: application/json and Content-Type: application/json.
  • Ensure your server's public IPv4 address is whitelisted in your developer portal.
  • Real money moves on Production. Test cash withdrawals with a small amount such as ₹100.

2. Headers and rules on every call

Rule Detail
X-Timestamp header Current India time (IST) as YYYY-MM-DD HH:MM:SS (within 15 seconds of server time).
IP whitelist Calls must originate from your whitelisted server IP address.
reference_id Your unique reference per request. Letters, digits, _ and - only, max 40 characters.
Location latitude and longitude of the agent, exactly 4 decimal places, inside India.
Device fields channel (APP or WEB), device_id, ip_address, user_agent.

3. AEPS Express Lifecycle & Endpoints

Integrate the complete merchant lifecycle and transactions in 9 clear steps:

  1. Step 1: Outlet Min-KYC Signup (POST /api/v1/aeps-express/outlet/signup)
    • Registers the merchant profile with PAN, Aadhaar, Shop info, and automatically links the settlement bank account.
  2. Step 2: Send Registration OTP (POST /api/v1/aeps-express/outlet/send-otp)
    • Dispatches a mobile verification OTP to the merchant's registered phone.
  3. Step 3: Verify Registration OTP (POST /api/v1/aeps-express/outlet/verify-otp)
    • Submits the OTP to complete merchant mobile validation.
  4. Step 4: Outlet Status & WADH (GET /api/v1/aeps-express/agents/{agent_code})
    • Check kyc_required, fetch device kyc_wadh hashes for biometric capture, and verify daily_2fa_required.
  5. Step 5: Outlet Biometric eKYC (POST /api/v1/aeps-express/agents/{agent_code}/kyc)
    • One-time biometric eKYC using the matching kyc_wadh from Outlet Status.
  6. Step 6: Daily 2FA Login (POST /api/v1/aeps-express/agents/{agent_code}/daily-2fa)
    • Mandatory daily biometric merchant login (valid till 23:59:59 IST).
  7. Step 7: List Supported Banks (GET /api/v1/aeps-express/banks)
    • Fetch the active bank list and 6-digit bank_iin codes.
  8. Step 8: Customer AEPS Transactions:
    • POST /api/v1/aeps-express/balance-inquiry — Balance Enquiry (BE)
    • POST /api/v1/aeps-express/mini-statement — Mini Statement (MS)
    • POST /api/v1/aeps-express/cash-withdrawal — Cash Withdrawal (CW: ₹100 - ₹10,000)
    • POST /api/v1/aeps-express/cash-deposit — Cash Deposit (CD: InstantPay Exclusive)
    • POST /api/v1/aeps-express/otp — Generate High-Value CW OTP (₹5,001+ on off-us banks)
    • POST /api/v1/aeps-express/transactions — Unified transaction endpoint
  9. Step 9: Real-time Transaction Status (GET /api/v1/aeps-express/transactions/{reference_id})
    • Query transaction status in real-time with RRN and settlement status.

Optional Management Endpoint:

  • Update Settlement Bank Account (POST /api/v1/aeps-express/outlet/bank-account) — Update settlement bank details later. (Note: Bank details are already auto-linked in Step 1).
  • Quick Onboard Outlet (POST /api/v1/aeps-express/agents) — Single-call signup alias.

4. Capturing Biometrics (RD Service)

Send bio_type:

  • 0 or FMR = Fingerprint
  • 1 or FIR = Face
  • 2 or IIR = Iris

Capture the PID block from your registered device (Mantra, Morpho, Startek, etc.), base64-encode the complete <PidData>...</PidData> XML string, and pass it in pid_data.

Rules for the wadh value in the PID options:

Call wadh
Outlet Biometric eKYC Use the matching kyc_wadh value from Outlet Status
Daily 2FA Login Empty
Transactions (CW, CD, BE, MS) Empty

5. Supported Transaction Types on AEPS Express

  • CW — Cash Withdrawal (amount required, limits ₹100 - ₹10,000)
  • CD — Cash Deposit (amount required - AEPS Express exclusive feature!)
  • BE — Balance Enquiry (amount null)
  • MS — Mini Statement (amount null, returns recent transactions)

6. Testing in UAT / Sandbox

  • Sandbox keys never reach the real bank network and never move money.
  • Send a reference_id starting with FAIL- to simulate a failed answer.
  • Send a reference_id starting with PEND- to simulate a 202 pending response, then verify with Transaction Status.