ZEPAY
Secure API v1

Postman Style API Documentation

Use Bearer token authentication. Generate your token from Callback & Token, then call these endpoints from your approved server IP.

Base URL https://api.zepay.money/api/v1
Required Header Authorization: Bearer YOUR_API_TOKEN Accept: application/json Content-Type: application/json
Payout Security Single request body New beneficiary auto-submits for approval client_ref is unique/idempotent Token is IP whitelisted Only your own approved beneficiary can be paid
Webhook / Callback Secure Transaction Callback Add your HTTPS callback URL from Callback & Token. ZEPAY sends transaction updates by POST JSON for Payout. 
{
    "Content-Type": "application/json",
    "User-Agent": "ZEPAY-Callback/1.0",
    "X-Zepay-Event": "transaction.updated",
    "X-Zepay-Timestamp": "1779012345",
    "X-Zepay-Signature": "HMAC_SHA256_SIGNATURE",
    "X-Zepay-Signature-Algo": "HMAC-SHA256"
}
{
    "event": "transaction.updated",
    "product": "payout",
    "status": "success",
    "client_ref": "PO123456789",
    "txnid": "SYSTEM_TXN_ID",
    "refno": "BANK_RRN",
    "amount": 1000,
    "charge": 5,
    "gst": 0.9,
    "tds": 0,
    "balance": 9500,
    "message": "Transaction Successfull",
    "timestamp": "2026-05-17T03:30:00+05:30"
}
signature = hash_hmac('sha256', timestamp + '.' + raw_json_body, YOUR_ACTIVE_API_TOKEN)
Method: POST Body: raw JSON Verify X-Zepay-Signature before processing Return HTTP 200 after receiving callback
Applies to all secure v1 APIs Common Security Responses Every endpoint is protected by Bearer token, IP whitelist, active API user, and token status checks.
Missing token HTTP 401 
{
    "http_status": 401,
    "success": false,
    "code": "AUTH_TOKEN_MISSING",
    "message": "Authorization Bearer token is required."
}
Invalid token HTTP 401 
{
    "http_status": 401,
    "success": false,
    "code": "AUTH_TOKEN_INVALID",
    "message": "Invalid API token."
}
IP not allowed HTTP 403 
{
    "http_status": 403,
    "success": false,
    "code": "IP_NOT_ALLOWED",
    "message": "Request IP is not allowed for this API token."
}
Token inactive HTTP 403 
{
    "http_status": 403,
    "success": false,
    "code": "IP_INACTIVE",
    "message": "Please contact ZEPAY. Your API IP is inactive."
}
Invalid API user HTTP 403 
{
    "http_status": 403,
    "success": false,
    "code": "API_USER_INVALID",
    "message": "API user is not valid."
}
Account blocked HTTP 403 
{
    "http_status": 403,
    "success": false,
    "code": "ACCOUNT_BLOCKED",
    "message": "API user account is blocked."
}
2 endpoints Getting Started & Wallet Token setup, request IP check, and wallet balance.
GET https://api.zepay.money/api/v1/ip

Check Request IP

Use this before token generation to confirm your server IP.

No body required
{
    "success": true,
    "code": "TXN",
    "message": "IP fetched successfully.",
    "data": {
        "ip": "127.0.0.1"
    }
}
GET https://api.zepay.money/api/v1/wallet/balance

Wallet Balance

Fetch API user main wallet balance.

No body required
{
    "success": true,
    "code": "TXN",
    "message": "Balance fetched successfully.",
    "data": {
        "main_wallet": 1000
    }
}
1 endpoints Payout API Single-body bank payout API. Save txnid from the response; use it with Status API.
POST https://api.zepay.money/api/v1/payout

Create Payout

Secure single-body payout API. Send beneficiary bank details and payout details in one protected request. If beneficiary is new, it is created for approval and the same request can be retried after approval.

{
    "client_ref": "PO1793428133",
    "amount": 1000,
    "mode": "IMPS",
    "remark": "Vendor settlement",
    "beneficiary": {
        "name": "Receiver Name",
        "account": "1234567890",
        "ifsc": "IFSC0000001",
        "bank": "BANK NAME"
    }
}
Success HTTP 200 
{
    "http_status": 200,
    "success": true,
    "code": "TXN",
    "message": "Transaction Successfull",
    "data": {
        "statuscode": "TXN",
        "txnid": "SYSTEM_TXN_ID",
        "beneficiary": {
            "beneficiary_id": 12,
            "account": "XXXXXX7890"
        }
    }
}
New beneficiary approval required HTTP 202 
{
    "http_status": 202,
    "success": false,
    "code": "BENEFICIARY_APPROVAL_REQUIRED",
    "message": "Beneficiary created and sent for approval. Retry the same payout request after approval.",
    "data": {
        "beneficiary_id": 12,
        "beneficiary_status": "pending",
        "client_ref": "PO123456789",
        "approval_required": true
    }
}
Beneficiary not approved HTTP 403 
{
    "http_status": 403,
    "success": false,
    "code": "BENEFICIARY_NOT_APPROVED",
    "message": "Payout beneficiary is not approved yet.",
    "data": {
        "beneficiary_id": 12,
        "status": "pending"
    }
}
Duplicate client_ref HTTP 409 
{
    "http_status": 409,
    "success": false,
    "code": "DUPLICATE_CLIENT_REF",
    "message": "client_ref already exists.",
    "data": []
}
Beneficiary limit exceeded HTTP 429 
{
    "http_status": 429,
    "success": false,
    "code": "BENEFICIARY_LIMIT_EXCEEDED",
    "message": "Maximum 5 payout beneficiaries are allowed.",
    "data": []
}
Profile incomplete HTTP 422 
{
    "http_status": 422,
    "success": false,
    "code": "PROFILE_INCOMPLETE",
    "message": "Mobile, email, and address are required before payout.",
    "data": []
}
Payout route unavailable HTTP 422 
{
    "http_status": 422,
    "success": false,
    "code": "PAYOUT_ROUTE_UNAVAILABLE",
    "message": "Payout route is not available for this mode or amount.",
    "data": []
}
Validation error HTTP 422 
{
    "http_status": 422,
    "success": false,
    "code": "VALIDATION_ERROR",
    "message": "The client ref field is required.",
    "data": {
        "errors": {
            "client_ref": [
                "The client ref field is required."
            ]
        }
    }
}
1 endpoints Status API Live bank status through ZEPAY. Send txnid or client_ref. ZEPAY matches your txn and queries Canara; you do not call the bank.
GET https://api.zepay.money/api/v1/transactions/{txnid}

Payout Status (live bank)

Check payout status by ZEPAY txnid (from /payout response) or your client_ref. ZEPAY matches the txn in your account and queries Canara Bank. Do not call Canara directly. Same payout: wait 5 minutes between checks. IMPS is usually final on payout response; NEFT stays pending until bank status is Successful.

GET https://api.zepay.money/api/v1/transactions/SYSTEM_TXN_ID
Authorization: Bearer YOUR_API_TOKEN
Accept: application/json

# SYSTEM_TXN_ID = data.txnid from POST /payout
# or your client_ref (data.client_ref / original client_ref)
No body required
Bank Successful HTTP 200 
{
    "http_status": 200,
    "success": true,
    "code": "STATUS_FOUND",
    "message": "Canara bank status: Successful",
    "data": {
        "status": "complete",
        "refno": "BANK_UTR_OR_REF",
        "txnid": "SYSTEM_TXN_ID",
        "client_ref": "PO123456789",
        "bank_envelope_status": "Successful"
    }
}
Still pending at bank HTTP 200 
{
    "http_status": 200,
    "success": true,
    "code": "STATUS_FOUND",
    "message": "Canara bank status: Pending",
    "data": {
        "status": "pending",
        "txnid": "SYSTEM_TXN_ID",
        "client_ref": "PO123456789",
        "bank_envelope_status": "Pending"
    }
}
Bank failed HTTP 200 
{
    "http_status": 200,
    "success": true,
    "code": "STATUS_FOUND",
    "message": "Canara bank status: Failed",
    "data": {
        "status": "failed",
        "txnid": "SYSTEM_TXN_ID",
        "client_ref": "PO123456789",
        "bank_envelope_status": "Failed"
    }
}
Transaction not found HTTP 404 
{
    "http_status": 404,
    "success": false,
    "code": "TRANSACTION_NOT_FOUND",
    "message": "Transaction not found in ZEPAY. Bank was not contacted.",
    "data": []
}