REST API & Webhook Documentation (v1)

Base API URL: https://api.distropay.online/api/v1

1. Integration Execution Sequence

Payment processing follows a 4-step API lifecycle (from initial order creation to webhook callback):

Create Payment Order

First Request: Your server calls POST /api/v1/orders with order amount, unique order_id, and redirect URL.

Customer Payment

Second Action: Redirect customer to the returned payment_url to display the dynamic UPI QR code or mobile app intent links.

Instant Webhook Postback

Third Trigger: Customer pays via UPI. DistroPay verifies the bank UTR and dispatches an HTTP POST webhook callback to your callbackUrl.

Status & UTR Verification

Fourth Query: Your server queries GET /api/v1/orders/{orderId} to verify payment status and store bank UTR.

2. System Interaction Sequence Diagram

Merchant Server                DistroPay API                  Customer                     Merchant Bank
      │                              │                           │                           │
      ├───── 1. Create Order ───────►│                           │                           │
      │    (POST /api/v1/orders)     │                           │                           │
      │                              │                           │                           │
      │◄──── 2. payment_url ─────────┤                           │                           │
      │                              │                           │                           │
      │                              ├───── 3. Redirect ────────►│                           │
      │                              │    (UPI QR / Intent)      │                           │
      │                              │                           │                           │
      │                              │                           ├──── 4. Pays via UPI ─────►│
      │                              │                           │                           │
      │                              │◄────────────────── 5. Direct Settlement ──────────┤
      │                              │                           │                           │
      │◄──── 6. Webhook Callback ────┤                           │                           │
      │      (HTTP POST to URL)      │                           │                           │
      │                              │                           │                           │
      ├───── 7. Verify Status ──────►│                           │                           │
      │  (GET /api/v1/orders/ORD_X)  │                           │                           │
      │                              │                           │                           │
      │◄──── 8. Bank UTR & Status ───┤                           │                           │

3. Authentication

Pass your Secret Key (sk_live_...) via the x-secret-key header or Authorization: Bearer token in all API requests.

x-secret-key: sk_live_your_secret_key_here
Content-Type: application/json

POST

Step 1: Create Payment Order

https://api.distropay.online/api/v1/orders

Parameter	Type	Required	Constraints & Format	Description	Example
amount	Number	Yes	Min ₹1.00, Max ₹1,00,000.00 (Max 2 decimals)	Order amount in INR	500.00
order_id	String	Yes	Length 5-50, Pattern: ^[a-zA-Z0-9_-]+$	Unique tracking ID from your merchant system	"ORD_1785291283"
redirect_url	String	Yes	Valid URI starting with http:// or https://	Customer redirect destination after completion	"https://site.com/success"
customer_mobile	String	Optional	Exactly 10 digits, Pattern: ^[6-9]\d{9}$	Customer 10-digit mobile number	"9876543210"
remark1	String	Optional	Max 100 characters	Custom remark 1 (e.g. Order / Customer ID)	"Customer_Order_42"
remark2	String	Optional	Max 100 characters	Custom remark 2 (e.g. Plan / Service name)	"Plan_Renewal"
upi	Number	Optional	Enum [1, 2, 3] (Default: 1)	Slot routing index	1

cURL Request

curl -X POST "https://api.distropay.online/api/v1/orders" \
  -H "x-secret-key: sk_live_your_secret_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 500.00,
    "order_id": "ORD_1785291283",
    "redirect_url": "https://yourwebsite.com/payment-success",
    "customer_mobile": "9876543210",
    "remark1": "Customer_Order_42",
    "remark2": "Plan_Renewal",
    "upi": 1
  }'

Response JSON (200 OK)

{
  "status": true,
  "message": "Order Created Successfully",
  "result": {
    "order_id": "ORD_1785291283",
    "payment_url": "https://distropay.online/pay/ORD_1785291283",
    "amount": 500.00,
    "status": "PENDING"
  }
}

Step 2: Webhook Verification & Handling Guide

As soon as a customer pays via UPI, DistroPay verifies the bank transaction and dispatches an instant HTTP POST callback to your merchant callbackUrl.

How Webhook Logic Works on Your Server:

Parse Payload: Extract parameters (status, order_id, amount, utr) from incoming POST body.
Verify Status: Confirm that status === "SUCCESS".
Audit Amount: Verify amount matches the order amount stored in your system database.
Idempotency Check: If order_id is already marked as paid in your DB, return HTTP 200 OK immediately without fulfilling again.
Save Bank UTR: Update order status to SUCCESS and store the 12-digit bank utr.
Respond fast: Return plain text OK with HTTP 200 OK within 5 seconds.

Sample Webhook POST Payload (application/x-www-form-urlencoded)

POST https://yourwebsite.com/api/callback
Content-Type: application/x-www-form-urlencoded

status=SUCCESS&order_id=ORD_1785291283&customer_mobile=9876543210&amount=500.00&remark1=Customer_Order_42&remark2=Plan_Renewal&utr=4219827391823

Developer Webhook Verification Checklist:

HMAC-SHA256 Signature Verification: Verify incoming x-distropay-signature (or x-signature) header against your Secret Key (sk_live_...).
Status Check: Verify that status === "SUCCESS" before marking order as paid.
Amount Audit: Audit that the received amount matches your database expected order amount.
Record UTR: Store the 12-digit bank utr number in your system for accounting & audit trails.
Fast Acknowledgment: Your webhook endpoint must return HTTP 200 OK with plain text OK within 5 seconds.
Idempotency Handling: If a duplicate webhook is received for an already fulfilled order, acknowledge with HTTP 200 OK without duplicating fulfillment.

HMAC-SHA256 Webhook Signature Verification Code (Node.js)

// HMAC-SHA256 Webhook Signature Verification (Node.js Example)
const crypto = require('crypto');

function verifyDistroPayWebhook(rawPayload, receivedSignature, merchantSecretKey) {
  // Compute HMAC-SHA256 hex digest using your Merchant Secret Key (sk_live_...)
  const expectedSignature = crypto
    .createHmac('sha256', merchantSecretKey)
    .update(rawPayload)
    .digest('hex');

  // Perform timing-safe equality check against x-distropay-signature header
  return crypto.timingSafeEqual(
    Buffer.from(receivedSignature.trim()),
    Buffer.from(expectedSignature.trim())
  );
}

Automatic Webhook Retry Schedule

If your webhook endpoint returns a non-2xx status code or times out, DistroPay automatically retries up to 5 times: +10s, +30s, +2m, +10m, +1h.

GET

Step 3: Check Order Status & Bank UTR

https://api.distropay.online/api/v1/orders/ORD_1785291283

cURL Request

curl -X GET "https://api.distropay.online/api/v1/orders/ORD_1785291283" \
  -H "x-secret-key: sk_live_your_secret_key_here"

Response JSON (200 OK)

{
  "status": true,
  "result": {
    "order_id": "ORD_1785291283",
    "status": "SUCCESS",
    "amount": 500.00,
    "utr": "4219827391823",
    "gateway_txn": "TXN_9812739182",
    "method": "PAYTM"
  }
}

4. Machine-Readable Error Codes & Responses

All failed API requests return standard HTTP error status codes (400, 401, 404, 409, 429, 500) with a machine-readable JSON error payload containing code and message.

HTTP Status	Error Code	Description & Cause
400 Bad Request	VALIDATION_ERROR	Field constraint failure (e.g. Amount out of bounds, invalid 10-digit mobile number, invalid redirect URL format).
400 Bad Request	SLOT_NOT_UNLOCKED	Requested slot index (`upi=2` or `upi=3`) exceeds your subscription plan allowance. Purchase additional slots in Plan settings.
400 Bad Request	SLOT_NOT_CONNECTED	Requested slot index is unlocked but has no active bank gateway connected under UPI Settings.
401 Unauthorized	INVALID_API_KEY	Missing, invalid, or inactive Secret Key (`sk_live_...`) in headers.
404 Not Found	ORDER_NOT_FOUND	The requested order ID does not exist in system database.
409 Conflict	DUPLICATE_ORDER	Submitting an `order_id` that has already been created under your merchant account.
429 Too Many Requests	QUOTA_EXCEEDED	Monthly 3,000 order limit reached and wallet balance is below ₹100 for automatic top-up.
500 Internal Error	INTERNAL_SERVER_ERROR	Unhandled server exception or bank gateway connectivity error.

Sample Error Response (400 Validation Error)

{
  "status": false,
  "code": "VALIDATION_ERROR",
  "message": "Amount must be a numeric value between ₹1.00 and ₹1,00,000.00"
}

Sample Error Response (409 Duplicate Order)

{
  "status": false,
  "code": "DUPLICATE_ORDER",
  "message": "Order ID already exists"
}

GET

Get Merchant Profile & Balance

https://api.distropay.online/api/v1/merchant

cURL Request

curl -X GET "https://api.distropay.online/api/v1/merchant" \
  -H "x-secret-key: sk_live_your_secret_key_here"

Response JSON (200 OK)

{
  "status": true,
  "user": {
    "name": "Merchant Name",
    "email": "merchant@example.com",
    "company": "Company Name",
    "walletBalance": 250.00,
    "extraUpiSlots": 2,
    "maxUpiSlotsAllowed": 3,
    "monthlyOrderCount": 142,
    "monthlyOrderLimit": 3000,
    "status": "Active",
    "expiry": "2027-01-01T00:00:00.000Z",
    "callbackUrl": "https://yourwebsite.com/api/callback"
  }
}

NPCI Regulatory Compliance & Legal Disclaimers

Operational guidelines mandated by NPCI and RBI banking standards

0% MDR Policy

In compliance with NPCI and Ministry of Finance mandates, zero Merchant Discount Rate (MDR) applies to standard UPI transactions processed directly through authorized NPCI banking handles.

P2P & P2M Limits

Standard UPI transactions are subject to NPCI daily per-user ceiling limits (typically INR 1,00,000 per 24-hour cycle) depending on issuing bank policies and account category.

Merchant Responsibility

Merchants must ensure full compliance with AML/KYC guidelines. Unauthorized commercial activity or misuse of individual P2P handles for high-frequency commerce is strictly prohibited under banking regulations.

Fraud Liability Disclaimer

DistroPay operates as an automated UPI payment collection interface and gateway integration provider. Users and merchants remain sole custodians of bank account credentials, session keys, and transaction UTR verifications. DistroPay is not responsible for unauthorized bank chargebacks, commercial disputes, or fraudulent UTR submissions.