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 with beneficiary details, approval safety, and idempotent client_ref.
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": "PO1785632845",
    "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 Check final or current transaction state using your own client_ref.
GET https://api.zepay.money/api/v1/transactions/{client_ref}

Transaction Status

Check transaction status with your client_ref.

No body required
{
    "success": true,
    "code": "TXN",
    "message": "Transaction Status Found",
    "data": {
        "status": "success",
        "txnid": "SYSTEM_TXN_ID",
        "refno": "OPERATOR_REF"
    }
}