Overview

NRPS is a reconciliation and provisioning system for collection requests. Your system creates a payment request, redirects the customer to a hosted payment page, and waits for verification or provider confirmation. Manual methods collect UTR/proof from the customer. Automated UPI requests show a QR code and update automatically after provider confirmation.

Once the transaction is approved or rejected, Nirmaata sends a webhook to your configured endpoint. Your system can also poll the status APIs if needed.

Payment links are single-use. After a customer submits UTR/details, the payment page is locked and cannot be opened or shared again.

1. Merchant checks active payment methods.
2. Merchant creates a payment request.
3. Merchant redirects customer to returned payment URL.
4. Customer pays using the selected method.
5. Manual payments are verified by staff; automated UPI is confirmed by provider update.
6. Nirmaata sends webhook to merchant.
7. Merchant marks order as paid/rejected.

Authentication

Every API request must include both the API key and API secret issued to the merchant. These credentials identify the merchant and protect the API from unauthorized order creation or status access.

X-Api-Key: YOUR_API_KEY
X-Api-Secret: YOUR_API_SECRET

cURL Example

curl -X POST "{BASE_URL}/api/v1/payments" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "X-Api-Secret: YOUR_API_SECRET" \
  -d '{"order_id":"ORDER-1001","amount":1250.00,"customer_name":"Customer Name"}'

Fetch Active Payment Methods

Use this endpoint before creating a payment request if your checkout needs to show only currently available methods. A method is returned only when it is active and mapped to an active collection bank account.

GET /api/v1/payment-methods

{
  "success": true,
  "data": {
    "payment_methods": [
      { "code": "UPI", "name": "UPI", "available": true },
      { "code": "IMPS", "name": "IMPS", "available": true },
      { "code": "RTGS", "name": "RTGS", "available": true }
    ]
  }
}

Create Payment Request

This endpoint creates a hosted payment page. Store the returned payment_id and request_ref in your order table. The returned payment_url should be shown to or redirected for the customer.

If the same merchant sends the same order_id again, the existing payment request is returned instead of creating a duplicate.

If payment_expires_at is omitted, the link expires 24 hours after creation. Once UTR is submitted, the link is considered used even if staff review is still pending.

POST /api/v1/payments
Content-Type: application/json

Request Body

{
  "order_id": "ORDER-1001",
  "amount": 1250.00,
  "customer_id": "CUST-1001",
  "customer_name": "Customer Name",
  "customer_email": "customer@merchantdomain.com",
  "customer_mobile": "9999999999",
  "return_url": "https://merchant.example.com/success",
  "failure_url": "https://merchant.example.com/failed",
  "payment_method": "UPI",
  "payment_expires_at": "2026-06-11 18:30:00"
}

Response

{
  "success": true,
  "payment_id": "PAY202606100101019999",
  "request_ref": "R202606100101019999",
  "order_id": "ORDER-1001",
  "amount": 1250,
  "fee_amount": 25,
  "net_amount": 1225,
  "payment_expires_at": "2026-06-11 18:30:00",
  "status": "Received",
  "payment_origin": "checkout",
  "payment_url": "{BASE_URL}/pay/{token}",
  "email_sent": false
}

Create And Send Link

Use POST /api/v1/payment-links when you want NRPS to optionally send the payment link email using platform SMTP. Send send_email: true to email the customer from NRPS, or send_email: false when your own system will share the returned payment_url.

{
  "order_id": "ORDER-1002",
  "amount": 2500.00,
  "customer_name": "Customer Name",
  "customer_email": "customer@merchantdomain.com",
  "payment_method": "UPI",
  "payment_expires_at": "2026-06-11 18:30:00",
  "send_email": true
}

{
  "success": true,
  "payment_id": "PAY202606100101029999",
  "request_ref": "R202606100101029999",
  "order_id": "ORDER-1002",
  "amount": 2500,
  "fee_amount": 50,
  "net_amount": 2450,
  "payment_expires_at": "2026-06-11 18:30:00",
  "status": "Received",
  "payment_origin": "payment_link",
  "payment_url": "{BASE_URL}/pay/{token}",
  "email_sent": true
}

Automated UPI Flow

Automated UPI is used when UPI is mapped to an automated provider route for the merchant. Your system creates the payment request in the same way as other methods and redirects the customer to the returned payment_url.

The hosted page generates a provider-backed QR code. The customer does not enter UTR or upload proof. NRPS updates the request after provider confirmation and sends your configured merchant webhook.

Create Request

POST /api/v1/payments
Content-Type: application/json

{
  "order_id": "ORDER-1001",
  "amount": 1250.00,
  "customer_name": "Customer Name",
  "customer_mobile": "9999999999",
  "payment_method": "UPI",
  "return_url": "https://merchant.example.com/success",
  "failure_url": "https://merchant.example.com/failed"
}

Customer Handling

1. Redirect the customer to payment_url.
2. Customer scans the QR and completes payment.
3. The payment page checks status automatically while open.
4. Your backend should wait for the merchant webhook, or poll status as a backup.

Status Check

Use status APIs when the customer returns to your site or when your system needs to reconcile an open request. For automated UPI, checking status can trigger a provider status refresh if the request is still open.

GET /api/v1/payments/{payment_id}
GET /api/v1/payment-requests/{request_ref}

Cancel And Recreate

If the customer abandons checkout, wants to change order details, or needs a fresh QR, cancel the open automated UPI request and create a new one. Do not reuse the old payment URL after cancellation.

POST /api/v1/payments/{payment_id}/cancel
POST /api/v1/payment-requests/{request_ref}/cancel

Cancellation is allowed only before the request reaches a final state. If payment has already been confirmed, the cancel API returns an error and your system should use the latest status/webhook result.

Source Of Truth

The final merchant-facing source of truth is the NRPS webhook sent to your configured webhook URL. Status APIs are useful for polling and recovery, but your order should be finalized only after verified API status or webhook confirmation from NRPS.

Payment Origins

Every transaction carries payment_origin so merchants and operators can identify how the payment request was created.

More origins can be added later through the normalized payment_origins table.

Customer Redirect

Redirect the customer to payment_url. The hosted page displays the amount and the available payment instructions.

For automated UPI, the page displays a provider-backed QR code and the request updates automatically after payment confirmation. The customer does not submit UTR/proof for automated UPI.

For manual UPI, IMPS, and RTGS, the page displays collection details and asks the customer to submit UTR/reference proof. UTR validation is method-specific:

Duplicate UTR values are rejected for manual methods. After successful manual submission or final automated confirmation, the same payment page URL becomes unavailable.

Status APIs

Use status APIs to poll payment state if your system does not rely only on webhook callbacks. You can check by payment_id or request_ref.

For automated UPI, status checks may trigger a provider status refresh when the transaction is still open. Use this as a backup to webhook delivery, not as the primary customer confirmation mechanism.

GET /api/v1/payments/{payment_id}
GET /api/v1/payment-requests/{request_ref}

{
  "success": true,
  "request": {
    "status": "Approved",
    "request_ref": "R202606100101019999",
    "payment_id": "PAY202606100101019999",
    "order_id": "ORDER-1001",
    "payment_method": "UPI",
    "amount": "1250.00",
    "fee_amount": "25.00",
    "net_amount": "1225.00",
    "payment_expires_at": "2026-06-11 18:30:00"
  },
  "payment": {
    "paid_amount": "1250.00",
    "utr": "123456789012",
    "payment_date": "2026-06-10 01:30:00",
    "verification_status": "Verified",
    "verified_at": "2026-06-10 01:40:00",
    "remarks": "Payment approved"
  }
}

Cancel Payment Request

Use this endpoint when the customer cancels checkout, wants to change the order, or needs a fresh payment request. Cancellation is supported for open automated UPI requests only. Final requests such as approved, settled, rejected, or failed cannot be cancelled.

POST /api/v1/payments/{payment_id}/cancel
POST /api/v1/payment-requests/{request_ref}/cancel

Headers

X-Api-Key: YOUR_API_KEY
X-Api-Secret: YOUR_API_SECRET

Response

{
  "success": true,
  "payment_id": "PAY202606100101019999",
  "request_ref": "R202606100101019999",
  "order_id": "ORDER-1001",
  "status": "Failed",
  "provider_status": "In Process",
  "message": "Payment request cancelled."
}

After cancellation, create a new payment request if the customer needs to pay again. Do not reuse the cancelled payment URL.

Balance Summary

This endpoint returns approved/settled collection summaries for the merchant. Use it for merchant dashboards, reconciliation, and settlement planning.

POST /api/v1/balance-summary

{
  "start_date": "2026-05-01 00:00:00",
  "end_date": "2026-05-03 23:59:59",
  "type": "daily"
}

Service Status & Support

Use the service status endpoint to check NRPS availability before initiating checkout.

GET /api/v1/service-status

{
  "success": true,
  "service": "Nirmaata Reconciliation and Provisioning System (NRPS)",
  "status": "live",
  "database": "ok",
  "timestamp": "2026-06-27T10:30:00+05:30"
}

Merchants can raise support tickets through API. Failed transaction tickets require both request_id and utr.

POST /api/v1/support/tickets

{
  "category": "failed_transaction",
  "priority": "high",
  "request_id": "R202606100101019999",
  "utr": "180127144274",
  "subject": "Customer debited but payment not approved",
  "message": "Customer has shared bank confirmation, but the payment is still pending."
}

Supported categories are failed_transaction, refund, technical, settlement, payout, and other.

Webhook

Nirmaata sends a webhook when a submitted payment is approved, rejected, or failed by an authorized reviewer. Your system should verify the signature before updating the order.

Headers

X-Nirmaata-Webhook-Id: evt_xxx
X-Nirmaata-Webhook-Timestamp: 1780000000
X-Nirmaata-Webhook-Signature: sha256={hmac}

Payload

{
  "event": "payment.approved",
  "event_id": "evt_9f4b6e2d7c8a1b2c3d4e5f60",
  "payment_id": "PAY202606100101019999",
  "request_ref": "R202606100101019999",
  "order_id": "ORDER-1001",
  "amount": "1250.00",
  "utr": "123456789012",
  "status": "approved",
  "timestamp": "2026-06-10T01:40:00+00:00"
}

Verification

1. Read the raw JSON body exactly as received.
2. Read X-Nirmaata-Webhook-Timestamp.
3. Build the string: timestamp + "." + raw_json_payload.
4. Generate HMAC SHA-256 using your webhook secret.
5. Prefix with sha256=.
6. Compare with X-Nirmaata-Webhook-Signature.

sha256=<hmac_sha256(timestamp + "." + raw_json_payload, webhook_secret)>

Webhook retries reuse the same event ID, timestamp, payload, and signature. Retry actions are stored in the audit trail.

Error Codes

API failures return a stable error_code along with the HTTP status and readable message. Integrations should use error_code for program logic and show message only where suitable.

{
  "success": false,
  "error_code": "DUPLICATE_UTR",
  "message": "This UTR has already been submitted"
}

Settlements & Payouts

Settlements and payouts are managed in the NRPS portal for reconciliation. These are operational records and do not change the merchant payment API identifiers.

Security Notes

• Never expose API secret or webhook secret in frontend code.
• Verify every webhook signature before provisioning an order.
• Reject old webhook timestamps to reduce replay risk.
• Use merchant IP/domain whitelisting where possible.
• Treat duplicate UTR as suspicious and do not provision twice.
• All API attempts are logged, including invalid credentials and blocked IP/domain attempts.
• API errors stay JSON for integrations. Browser/payment-page errors are shown as branded HTML pages.

Status Values