@bucksbox/capacitor-sdk
v1.1.0
Published
Capacitor bridge for the BucksBox Android SDK — launches the sdk/websdk widget flows (AEPS, DMT, UPI, merchant signup/onboarding) in a native WebView shell, plus the websdk API client for UPI, AEPS, DMT and merchant onboarding and UIDAI RD fingerprint cap
Readme
@bucksbox/capacitor-sdk
Capacitor plugin for BucksBox AEPS, DMT, merchant onboarding and UPI QR on Android.
There are two ways to integrate, and an app can use both:
| | What you get | Call |
|---|---|---|
| Widget flows | Complete screens: forms, OTP, fingerprint capture, receipts. One call returns the outcome | BucksBoxSdk.launch({ service, … }) |
| Headless API | The same backend calls as the BucksBox web SDK, behind your own UI | createBucksBoxClient(config).aeps.balance(…) |
Plus fingerprint capture (captureFingerprint()) through the UIDAI RD service app installed on the device. The headless AEPS and DMT calls need its PidData.
| Service | Widget service | API module |
|---|---|---|
| AEPS — cash withdrawal, balance, mini statement, Aadhaar Pay | aeps | client.aeps |
| AEPS agent onboarding | aeps-onboarding | client.aeps |
| DMT — remitters, beneficiaries, transfers | dmt | client.dmt |
| DMT BC-agent onboarding | dmt-onboarding | client.dmt |
| Merchant signup (by a vendor) | merchant-signup | client.registration |
| Merchant KYC onboarding | merchant-onboarding | client.onboarding |
| UPI QR — static and dynamic, collect, SMS pay | upi | client.upi |
Every request is encrypted with AES-256-GCM, signed with HMAC-SHA256 and sent to the BucksBox gateway by the native SDK.
Contents
- Requirements
- Installation
- Configuration
- Quick start
- AEPS
- DMT
- Merchant onboarding
- UPI QR
- Fingerprint capture (RD service)
- Location
- Results and errors
- Web platform
- Security
- Troubleshooting
- Test app
- API reference
Requirements
| | |
|---|---|
| Capacitor | 6 or later (verified with 8.5) |
| Android | minSdk 24 (Android 7.0). compileSdk/targetSdk follow your app |
| Kotlin Gradle plugin | in your Android project (verified with 2.1.21) |
| iOS | not supported |
| For AEPS / DMT biometrics | a UIDAI RD service app (e.g. Mantra) and a fingerprint scanner on the device |
| Credentials | a BucksBox clientId and key for staging or production |
Installation
The plugin and the native SDK it wraps (android-sdk/bucksbox-sdk) aren't published to npm or Maven yet. You install them from a checkout of this repository.
1. Build the plugin once
cd android-sdk/bridges/capacitor
npm install
npm run build2. Add it to your app
cd your-capacitor-app
npm install ../path/to/android-sdk/bridges/capacitor
npx cap sync androidcap sync detects the plugin, adds its Android module and registers it. You don't need to edit MainActivity.
3. Include the native SDK module (one-time edit of android/settings.gradle)
include ':bucksbox-sdk'
project(':bucksbox-sdk').projectDir = new File(settingsDir, '../path/to/android-sdk/bucksbox-sdk')4. Add the Kotlin Gradle plugin (one-time edit of android/build.gradle, in buildscript { dependencies { … } })
classpath 'org.jetbrains.kotlin:kotlin-gradle-plugin:2.1.21'5. Build
cd android && ./gradlew assembleDebugandroid-sdk/samples/capacitor/scripts/setup-android.mjs automates steps 3 and 4. You can copy it into your app.
What the SDK adds to your app's manifest (merged automatically)
| Entry | Why |
|---|---|
| INTERNET | Gateway calls |
| ACCESS_FINE_LOCATION, ACCESS_COARSE_LOCATION | NSDL requires the agent's location on every AEPS call. Requested at runtime only when a flow needs it |
| <queries> for in.gov.uidai.rdservice.fp.CAPTURE / INFO | Lets the SDK find the installed RD service app on Android 11+ |
| BucksBoxActivity, a FileProvider | The widget screen, and camera capture for KYC document upload |
Configuration
Both launch() and createBucksBoxClient() take the same credentials:
| Field | Required | Notes |
|---|---|---|
| clientId | yes | The account's User.apiKey |
| key | yes | The account's User.SaltAESKey: a 32-byte AES key, as 64 hex characters or base64 |
| environment | one of these two | 'production' → https://api.bucksbox.in/gateway, 'staging' → https://uatgateway.bucksbox.in |
| gatewayUrl | | An explicit gateway URL. Takes priority over environment. Must be HTTPS (the SDK blocks cleartext traffic) |
| merchantId | no | Only for vendor credentials acting for one merchant. It's added to every request body that doesn't already have one |
| checksumSecret | no | Defaults to key |
| timeout | no | Headless API only, in ms. Default 30000 |
Which credentials to use:
| Flow | Credentials |
|---|---|
| AEPS, DMT, UPI, merchant KYC onboarding | The merchant's own, or a vendor's plus merchantId |
| DMT BC-agent onboarding (dmt-onboarding, dmt.initializeAgent, dmt.registerAgent) | A vendor's (or aggregator's) plus merchantId. A merchant's own credentials are rejected |
| Merchant signup (merchant-signup, client.registration) | The onboarding vendor's. The new merchant is linked to that vendor |
Quick start
import { BucksBoxSdk, createBucksBoxClient } from '@bucksbox/capacitor-sdk';
const credentials = { environment: 'staging' as const, clientId: '…', key: '…' };
// A complete flow, with BucksBox screens
const result = await BucksBoxSdk.launch({ ...credentials, service: 'aeps' });
if (result.status === 'success') {
// the transaction completed — see "Results and errors"
}
// The same backend, behind your own UI
const client = createBucksBoxClient(credentials);
const banks = await client.aeps.banks();
if (banks.statusCode === '00') console.log(banks.data);Every API method resolves with the decrypted response, typically { statusCode, message, data }. statusCode === '00' means success. Any other value is a business failure: it still resolves, it doesn't reject. See Results and errors.
AEPS
Widget
// Agent onboarding with NSDL: OTP, PAN, Aadhaar, fingerprint. Run once per agent.
await BucksBoxSdk.launch({ ...credentials, service: 'aeps-onboarding' });
// Transactions: the daily agent authentication, then withdrawal / balance / mini statement / Aadhaar Pay
const r = await BucksBoxSdk.launch({ ...credentials, service: 'aeps' });The widget handles bank selection, the daily (24-hour) agent authentication, location and fingerprint capture. A PENDING transaction (no confirmation from the bank) is reported as status: 'failure' with resultStatus: 'PENDING'. Verify it with the reference number before treating it as failed.
Headless API
Agent onboarding, once per agent. This is the order the widget uses:
await client.aeps.onboarding();
const otpReq = await client.aeps.requestOtp();
await client.aeps.validateOtp({ otp, otpreqid }); // otpreqid from the requestOtp response
await client.aeps.verifyPan({ pan, name, dob });
await client.aeps.updateUid({ aadhaarno });
const fp = await BucksBoxSdk.captureFingerprint();
if (fp.status === 'success') await client.aeps.updateBiodetail({ PidData: fp.pidData, aadhaarno });
const status = await client.aeps.statusCheck();initialize(), submit() and getAgentDetail() are also available for terminals that need them.
Daily agent authentication, required once every 24 hours before any transaction:
const auth = await client.aeps.authStatus();
if (auth.statusCode !== '00') {
const fp = await BucksBoxSdk.captureFingerprint(); // the agent's finger
await client.aeps.reqAuth({
AadharNo: agentAadhaar, Latitude, Longitude, CustomerName: agentName,
PidData: fp.pidData,
});
}Transactions:
const { data: bankList } = await client.aeps.banks(); // the bank's IIN goes in BankName
const fp = await BucksBoxSdk.captureFingerprint(); // the customer's finger
const body = {
AadharNo: '…', CustomerName: '…', Latitude, Longitude,
PidData: fp.pidData,
BankName: selectedIin,
};
await client.aeps.balance(body);
await client.aeps.minStatement(body);
await client.aeps.withdrawal({ ...body, TxnAmount: 500 });
await client.aeps.purchase({ ...body, TxnAmount: 500 }); // Aadhaar PayCapture a new fingerprint for every call. A PidData is single-use.
DMT
Widget
// Register the merchant as an NSDL DMT Business Correspondent agent (vendor credentials + merchantId)
await BucksBoxSdk.launch({ ...vendorCredentials, merchantId, service: 'dmt-onboarding' });
// Money transfer: remitter lookup/registration, customer onboarding, beneficiaries, OTP, transfer, status
const r = await BucksBoxSdk.launch({ ...credentials, service: 'dmt' });A transfer that ends PENDING is reported as status: 'failure' with resultStatus: 'PENDING'. Re-check it with client.dmt.transactionRequery().
Headless API
// 1. Find or register the remitter
let remitter = await client.dmt.getRemitterDetails({ sender_mobilenumber: mobile });
if (remitter.statusCode !== '00') {
await client.dmt.registerRemitter({ sender_mobilenumber: mobile });
}
// 2. New customer onboarding (when the remitter isn't onboarded yet)
const ob = await client.dmt.onboardCustomer({ name, mobile_no: mobile, email_id, city, state });
await client.dmt.requestCustomerOtp({ referenceid });
await client.dmt.validateCustomerOtp({ otp, otpreqid, referenceid });
await client.dmt.verifyCustomerUid({ aadhaarno, referenceid });
const fp = await BucksBoxSdk.captureFingerprint();
await client.dmt.updateCustomerBiodetail({ PidData: fp.pidData, aadhaarno, referenceid });
// 3. Beneficiary
await client.dmt.accountVerification({ sender_mobilenumber: mobile, receiver_account_no, receiverIfscCode, receivername, receivermobilenumber });
await client.dmt.addBeneficiary({ senderId, receivername, receivermobilenumber, receiveremailid, receiverIfscCode, receiver_account_no });
// 4. Transfer
await client.dmt.transactionCharges({ senderId, amount });
await client.dmt.transactionOtp({ senderId, amount, receiver_account_no, receiverIfscCode });
const txn = await client.dmt.transactionInstant({
senderId, BeneficiaryId, amount, refId, otp,
receiver_account_no, receiverIfscCode, account_holder_name,
});
// 5. Pending or ambiguous outcome
await client.dmt.transactionRequery({ /* fields from the transaction response */ });Also available: getCustomerDetail, customerStatusCheck, submitCustomer, getBeneficiary, deleteBeneficiary, transaction, refundOtp, refund, login. BC-agent onboarding is initializeAgent() then registerAgent({ name, lastname, pancard, dmt?, aeps? }), with vendor credentials.
Merchant onboarding
Onboarding a new merchant has two parts, with different credentials:
| Step | Widget | Credentials | Produces |
|---|---|---|---|
| 1. Signup | merchant-signup | The onboarding vendor's | The new merchant's account and its clientId/key |
| 2. KYC (ISG) | merchant-onboarding | The merchant's own (from step 1) | KYC submitted for verification |
Widget
const signup = await BucksBoxSdk.launch({ ...vendorCredentials, service: 'merchant-signup' });
if (signup.status === 'success') {
// signup.merchantId, signup.clientId, signup.key — the new merchant's credentials.
// signup.existing === true means the merchant already existed and should resume, not re-register.
// Send these to your backend and store them there. Don't keep the key in the app.
const kyc = await BucksBoxSdk.launch({
environment: 'staging', clientId: signup.clientId as string, key: signup.key as string,
service: 'merchant-onboarding',
});
if (kyc.status === 'success' && kyc.resultStatus === 'not_onboardable') {
// The merchant can't be onboarded right now. Show kyc.title / kyc.message.
}
}merchant-onboarding resumes from where the merchant left off. A merchant who already verified PAN in an earlier session goes straight to the next incomplete step.
Headless API
Signup (vendor credentials):
const vendor = createBucksBoxClient(vendorCredentials);
const { data: businessTypes } = await vendor.registration.getBusinessTypes();
const { data: turnover } = await vendor.registration.getTurnoverRanges();
const { data: mcc } = await vendor.registration.searchMcc('kirana'); // 2+ characters
const { data: pins } = await vendor.registration.searchPincode('5600');
const { data: services } = await vendor.registration.getServiceCatalog();
const reg = await vendor.registration.register({ /* merchant details */ });
// reg.data.user.apiKey / reg.data.user.SaltAESKey — the new merchant's clientId / keyKYC (merchant credentials). This is the order the widget uses:
const merchant = createBucksBoxClient(merchantCredentials);
await merchant.onboarding.sendOtp({ phone });
await merchant.onboarding.verifyOtp({ phone, otp }); // data.token null with '00' = no account for that number
const { data: own } = await merchant.onboarding.getOwnMerchantForOnboarding();
const merchantId = own.id; // the real merchant id (not the `mid` display code)
const status = await merchant.onboarding.isgComplianceStatus(); // kycStatus, summary, per-category documents
await merchant.onboarding.isgVerifyPan({ pan, name, dob: '31/12/1990', fathername, merchantId }); // dob as DD/MM/YYYY
await merchant.onboarding.isgVerifyAccount({ accountHolderName, accountNumber, ifsc, consent: 'Y', additionalData: 'true', merchantId });
const img = await merchant.onboarding.uploadComplianceImage({ file: base64OrDataUri, filename, mimetype, merchantId });
await merchant.onboarding.isgDocUpload({ doc_type: 'PAN', doc_number, images: [img.data.id], merchantId });
await merchant.onboarding.markKycSubmitted();Backend behaviours to handle:
isgVerifyAccountcan return an HTTP 500 after the account was verified. CheckisgComplianceStatus().kycStatus.bankbefore retrying.isgDocUploadwithdoc_type: 'AADHAAR'needs at least 2 image ids (front and back).createServiceKycreplying"Service KYC already exists…"means it's already set up, not that it failed.- Use
markKycSubmitted()to finish onboarding (this is what the widget does).
UPI QR
Widget
// Dynamic QR for a fixed amount: waits for payment and reports the outcome
const paid = await BucksBoxSdk.launch({ ...credentials, service: 'upi', amount: 499, orderId: 'ORD-1001' });
if (paid.status === 'success') {
// paid.orderId, paid.amount, plus the status response fields
}
// Static QR: omit amount (the customer enters it). Scan-any-time, so there's no single outcome to wait for.
await BucksBoxSdk.launch({ ...credentials, service: 'upi' });The dynamic QR widget polls for payment every 3 seconds for up to 3 minutes, then reports resultStatus: 'FAILED' with "Payment timed out".
Headless API
const qr = await client.upi.generateQr({ amount: '499', order_id: 'ORD-1001' }); // omit amount for a static QR
if (qr.statusCode === '00') {
showImage(qr.data.qr_image); // a ready-to-display PNG data URL
const transId = qr.data.txn_ref_no; // use this to poll
// Poll until paid, failed, or your timeout
const s = await client.upi.upiStatus({ trans_id: transId });
// s.statusCode: '00' paid · '01' pending (keep polling) · '03' failed
}Send amount as a string. The backend's checksum for the QR provider is computed over its string form.
Other UPI calls:
| Need | Call |
|---|---|
| Collect request to a customer's VPA | upi.collect({ amount, order_id, vpa, customer_mobile?, customer_name? }) |
| Payment link by SMS | upi.smsPay({ amount, order_id, customer_number }), then upi.smsStatus({ trans_id }) |
| Validate a VPA | upi.verifyVpa({ payer_virtual_address }) |
| Refunds | upi.refundUpi({ tr, amount }), upi.refundSms({ trans_id }) |
| Reports | upi.transactions({ page, limit, startDate, endDate, status }), upi.transactionStatusSummary(), upi.collectionsByGranularity({ granularity: 'day' }) |
Fingerprint capture (RD service)
const { devices } = await BucksBoxSdk.listRdDevices(); // [{ packageName, label }]
const fp = await BucksBoxSdk.captureFingerprint(); // optional: { packageName, pidOptions }
switch (fp.status) {
case 'success': /* fp.pidData → the PidData field */ break;
case 'failure': /* fp.message, fp.errCode — e.g. poor quality or timeout; ask for a retry */ break;
case 'cancelled': break;
case 'no_device': /* no RD service app installed — prompt the user to install the vendor's RD app */ break;
}captureFingerprint()never rejects for a capture outcome. It always resolves with one of these four statuses.- It uses the first installed RD service app unless you pass
packageName. - The default PID options are the BucksBox web SDK's production options (
env="P", one finger, 10-second timeout). PasspidOptions(PidOptions XML) to change them. - The widget flows capture fingerprints themselves. You only need
captureFingerprint()for headless API calls.
Location
AEPS needs Latitude and Longitude on every transaction and on reqAuth.
- Widgets: the SDK asks for location permission when needed and reads the location itself.
- Headless API: read the location yourself, e.g. with
@capacitor/geolocationornavigator.geolocation, and pass the values as strings.
Results and errors
launch()
Resolves exactly once per call. It rejects only for a misconfigured call (unknown service, missing clientId/key).
| Field | Meaning |
|---|---|
| status | 'success' · 'failure' · 'cancelled' |
| resultStatus | The widget's own status, when it differs: 'SUCCESS' / 'FAILED' / 'PENDING' (UPI, AEPS, DMT), 'not_onboardable' (merchant-onboarding), or the merchant's KYC status |
| message | Human-readable reason on failure |
| …other fields | Specific to each flow (below) |
- The user closing the flow (✕ or the back button) gives
status: 'failure'withmessage: 'Payment cancelled by user'. 'cancelled'means the screen was destroyed before reporting anything, e.g. the app process was killed.
| Service | Extra fields on success |
|---|---|
| upi | orderId, amount, and the payment status response (statusCode, message, data) |
| aeps | operation, aadhaar, amount, and the transaction response |
| dmt | refId, amount, beneficiary, and the transaction response |
| dmt-onboarding | name, lastname, pancard, and the registration response |
| merchant-signup | merchantId, clientId, key, existing, statusCode, message |
| merchant-onboarding | merchantId, mid, statusCode, message; or resultStatus: 'not_onboardable' with title, message |
Results can contain personal data (Aadhaar numbers) and credentials (merchant-signup's key). Don't log them or send them to analytics.
Headless API
| Outcome | How it arrives |
|---|---|
| Success | Resolves, statusCode === '00' |
| Business failure (declined, invalid OTP, insufficient balance, …) | Resolves with another statusCode and a message |
| HTTP error (4xx/5xx from the gateway or backend) | Rejects, code: 'HTTP_<status>', data: { status, message, response } |
| Network failure or timeout | Rejects, code: 'NETWORK' |
| Bad config or arguments | Rejects, code: 'INVALID_CONFIG' / 'INVALID_REQUEST' |
try {
const res = await client.aeps.withdrawal(body);
if (res.statusCode === '00') { /* done */ } else { showError(res.message); }
} catch (e: any) {
if (e.code === 'NETWORK') { /* offline or timed out — the outcome is unknown, check status before retrying a payment */ }
else { showError(e.data?.message ?? e.message); }
}A 401 with "Checksum invalid" almost always means the key doesn't belong to that clientId.
Web platform
Running in a browser or PWA, the plugin loads the BucksBox web SDK (bucksbox.web.js):
launch()and the headless API work the same as on Android.captureFingerprint()returnsno_device, andlistRdDevices()returns an empty list.- By default it loads
https://cdn.bucksbox.in/sdk/bucksbox.web.js. PasswebScriptUrlin the config to load a copy you host yourself (sdk/websdk/dist/bucksbox.web.js). - The gateway must allow your web origin (CORS).
Security
- Anything built into the APK can be extracted, including a
keybundled through.envor config. For production, fetch credentials from your backend after the agent signs in, and keep them in memory only. - Prefer one vendor credential plus a per-agent
merchantIdover shipping merchant keys. - Never store or log
pidData. It's single-use biometric data. - The SDK only talks to the gateway over HTTPS, blocks cleartext traffic, and opens any other link outside the app.
- WebView debugging (
chrome://inspect) and widget console logs are on only when your app is debuggable.
Troubleshooting
| Symptom | Fix |
|---|---|
| Project with path ':bucksbox-sdk' could not be found | Installation step 3: include :bucksbox-sdk in android/settings.gradle |
| Plugin with id 'kotlin-android' not found / Kotlin errors | Installation step 4: add the Kotlin Gradle plugin classpath |
| "BucksBoxSdk" plugin is not implemented on android | Run npx cap sync android after installing, then rebuild |
| Cannot find module '@bucksbox/capacitor-sdk' / missing dist | Build the plugin first: npm install && npm run build in android-sdk/bridges/capacitor |
| AAR metadata error: "requires … compile against version 36" | Set compileSdkVersion in your variables.gradle to what the error asks for. The plugin follows it |
| captureFingerprint() → no_device | Install the scanner vendor's RD service app, and connect and register the device in it |
| AEPS widget: "No RD biometric service found" | Same as above |
| AEPS: location errors | Grant location permission and turn on device location |
| 401 Checksum invalid | key and clientId don't belong together, or the environment doesn't match the credentials |
| gatewayUrl with http:// fails | Use HTTPS. The SDK blocks cleartext traffic |
Test app
android-sdk/samples/capacitor is a ready-made Capacitor 8 app. It exercises every flow above: all 7 widgets, one-tap API calls, a picker for every API method, fingerprint capture, and location.
cd android-sdk/samples/capacitor
npm install
npm run android:add
adb install -r android/app/build/outputs/apk/debug/app-debug.apkStart with aeps.banks(): a statusCode "00" confirms that your credentials and the gateway connection work.
API reference
createBucksBoxClient(config) returns these modules. Method names and request bodies are the same as the BucksBox web SDK's BucksBoxClient, and an automated check keeps them in sync.
Every method returns Promise<BucksBoxResponse>. Argument styles:
(): no argument(body?): an optional object(q: string): a search string(body): a required object
Plugin methods on BucksBoxSdk:
| Method | Returns |
|---|---|
| launch(options) | { status, resultStatus?, message?, … } — see Results and errors |
| request({ config, method, path, body }) | One raw gateway call. Prefer createBucksBoxClient() |
| captureFingerprint({ packageName?, pidOptions? }) | { status, pidData?, message?, errCode? } |
| listRdDevices() | { devices: [{ packageName, label }] } |
client.aeps
AEPS (Aadhaar Enabled Payment System) — agent onboarding, daily agent authentication and transactions. Proxied to paymentSystem's /aeps routes.
| Method | HTTP → path | Body / notes |
|---|---|---|
| initialize() | POST aeps/initialize | Initialize this terminal's AEPS onboarding session. |
| onboarding() | POST aeps/onboarding | Kick off merchant onboarding with NSDL. |
| requestOtp() | POST aeps/request_otp | Request the onboarding OTP. |
| validateOtp(body?) | POST aeps/validate_otp | { otp, otpreqid } |
| verifyPan(body?) | POST aeps/verify_pan | { pan, name, dob } |
| updateUid(body?) | POST aeps/update_UID | { aadhaarno } |
| updateBiodetail(body?) | POST aeps/updatebiodetail | { PidData, aadhaarno } — PidData from captureFingerprint(). |
| submit() | POST aeps/submit | Submit the completed onboarding application. |
| statusCheck() | GET aeps/statusCheck | Onboarding status of the caller. |
| getAgentDetail(body?) | POST aeps/GetAgentDetail | { agentId? } — defaults to the terminal's MID. |
| reqAuth(body?) | POST aeps/reqAuth | Daily (24h) agent authentication: { AadharNo, Latitude, Longitude, CustomerName, PidData, BankName? } |
| authStatus() | GET aeps/authStatus | Whether today's agent authentication is still valid. |
| withdrawal(body?) | POST aeps/withdrawal | { AadharNo, TxnAmount, Latitude, Longitude, CustomerName, PidData, BankName? } |
| balance(body?) | POST aeps/balance | { AadharNo, Latitude, Longitude, CustomerName, PidData, BankName? } |
| minStatement(body?) | POST aeps/minstatement | { AadharNo, Latitude, Longitude, CustomerName, PidData, BankName? } |
| purchase(body?) | POST aeps/purchase | Aadhaar Pay: { AadharNo, TxnAmount, Latitude, Longitude, CustomerName, PidData, BankName? } |
| banks() | GET aeps/banks | NSDL IIN -> bank name list. |
client.dmt
Domestic Money Transfer — remitter onboarding (/dmt/customer), remittance (/dmt/txn/v1) and BC agent onboarding (/onboarding/dmt/bc/agent).
| Method | HTTP → path | Body / notes |
|---|---|---|
| getCustomerDetail(body?) | POST dmt/customer/GetDetail | { mobile_number } |
| onboardCustomer(body?) | POST dmt/customer/onboarding | { name, mobile_no, email_id, city, state } |
| requestCustomerOtp(body?) | POST dmt/customer/request_otp | { referenceid } |
| validateCustomerOtp(body?) | POST dmt/customer/validate_otp | { otp, otpreqid, referenceid } |
| verifyCustomerUid(body?) | POST dmt/customer/verify_UID | { aadhaarno, referenceid } |
| updateCustomerBiodetail(body?) | POST dmt/customer/updatebiodetail | { PidData, aadhaarno, referenceid } |
| submitCustomer() | POST dmt/customer/submit | Submit the completed customer onboarding application. |
| customerStatusCheck() | GET dmt/customer/statusCheck | Onboarding status of the remitter identity. |
| login() | POST dmt/txn/v1/login | Login/refresh the aggregator's NSDL DMT session. |
| registerRemitter(body?) | POST dmt/txn/v1/remitter/register | { sender_mobilenumber } |
| getRemitterDetails(body?) | POST dmt/txn/v1/remitter/details | { sender_mobilenumber? , senderId? } — one is required. |
| accountVerification(body?) | POST dmt/txn/v1/beneficiary/accountVerification | { sender_mobilenumber, receiver_account_no, receiverIfscCode, receivername, receivermobilenumber, receiveremailid? } |
| getBeneficiary(body?) | POST dmt/txn/v1/beneficiary/get | { senderId, receiverIfscCode, receiver_account_no } |
| addBeneficiary(body?) | POST dmt/txn/v1/beneficiary/add | { senderId, receivername, receivermobilenumber, receiveremailid, receiverIfscCode, receiver_account_no, address?, city?, state?, branch_contact? } |
| deleteBeneficiary(body?) | POST dmt/txn/v1/beneficiary/delete | { senderId, benefId } |
| transactionOtp(body?) | POST dmt/txn/v1/transaction/otp | { senderId, amount, receiver_account_no, receiverIfscCode } |
| transaction(body?) | POST dmt/txn/v1/transaction | Generic transaction submit — same shape as transactionInstant. |
| transactionInstant(body?) | POST dmt/txn/v1/transaction/instant | { senderId, BeneficiaryId, amount, refId, remarks?, otp, receiver_account_no, receiverIfscCode, account_holder_name, receiverMobilenumber? } |
| transactionCharges(body?) | POST dmt/txn/v1/transaction/charges | { senderId, amount } |
| transactionRequery(body?) | POST dmt/txn/v1/transaction/requery | Re-query a pending/ambiguous transaction. |
| refundOtp(body?) | POST dmt/txn/v1/transaction/refundOTP | { transactionId } |
| refund(body?) | POST dmt/txn/v1/refund | Refund request, passed through as-is. |
| initializeAgent(body?) | POST onboarding/dmt/bc/agent/initialize | Create the merchant's DMT ServiceKyc record (idempotent). Vendor/aggregator credentials only. |
| registerAgent(body?) | POST onboarding/dmt/bc/agent/registor | { name, lastname, pancard, dmt?, aeps?, cardpin?, accountopen? } — vendor/aggregator credentials only. |
client.upi
UPI / QR collection. QR generation and status are on /upi/txn/v1; everything else on /merchant/payment.
| Method | HTTP → path | Body / notes |
|---|---|---|
| generateQr(body?) | POST upi/txn/v1/GenerateQR | { amount?, order_id?, merchantId? } — omit amount for a static QR. data.qr_image is a base64 PNG data URL. Send amount as a string. |
| dynamicQr(body?) (deprecated) | POST upi/txn/v1/GenerateQR | Alias of generateQr. |
| collect(body?) | POST merchant/payment/Collection | { amount, order_id, vpa, customer_mobile?, customer_name?, customer_email?, remarks? } |
| smsPay(body?) | POST merchant/payment/SMSpay | { amount, order_id, customer_number, customer_name?, remarks? } |
| upiStatus(body?) | POST upi/txn/v1/UpiStatus | { trans_id, merchantId? } |
| smsStatus(body?) | POST merchant/payment/SMSStatus | { trans_id } |
| refundUpi(body?) | POST merchant/payment/RefundUPI | { tr, amount } |
| refundSms(body?) | POST merchant/payment/RefundSMS | { trans_id } |
| verifyVpa(body?) | POST merchant/payment/verifyVPA | { payer_virtual_address } |
| transactions(body?) | GET merchant/payment/transactions | { page?, limit?, startDate?, endDate?, status?, paymentMethod? } |
| transactionStatusSummary() | GET merchant/payment/transactions/status-summary | Success/failed/pending counts. |
| collectionsByGranularity(body?) | POST merchant/payment/getCollectionsByGranularity | { granularity: day, week, month, year, 5years or 10years } |
client.registration
Merchant self-registration, called with an onboarding vendor's credentials (the new merchant is linked to that vendor server-side).
| Method | HTTP → path | Body / notes |
|---|---|---|
| register(body?) | POST register | Creates the merchant's user + Merchant record. data.existing: true means resume rather than re-register. |
| getServiceCatalog() | GET setups/services/public-catalog | Service catalog for a 'select services' step. |
| getBusinessTypes() | GET admin/onboarding/businessType | Business types. |
| getTurnoverRanges() | GET admin/onboarding/trunOver | Turnover ranges. |
| searchMcc(q: string) | GET admin/onboarding/search/mcc | MCC search — queries shorter than 2 chars are ignored. |
| searchPincode(q: string) | GET admin/onboarding/search/pincode | Pincode search — queries shorter than 2 chars return no data. |
client.onboarding
Post-registration merchant KYC (ISG), called with the merchant's own credentials.
| Method | HTTP → path | Body / notes |
|---|---|---|
| getProfile() | GET merchant/me | The authenticated merchant's profile. |
| getOwnMerchantForOnboarding() | GET onboarding/merchants/onboarding | Own merchant record incl. id, business_type, verified pan/pan_name. |
| sendOtp(body?) | POST send-otp | { phone, email? } |
| verifyOtp(body?) | POST verify-otp | { phone, otp } — data.token null with statusCode '00' means no account for that number. |
| searchMcc(q: string) | GET onboading/search/mcc | MCC search. |
| searchPincode(q: string) | GET onboading/search/pincode | Pincode search. |
| getBusinessTypes() | GET onboading/businessType | Business types. |
| getTurnoverRanges() | GET onboading/trunOver | Turnover ranges. |
| getComplianceCatalog() | GET onboading/compliance | Business types with their required document categories. |
| verifyPan(body?) | POST onboading/verify/pan | { pan, name, dob, fathername? } |
| verifyAccount(body?) | POST onboading/verify/account | { accountNumber, accountHolderName, ifsc, additionalData?, consent? } |
| createServiceKyc(body) | POST services/createServceKyc/{merchantId} | { merchantId, service, interfaceName } — call after the merchant has a MerchantKyc row. 'Service KYC already exists…' means already set up. |
| setVerifyOtp(body?) | POST onboarding/upi/isg/set-verify-otp | { merchantId, interfaceName? } — always replies '00'. |
| isgVerifyPan(body?) | POST onboarding/upi/isg/verify/pan | { pan, name, dob, fathername, merchantId?, interface? } — safe as the first onboarding call. |
| isgVerifyAccount(body?) | POST onboarding/upi/isg/verify/account | { accountHolderName, accountNumber, ifsc, consent, additionalData, merchantId?, interface? } — a 500 can follow a successful verification; check isgComplianceStatus first. |
| isgComplianceStatus(body?) | GET onboarding/upi/isg/compliance/status | { interfaceName? } — server-computed kycStatus/summary/categories. Default body: {"interface":"ISG"}. |
| isgDocUpload(body?) | POST onboarding/upi/isg/compliance/docUpload | { doc_type, doc_number, images: number[], merchantId?, interface? } — AADHAAR needs >= 2 image ids. |
| markKycSubmitted(body?) | POST merchant/kyc/submit | { merchantId? } — marks KYC SUBMITTED (the safe way to finish ISG onboarding). |
| updateBusinessType(body?) | PUT onboarding/business-type | { businessTypeCode } |
| uploadComplianceImage(body?) | POST onboarding/compliance/images | { file (base64 or data: URI), filename, mimetype, docid? } |
| initCompliance(body?) | POST onboarding/init-compliance | { doc_type, doc_number, images, pan?, gst?, settlement? } |
| submitOnboarding(body?) | POST onboarding/Onboarding | Final submission — profile + addresses in one call. |
