Endpoint Reference

Every endpoint a partner (vendor) credential can call, generated directly from BucksBox-Vendor.postman_collection.json — same paths, same request bodies, same order. For the encryption/checksum mechanics these all ride on top of, see Authentication & Security; this page is the flat endpoint-by-endpoint list.

Base URLs

EnvironmentBase URLFull example (/aeps/withdrawal)
Productionhttps://api.bucksbox.in/gatewayhttps://api.bucksbox.in/gateway/process/aeps/withdrawal
Staginghttps://api.bucksbox.in/gateway-stagehttps://api.bucksbox.in/gateway-stage/process/aeps/withdrawal
Local devhttp://localhost:3001http://localhost:3001/process/aeps/withdrawal

Every path below is written relative to /process — append it to whichever base URL's environment you're targeting. This is exactly the {{gatewayBaseUrl}} collection variable in the Postman collection; point it at the Production or Staging base URL above (or use the BucksBox-Production.postman_environment.json / BucksBox-Staging.postman_environment.json files, which already do).

Every call needs

  • Method + path as listed per endpoint below, always prefixed with /process.
  • Headers: X-Client-Id, X-Timestamp, X-IV, X-Tag, X-Checksum, X-Request-Id, Content-Type: application/json — see Authentication & Security for how to build each.
  • Body: { "payload": "<base64 AES-256-GCM ciphertext of the JSON shown per endpoint>" }.

The plaintext JSON shown under each endpoint below is what you encrypt into that payload — none of it is sent in the clear. Every AEPS/DMT body includes merchantId, the merchant this call acts on behalf of (see Authentication & Security → Acting on behalf of a merchant).

AEPS

17 endpoints, all under /process/aeps/*.

#NameMethodPath
1InitializePOST/process/aeps/initialize
2OnboardingPOST/process/aeps/onboarding
3Request OTPPOST/process/aeps/request_otp
4Validate OTPPOST/process/aeps/validate_otp
5Verify PANPOST/process/aeps/verify_pan
6Update UIDPOST/process/aeps/update_UID
7Update BiodetailPOST/process/aeps/updatebiodetail
8SubmitPOST/process/aeps/submit
9Status CheckGET/process/aeps/statusCheck
10Get Agent DetailPOST/process/aeps/GetAgentDetail
11Req AuthPOST/process/aeps/reqAuth
12Auth StatusGET/process/aeps/authStatus
13WithdrawalPOST/process/aeps/withdrawal
14Balance EnquiryPOST/process/aeps/balance
15Mini StatementPOST/process/aeps/minstatement
16Purchase (Aadhaar Pay)POST/process/aeps/purchase
17Banks (IIN list)GET/process/aeps/banks

1. Initialize

{ "merchantId": "{{vendorMerchantId}}" }

KYC service activation — no fields beyond merchantId.

2. Onboarding

{ "merchantId": "{{vendorMerchantId}}" }

3. Request OTP

{ "merchantId": "{{vendorMerchantId}}" }

4. Validate OTP

{ "merchantId": "{{vendorMerchantId}}", "otp": "123456", "otpreqid": "" }

5. Verify PAN

{ "merchantId": "{{vendorMerchantId}}", "pan": "ABCDE1234F", "name": "Ravi Kumar", "dob": "1990-01-15" }

6. Update UID (Aadhaar)

{ "merchantId": "{{vendorMerchantId}}", "aadhaarno": "999999999999" }

7. Update Biodetail

{ "merchantId": "{{vendorMerchantId}}", "PidData": "<base64-biometric-capture-xml>", "aadhaarno": "999999999999" }

8. Submit

{ "merchantId": "{{vendorMerchantId}}" }

9. Status Check

{ "merchantId": "{{vendorMerchantId}}" }

GET, but still sent as an encrypted body — paymentSystem's route reads merchantId off req.body, and the gateway forwards a GET with a body unchanged.

10. Get Agent Detail

{ "merchantId": "{{vendorMerchantId}}", "agentId": "" }

agentId optional — empty string defaults to your own terminal's MID.

11. Req Auth (daily agent authentication)

{
  "merchantId": "{{vendorMerchantId}}",
  "AadharNo": "999999999999",
  "TxnAmount": 0,
  "Latitude": "19.0760",
  "Longitude": "72.8777",
  "CustomerName": "Ravi Kumar",
  "PidData": "<base64-biometric-capture-xml>",
  "BankName": "607086"
}

{ "statusCode": "00", "message": "Transaction successful", "data": { "ResponseCode": "00", "ResponseStatus": "SUCCESS", "STAN": "011030" } }

One-time (24h) NSDL agent authentication — also runs automatically on your first transaction of the day if you skip it. No Balance/Ministatement field; it's purely an auth handshake, and the session it opens is cached for 24 hours.

12. Auth Status

{ "merchantId": "{{vendorMerchantId}}" }

Read-only — never calls NSDL.

13. Withdrawal

POST https://api.bucksbox.in/gateway/process/aeps/withdrawal
X-Client-Id: <your apiKey>

Plaintext body — encrypt with AES-256-GCM using your SaltAESKey (64-char hex or 44-char base64, both decode to 32 bytes) before sending as { "payload": "..." }:

{
  "merchantId": "{{vendorMerchantId}}",
  "AadharNo": "999999999999",
  "TxnAmount": 1000,
  "Latitude": "19.0760",
  "Longitude": "72.8777",
  "CustomerName": "Ravi Kumar",
  "PidData": "<base64-biometric-capture-xml>",
  "BankName": "607086"
}

{
  "statusCode": "00",
  "message": "Transaction successful",
  "data": {
    "ResponseCode": "00",
    "ResponseStatus": "SUCCESS",
    "Balance": "15230.00",
    "STAN": "011032",
    "RetailerReferenceNumber": "RRN-...",
    "ReferenceNo": "...",
    "AuthCode": "cdcf3f268b87422f859e0b10676bfde8",
    "AadharNo": "********4821"
  }
}

Balance is the balance after the withdrawal. ResponseCode "00" = success. No response at all (NSDL timeout) is treated as pending, not failed — recorded with a generated reference (AEPS-NR-<timestamp>) for later reconciliation.

14. Balance Enquiry

POST https://api.bucksbox.in/gateway/process/aeps/balance
X-Client-Id: <your apiKey>

Plaintext body — encrypt with AES-256-GCM using your SaltAESKey (64-char hex or 44-char base64, both decode to 32 bytes) before sending as { "payload": "..." }:

{
  "merchantId": "{{vendorMerchantId}}",
  "AadharNo": "999999999999",
  "TxnAmount": 0,
  "Latitude": "19.0760",
  "Longitude": "72.8777",
  "CustomerName": "Ravi Kumar",
  "PidData": "<base64-biometric-capture-xml>",
  "BankName": "607086"
}

{
  "statusCode": "00",
  "message": "Transaction successful",
  "data": { "ResponseCode": "00", "ResponseStatus": "SUCCESS", "Balance": "15230.00", "STAN": "011033", "RetailerReferenceNumber": "RRN-...", "AadharNo": "********4821" }
}

TxnAmount still required by the validator for a balance enquiry — send 0.

15. Mini Statement

POST https://api.bucksbox.in/gateway/process/aeps/minstatement
X-Client-Id: <your apiKey>

Plaintext body — encrypt with AES-256-GCM using your SaltAESKey (64-char hex or 44-char base64, both decode to 32 bytes) before sending as { "payload": "..." }:

{
  "merchantId": "{{vendorMerchantId}}",
  "AadharNo": "999999999999",
  "TxnAmount": 0,
  "Latitude": "19.0760",
  "Longitude": "72.8777",
  "CustomerName": "Ravi Kumar",
  "PidData": "<base64-biometric-capture-xml>",
  "BankName": "607086"
}

{
  "statusCode": "00",
  "message": "Transaction successful",
  "data": {
    "ResponseCode": "00",
    "ResponseStatus": "SUCCESS",
    "Ministatement": "02/06 POS/D/5017000018 C 100.00\n01/06 POS/W/5017000017 D 500.00",
    "STAN": "011034",
    "AadharNo": "********4821"
  }
}

Ministatement is a single \n-delimited string (NSDL's own format), not a JSON array.

16. Purchase (Aadhaar Pay)

POST https://api.bucksbox.in/gateway/process/aeps/purchase
X-Client-Id: <your apiKey>

Plaintext body — encrypt with AES-256-GCM using your SaltAESKey (64-char hex or 44-char base64, both decode to 32 bytes) before sending as { "payload": "..." }:

{
  "merchantId": "{{vendorMerchantId}}",
  "AadharNo": "999999999999",
  "TxnAmount": 500,
  "Latitude": "19.0760",
  "Longitude": "72.8777",
  "CustomerName": "Ravi Kumar",
  "PidData": "<base64-biometric-capture-xml>",
  "BankName": "607086"
}

{
  "statusCode": "00",
  "message": "Transaction successful",
  "data": { "ResponseCode": "00", "ResponseStatus": "SUCCESS", "STAN": "011035", "RetailerReferenceNumber": "RRN-...", "ReferenceNo": "...", "AuthCode": "9f1c2a3b4d5e6f708192a3b4c5d6e7f8", "AadharNo": "********4821" }
}

Same shape as Withdrawal, minus Balance — a point-of-sale debit, not a cash disbursement.

17. Banks (IIN list)

GET https://api.bucksbox.in/gateway/process/aeps/banks
X-Client-Id: <your apiKey>

Plaintext body — encrypt with AES-256-GCM using your SaltAESKey (64-char hex or 44-char base64, both decode to 32 bytes) before sending as { "payload": "..." }:

{}

{ "statusCode": "00", "message": "success", "data": [ { "iin": "918152", "bankName": "State Bank of India" }, { "iin": "607086", "bankName": "Axis Bank" } ] }

No merchantId needed — a static reference list, not merchant-scoped. BankName on every transaction above must be one of these iin values.

See Partner API → AEPS for every endpoint above written out in full (including the onboarding steps 1–10) with production/staging URLs side by side.

DMT — Customer (Remitter Onboarding)

8 endpoints, all under /process/dmt/customer/*.

#NameMethodPath
1Get DetailPOST/process/dmt/customer/GetDetail
2OnboardingPOST/process/dmt/customer/onboarding
3Request OTPPOST/process/dmt/customer/request_otp
4Validate OTPPOST/process/dmt/customer/validate_otp
5Verify UIDPOST/process/dmt/customer/verify_UID
6Update BiodetailPOST/process/dmt/customer/updatebiodetail
7SubmitPOST/process/dmt/customer/submit
8Status CheckGET/process/dmt/customer/statusCheck

1. Get Detail

{ "merchantId": "{{vendorMerchantId}}", "mobile_number": "9876543210" }

2. Onboarding (customer registration)

POST https://api.bucksbox.in/gateway/process/dmt/customer/onboarding
X-Client-Id: <your apiKey>

Plaintext body — encrypt with AES-256-GCM using your SaltAESKey (64-char hex or 44-char base64, both decode to 32 bytes) before sending as { "payload": "..." }:

{
  "merchantId": "{{vendorMerchantId}}",
  "name": "Ravi Kumar",
  "mobile_no": "9876543210",
  "email_id": "ravi@example.com",
  "city": "Mumbai",
  "state": "Maharashtra"
}

{ "statusCode": "00", "message": "success", "data": { "referenceid": "REF-a1b2c3d4" } }

This is the call that actually registers the customer as a DMT remitter candidate. email_id optional, the rest required. Grab referenceid from the response and reuse it for every step below.

3. Request OTP

{ "merchantId": "{{vendorMerchantId}}", "referenceid": "{{dmtReferenceId}}" }

4. Validate OTP

{ "merchantId": "{{vendorMerchantId}}", "otp": "123456", "otpreqid": "", "referenceid": "{{dmtReferenceId}}" }

5. Verify UID (Aadhaar)

{ "merchantId": "{{vendorMerchantId}}", "aadhaarno": "999999999999", "referenceid": "{{dmtReferenceId}}" }

6. Update Biodetail

{ "merchantId": "{{vendorMerchantId}}", "PidData": "<base64-biometric-capture-xml>", "aadhaarno": "999999999999", "referenceid": "{{dmtReferenceId}}" }

7. Submit

{ "merchantId": "{{vendorMerchantId}}", "referenceid": "{{dmtReferenceId}}" }

8. Status Check

{ "merchantId": "{{vendorMerchantId}}", "referenceid": "{{dmtReferenceId}}" }

GET, but referenceid still travels in the encrypted body, not a query string — query strings can't carry the encrypted envelope.

DMT — Transactions (Remitter)

12 endpoints, all under /process/dmt/txn/v1/*.

#NameMethodPath
1Remitter — RegisterPOST/process/dmt/txn/v1/remitter/register
2Remitter — DetailsPOST/process/dmt/txn/v1/remitter/details
3Beneficiary — AddPOST/process/dmt/txn/v1/beneficiary/add
4Beneficiary — Account VerificationPOST/process/dmt/txn/v1/beneficiary/accountVerification
5Beneficiary — GetPOST/process/dmt/txn/v1/beneficiary/get
6Beneficiary — DeletePOST/process/dmt/txn/v1/beneficiary/delete
7Transaction — OTPPOST/process/dmt/txn/v1/transaction/otp
8Transaction — Instant TransferPOST/process/dmt/txn/v1/transaction/instant
9Transaction — ChargesPOST/process/dmt/txn/v1/transaction/charges
10Transaction — RequeryPOST/process/dmt/txn/v1/transaction/requery
11Transaction — Refund OTPPOST/process/dmt/txn/v1/transaction/refundOTP
12RefundPOST/process/dmt/txn/v1/refund

1. Remitter — Register

{ "merchantId": "{{vendorMerchantId}}", "sender_mobilenumber": "9876543210" }

sender_mobilenumber or senderId. Grab senderid from the decrypted response and reuse it below.

2. Remitter — Details

{ "merchantId": "{{vendorMerchantId}}", "sender_mobilenumber": "9876543210" }

3. Beneficiary — Add

{
  "merchantId": "{{vendorMerchantId}}",
  "senderId": "{{dmtSenderId}}",
  "receivername": "Priya Sharma",
  "receivermobilenumber": "9876500000",
  "receiveremailid": "priya@example.com",
  "receiverIfscCode": "HDFC0001234",
  "receiver_account_no": "1234567890",
  "address": "123 MG Road",
  "city": "Mumbai",
  "state": "Maharashtra",
  "branch_contact": ""
}

4. Beneficiary — Account Verification (Penny-Drop)

{
  "merchantId": "{{vendorMerchantId}}",
  "sender_mobilenumber": "9876543210",
  "senderId": "{{dmtSenderId}}",
  "receiver_account_no": "1234567890",
  "receiverIfscCode": "HDFC0001234",
  "receivername": "Priya Sharma",
  "receivermobilenumber": "9876500000",
  "receiveremailid": "priya@example.com"
}

5. Beneficiary — Get

{
  "merchantId": "{{vendorMerchantId}}",
  "senderId": "{{dmtSenderId}}",
  "receiverIfscCode": "HDFC0001234",
  "receiver_account_no": "1234567890"
}

6. Beneficiary — Delete

{
  "merchantId": "{{vendorMerchantId}}",
  "senderId": "{{dmtSenderId}}",
  "receiver_account_no": "1234567890",
  "receiverIfscCode": "HDFC0001234"
}

7. Transaction — OTP

{
  "merchantId": "{{vendorMerchantId}}",
  "senderId": "{{dmtSenderId}}",
  "amount": 500,
  "receiver_account_no": "1234567890",
  "receiverIfscCode": "HDFC0001234"
}

8. Transaction — Instant Transfer

{
  "merchantId": "{{vendorMerchantId}}",
  "senderId": "{{dmtSenderId}}",
  "BeneficiaryId": "",
  "amount": 500,
  "refId": "",
  "remarks": "Groceries",
  "otp": "123456",
  "receiver_account_no": "1234567890",
  "receiverIfscCode": "HDFC0001234",
  "account_holder_name": "Priya Sharma",
  "receiverMobilenumber": "9876500000"
}

otp comes from Transaction — OTP above.

9. Transaction — Charges

{ "merchantId": "{{vendorMerchantId}}", "senderId": "{{dmtSenderId}}", "amount": 500 }

10. Transaction — Requery

{ "merchantId": "{{vendorMerchantId}}", "refId": "" }

11. Transaction — Refund OTP

{ "merchantId": "{{vendorMerchantId}}", "refereanceId": "" }

⚠️ refereanceId is spelled that way in the backend (dmt.txn.controller.js#refundOTP) — not a typo on this page.

12. Refund

{ "merchantId": "{{vendorMerchantId}}", "transactionId": "", "refId": "", "otp": "123456" }

{ "statusCode": "00", "message": "Refund processed successfully", "data": { "refundId": "RFD-uuid", "amount": 500 } }

otp comes from Transaction — Refund OTP above.

See Partner API → DMT for every endpoint above written out in full (customer registration flow, remitter/beneficiary management, transactions) with production/staging URLs and response examples for each.

UPI

1 endpoint, currently non-functional for partner credentials — see below.

#NameMethodPath
1Generate QRPOST/process/upi/txn/v1/GenerateQR

1. Generate QR (Static or Dynamic)

POST https://api.bucksbox.in/gateway/process/upi/txn/v1/GenerateQR
X-Client-Id: <your apiKey>

Plaintext body — encrypt with AES-256-GCM using your SaltAESKey (64-char hex or 44-char base64, both decode to 32 bytes) before sending as { "payload": "..." }:

{ "merchantId": "{{vendorMerchantId}}", "amount": 250, "order_id": "ORD-12345" }

amount present = Dynamic QR; omitted or 0 = Static QR.

Response today — 403:

{ "statusCode": "01", "message": "Access denied" }

Expect 403 today

paymentSystem's /upi/txn/v1/GenerateQR route is gated checkRole("merchant") only — a partner/vendor credential is rejected before the request body is even read, regardless of merchantId. This endpoint is documented for completeness (and for when this is opened up server-side), not because it currently works. See Vendor UPI for the full explanation and the response shape a working call would return.

Source

This page and the Postman collection it's generated from are kept in sync by hand — if you add or change a partner-facing endpoint in fintech-gateway/paymentSystem, update the Postman collection first, then reflect the change here.