KlyroPay API Documentation

Request Body

{
    "order_id":       "YOUR-ORDER-001",
    "amount":         1000,
    "customer_phone": "9876543210",
    "customer_name":  "Rahul Sharma"
}

Response — 201

{
    "success": true,
    "data": {
        "transaction_id": "8a7f3e2d-9c1b-4f5a-b8e6-d4c2a1f9e7b3",
        "custom_txn_id":  "KRESTAA9MKMEQ5LMV29C2",
        "order_id":       "YOUR-ORDER-001",
        "txn_ref":        "PAYIN-REF-XXXXX",
        "amount":         1000.00,
        "commission":     10.00,
        "intent_url":     "upi://pay?pa=xxxxx&am=1000.00&cu=INR",
        "expires_in":     600,
        "status":         "pending"
    }
}

Showing the Payment to Customer

<script src="https://cdnjs.cloudflare.com/ajax/libs/
qrcodejs/1.0.0/qrcode.min.js"></script>

<div id="qrcode"></div>
<input type="hidden" id="upi-url"
    value="{{ $intentUrl }}">

<script>
new QRCode(document.getElementById('qrcode'), {
    text: document.getElementById('upi-url').value,
    width: 220, height: 220
});
</script>

<!-- Pass via hidden input to avoid
     HTML encoding issues -->
<input type="hidden" id="upi-url"
    value="{{ $intentUrl }}">

<button onclick="
    window.location.href =
    document.getElementById('upi-url').value
">
    Pay with UPI App
</button>

If the transaction is already in a terminal state (success/failed/expired), this returns the stored record instantly. Otherwise it actively re-checks with the payment provider first — safe to use as a polling fallback if you haven't set up webhooks yet.

{
    "success": true,
    "data": {
        "transaction_id":  "KRESTAA9MKMEQ5LMV29C2",
        "internal_txn_id": "8a7f3e2d-9c1b-4f5a-b8e6-d4c2a1f9e7b3",
        "custom_txn_id":   "KRESTAA9MKMEQ5LMV29C2",
        "order_id":        "YOUR-ORDER-001",
        "txn_ref":         "PAYIN-REF-XXXXX",
        "amount":          1000.00,
        "commission":      10.00,
        "utr":             "407241812279",
        "status":          "success",
        "created_at":      "2026-04-30T10:00:00.000000Z"
    }
}

Request Body

{
    "mobile_no":          "9876543210",
    "beneficiary_name":   "Rahul Sharma",
    "account_no":         "1234567890",
    "ifsc":               "SBIN0001234",
    "bank_name":          "State Bank of India",
    "amount":             5000,
    "partner_request_id": "YOUR-UNIQUE-ORDER-ID"
}

Note: transfers are always IMPS — there's no transfer_type field to send; it's handled automatically on our side.

Response — Success

{
    "success": true,
    "message": "Payout transferred successfully.",
    "data": {
        "transaction": {
            "transaction_id":     "KRESTAA9MKMEQ5LMV29C2",
            "internal_txn_id":    "8e6bf7e9-8e19-47f3-affc-88d02f69b86a",
            "custom_txn_id":      "KRESTAA9MKMEQ5LMV29C2",
            "reference_id":       "RKIT-ORDER-OR-UTR-XXXX",
            "partner_request_id": "YOUR-UNIQUE-ORDER-ID",
            "status":             "success",
            "amount":             5000.00,
            "charge":             10.00,
            "net_amount":         5010.00
        }
    }
}

Note: the commission field here is called charge, not commission — a naming quirk specific to this endpoint. Webhooks (below) use commission instead.

Response — Pending

{
    "success": true,
    "message": "Payout is being processed. You will be notified once settled.",
    "data": {
        "transaction": {
            "transaction_id":     "KRESTAA9MKMEQ5LMV29C2",
            "internal_txn_id":    "8e6bf7e9-8e19-47f3-affc-88d02f69b86a",
            "custom_txn_id":      "KRESTAA9MKMEQ5LMV29C2",
            "reference_id":       null,
            "partner_request_id": "YOUR-UNIQUE-ORDER-ID",
            "status":             "pending",
            "amount":             5000.00,
            "charge":             10.00,
            "net_amount":         5010.00
        }
    }
}

Single Transaction

Accepts either your custom_txn_id (KRESTA...) or the internal UUID — both work. There's no dedicated /payout/status/{id} route; this shared endpoint is the way to look up a payout after creation.

Call this first, every time. Tells you if the mobile number is a new or existing remitter, and if existing, returns their beneficiaries + KYC status in one call.

Response — New Mobile Number

{
  "success": true,
  "message": "Remitter Not Found",
  "data": {
    "exists": false,
    "is_verified": false,
    "is_kyc_verified": false,
    "statuscode": "RNF",
    "status": "Remitter Not Found",
    "data": {
      "referenceKey": "mTN2LUVBFvr034...",
      "pidOptionWadh": "E0jzJ/P8UopUHAieZn8CKqS4WPMi5ZSYXgfnlfkWjrc="
    }
  }
}

Response — Already Exists & KYC-Verified

{
  "success": true,
  "message": "Success",
  "data": {
    "exists": true,
    "is_verified": true,
    "is_kyc_verified": true,
    "statuscode": "TXN",
    "status": "Success",
    "data": {
      "mobileNumber": "9998887776",
      "firstName": "Ramesh",
      "lastName": "Kumar",
      "limitAvailable": "24143.00",
      "beneficiaries": [
        {
          "id": "2cbd9684548d5b36335876735d8cee90",
          "name": "Suresh Verma",
          "account": "50100123456789",
          "ifsc": "HDFC0000123",
          "bank": "HDFC BANK",
          "beneficiary_id": "7c1e2f3a-1234-4abc-9def-1234567890ab"
        }
      ],
      "referenceKey": "o6p8y4S/xHSwmh53...",
      "pidOptionWadh": "E0jzJ/P8UopUHAieZn8CKqS4WPMi5ZSYXgfnlfkWjrc="
    }
  }
}

Only when Step 1 returned exists: false. Links the remitter's Aadhaar with the provider and sends an OTP.

Response — OTP Sent

{
  "success": true,
  "message": "OTP Successfully sent",
  "data": {
    "statuscode": "OTP",
    "status": "OTP Successfully sent",
    "data": { "validity": "2026-08-04 00:24:27", "referenceKey": "W69kpF1qSYuLOenm..." }
  }
}

OTP goes to the remitter's mobile — use it in Step 3 immediately, validity is ~15 min.

Response — Already Registered (called by mistake)

{ "success": false, "message": "This customer is already registered — there is no need to register them again. You can continue directly to adding their beneficiary and sending money.", "data": null }

HTTP 422 — blocked before reaching the provider.

Response — Success

{
  "success": true,
  "message": "Mobile validated successfully please proceed for kyc",
  "data": { "success": true, "statuscode": "KYC", "data": { "referenceKey": "74kzm0Db..." } }
}

Requires a real biometric capture from a UIDAI-certified RD Service device (e.g. Mantra MFS110) or AadhaarFaceRD — this data cannot be fabricated, it must come from actual certified capture hardware/software on your end.

biometric_data shape

{
  "ci": "20280813", "hmac": "<from RD Service>", "pidData": "<base64>",
  "ts": "2026-08-04T11:09:59", "dc": "00c7f4af-...", "mi": "MFS110",
  "dpId": "MANTRA.MSIPL", "mc": "<from RD Service>",
  "rdsId": "RENESAS.MANTRA.001", "rdsVer": "1.5.1",
  "Skey": "<from RD Service>", "srno": "9604562"
}

Success unlocks Step 5. This is only needed for brand-new remitters — check is_kyc_verified from Step 1 first.

Needed before Step 5 — resolves a numeric bank_id from an IFSC code or bank name.

{
  "success": true, "message": "OK",
  "data": {
    "query": "HDFC0000123",
    "matches": [ { "bank_id": 11263, "name": "HDFC BANK", "ifsc_alias": "HDFC", "imps": true, "neft": true } ],
    "total_banks": 1847
  }
}

Cached 24h per provider — repeated calls don't cost anything extra.

Only after is_kyc_verified: true. Registers who the money is going to.

Response — OTP Sent

{
  "success": true, "message": "OTP Successfully sent",
  "data": {
    "beneficiary_id": "7c1e2f3a-1234-4abc-9def-1234567890ab",
    "statuscode": "OTP", "status": "OTP Successfully sent",
    "data": { "beneficiaryId": "2cbd9684...", "referenceKey": "gJFqtmhE..." }
  }
}

The OTP from Step 5 goes to the remitter's mobile (not the beneficiary's) — the remitter is confirming they want to add this beneficiary.

{ "success": true, "message": "Success", "data": { "success": true, "beneficiary_id": "7c1e2f3a-...", "statuscode": "TXN" } }

Any already-verified beneficiary can be deleted at any time.

Sends an OTP to the remitter's mobile — does not delete by itself. Body: beneficiary_id (must have no pending transfer, or you get 409).

Body: beneficiary_id, otp. On success the beneficiary is permanently removed and its ID becomes invalid everywhere else.

Required immediately before every transfer — Step 6's OTP cannot be reused.

{ "success": true, "message": "OTP Successfully sent", "data": { "beneficiary_id": "7c1e2f3a-...", "statuscode": "OTP", "data": { "referenceKey": "NjINNkM5...", "isTxnBioAuthRequired": false } } }

Response — Success

{
  "success": true, "message": "DMT transfer completed successfully.",
  "data": {
    "transaction": {
      "transaction_id": "TXN20260802ABCDE", "internal_txn_id": "b3f1c2d4-...",
      "reference_id": "IP20260802123456", "utr": "IP20260802123456",
      "partner_request_id": "RESELLER-ORDER-9981", "status": "success",
      "amount": 5000, "commission": 12.5, "net_amount": 5012.5
    },
    "statuscode": "TXN", "status": "Success", "data": { "txnReferenceId": "IP20260802123456" }
  }
}

Response — Pending (timeout, no definitive answer yet)

{
  "success": true, "message": "DMT transfer initiated. Check status shortly.",
  "data": {
    "transaction": { "transaction_id": "TXN20260802ABCDE", "status": "pending", "amount": 5000, "commission": 12.5, "net_amount": 5012.5 },
    "error": "cURL error 28: Operation timed out"
  }
}

Response — Failed & Refunded

{ "success": false, "message": "DMT transfer failed. Amount has been refunded to your wallet.", "data": { "transaction": { "status": "refunded", "amount": 5000, "commission": 12.5, "net_amount": 5012.5 } } }

{transactionId} is the transaction_id from Step 8. Resolved transactions return instantly from our own records; only still-pending ones trigger a fresh provider check internally.

{
  "success": true, "message": "DMT status retrieved.",
  "data": {
    "transaction_id": "TXN20260802ABCDE", "utr": "IP20260802123456",
    "partner_request_id": "RESELLER-ORDER-9981", "amount": 5000,
    "commission": 12.5, "net_amount": 5012.5, "status": "success",
    "created_at": "2026-08-02T16:33:59.000000Z"
  }
}

Onboard a new retailer, once. Needs the retailer's own identity (Aadhaar/PAN/name/DOB) — the outlet is registered under their own identity.

Response

{
  "success": true, "message": "Transaction Successful",
  "data": {
    "success": true, "outlet_id": "714724",
    "raw": { "data": { "outletId": 714724, "name": "A**HIT G**TA", "state": "RAJASTHAN" } }
  }
}

Call right after Signup to check whether biometric submission is needed.

{
  "success": true, "data": {
    "action_required": true, "status": "PENDING",
    "outlet_aadhaar": null,
    "reference_key": "GioMS1k4VyBbY/r3LUzyR9sSaXtEIb6R3nAjtq9gL9AvqMO/4A0wgRZAarU7y7Sn"
  }
}

Only when Step 2 returned action_required: true. Requires the retailer's own fingerprint capture.

{ "success": true, "data": { "success": true, "message": "Biometric KYC completed" } }

Call after Step 3, then periodically until aeps_ready: true. This is the real signal that the outlet can transact — bank approval takes time.

{
  "success": true, "data": {
    "aeps_ready": true, "wap_status": true,
    "biometric": { "status": "Biometric authentication already completed", "action_required": false },
    "record": { "outletId": 714724, "products": { "wapStatus": true } }
  }
}

aeps_ready: false -> any AEPS call returns 403. Poll this until true. aeps_ready/wap_status reflect bank approval; biometric.* reflects biometric-KYC completion — two separate checks bundled into one call.

Call before any transaction to find the customer's bank — gives you the bankiin every other AEPS call needs.

{
  "statuscode": "TXN", "status": "Banks fetched successfully",
  "data": [
    { "bankId": 109005, "name": "STATE BANK OF INDIA", "iin": "607094", "aepsEnabled": true },
    { "bankId": 1, "name": "AIRTEL PAYMENTS BANK", "iin": "990320", "aepsEnabled": true }
  ]
}

iin is what you pass as bankiin in every other AEPS call.

Check daily, before any transaction — has today's 2FA already been done?

{ "success": true, "data": { "logged_in": false, "actcode": "LOGINREQUIRED" } }

logged_in: false -> run Outlet Login first.

Once per calendar day (expires at midnight), before any transaction. Uses the retailer's own Aadhaar and fingerprint — not the customer's.

{ "success": true, "data": { "success": true, "message": "SUCCESS" } }

Only needed when the Cash Withdrawal amount will be above ₹5,000.

{ "success": true, "data": { "message": "OTP Successfully sent", "reference_key": "F7Z7WzbRJZeF5nM1...", "otp_required": true } }

otp_required: true (off-us) -> embed the customer's OTP in the withdrawal capture. false (on-us) -> no OTP needed, but reference_key is still required in the withdrawal call.

Response — Success

{
  "success": true, "data": {
    "success": true, "message": "Transaction Successful",
    "transaction": { "transaction_id": "KRESTAA9MKMEQ5LMV29C2", "status": "success", "amount": 500, "commission": 5.0 },
    "provider": { "bankName": "State Bank of India", "bankAccountBalance": "1520.00" }
  }
}

Common bank/UIDAI-side rejection messages: "No account found for given Aadhaar number", "Pre auth failed for given request", "U16Risk threshold has exceeded", "UIDAI_ERROR552 Invalid wadh element".

Same body as Cash Withdrawal, minus amount/reference_key.

{ "success": true, "data": { "success": true, "balance": "1520.00" } }

Same body as Balance Enquiry.

{
  "success": true, "data": {
    "success": true,
    "mini_statement": [
      { "date": "02/08/2026", "txnType": "CR", "amount": "1.00", "narration": "01015522" },
      { "date": "18/07/2026", "txnType": "DR", "amount": "2000.00", "narration": "NFI/CASH" }
    ]
  }
}

{
    "success": true,
    "data": {
        "wallet_id":         "9c1b4f5a-...",
        "total_balance":     "46000.0000",
        "available_balance": "45000.0000",
        "hold_balance":      "0.0000",
        "unsettled_balance": "1000.0000"
    }
}

Full ledger of every debit/credit — useful for reconciling refunds and settlements against your own records.