ERP Partner API Contract
This document defines the APIs that DemandPay requires from ERP partners to enable automated customer sync, bill
collection, payment posting, and plan management.
DemandPay will call these APIs on your system. You provide the base URL and authentication credentials. We handle
the rest.
Authentication
DemandPay supports the following authentication mechanisms. Provide whichever your system uses:
Method How it works
You provide a static or rotating token. We send it as Authorization:
Bearer Token
Bearer <token> header.
You provide an API key. We send it as a custom header (e.g. X-API-Key:
API Key
<key>).
API Key + You provide a key-secret pair. We send both as custom headers or use
Secret them for request signing (HMAC, JWS, etc).
Username + You provide app-level credentials. We send them as custom headers or
Password use HTTP Basic Auth.
Important: These are application-level credentials for server-to-server communication, not end-user credentials.
Provide one set of credentials per business/operator that we integrate.
Base URL
You provide a base URL per environment (staging, production). All API endpoints below are relative to this base URL.
Example: [Link]
API Summary
# API Method Purpose
Sync all customers — we need name, unique ID, mobile,
1 Get Customer List GET
email
Fetch Invoice for a
2 GET Get outstanding bills/invoices for a specific customer
Customer
# API Method Purpose
After we collect payment, we post it back to your system
3 Post Payment POST
to mark the bill as paid
Check Payment Verify whether a payment we posted was processed
4 GET
Status successfully on your side
5 Get Plans GET Fetch available subscription/service plans for a business
Renew Plan for a Renew or change a customer's plan — with or without
6 POST
Customer payment
1. Get Customer List
Why we need this: We periodically sync your customer database to enable bill lookup, notifications, and payment
collection. This runs as a batch job (typically daily).
What we need: All customers for a given business/operator, with at minimum: a unique customer identifier, full name,
mobile number, and email.
Endpoint
GET /customers
Search & Filter Parameters
We need the ability to search and filter customers efficiently. Please support the following query parameters:
Parameter Type Required Description
Search by customer name, mobile number, email, or unique
search string No
ID (partial match)
status string No Filter by customer status: active, inactive. Defaults to all
page integer No Page number for pagination. Defaults to 1
page_size integer No Records per page. Defaults to 50, max 200
Note: The search parameter should support partial matching across name, mobile, email, and customer unique
ID. This allows us to look up customers quickly during real-time operations (e.g. customer calls in to pay a bill).
Required Fields in Response
Each customer object must include:
Field Type Required Description
Your system's unique identifier for the
customer_id string Yes
customer
Field Type
Required Description
customer_name YesstringFull name of the customer
customer_mobile YesstringMobile number (10 digits, no country code)
customer_email No stringEmail address
Account number, subscriber ID, or username
customer_unique_id string Yes — the identifier your customers know and
use
What this identifier is called (e.g. "Account
customer_unique_id_name string Yes
Number", "Subscriber ID", "Username")
status string Yes active or inactive
Note: You may include additional fields beyond these. We will store and map them as needed.
Example Response
{
"status": "success",
"data": {
"total_count": 2,
"customers": [
{
"customer_id": "CUST-5678",
"customer_name": "John Doe",
"customer_mobile": "9876543210",
"customer_email": "[Link]@[Link]",
"customer_unique_id": "SUB-001234",
"customer_unique_id_name": "Subscriber ID",
"status": "active"
},
{
"customer_id": "CUST-5679",
"customer_name": "Jane Smith",
"customer_mobile": "9876543211",
"customer_email": null,
"customer_unique_id": "SUB-001235",
"customer_unique_id_name": "Subscriber ID",
"status": "active"
}
]
},
"meta": {
"page": 1,
"page_size": 50,
"total_pages": 1
}
}
Error Responses
HTTP Status Code Description
401 UNAUTHORIZED Invalid or expired authentication credentials
404 NOT_FOUND No customers found
2. Fetch Invoice for a Customer
Why we need this: When a customer wants to pay their bill, we fetch their current outstanding invoice from your system
to show the correct amount and due date.
What we need: Given a customer identifier, return their current outstanding invoice/bill with amount, due date, and a
unique bill/invoice number.
Endpoint
GET /invoices
Request Parameters
Parameter Type Required Description
The customer's unique identifier (as returned by Get
customer_id string Yes
Customer List)
Required Fields in Response
Each invoice object must include:
Field Type Required Description
invoice_id string Yes Unique invoice/bill identifier in your system
customer_id string Yes Customer this invoice belongs to
customer_name string No Customer name (for verification)
invoice_date string Yes Date the invoice was generated (format: YYYY-MM-DD)
due_date string Yes Payment due date (format: YYYY-MM-DD)
amount number Yes Total amount due
currency string No Currency code (defaults to INR)
status string Yes unpaid, partial, paid, or overdue
paid_amount number No Amount already paid (for partial payments)
balance_due number No Remaining amount to be paid
billing_period object No { "start": "YYYY-MM-DD", "end": "YYYY-MM-DD" }
Example Response
{
"status": "success",
"data": {
"invoices": [
{
"invoice_id": "INV-2026-001234",
"customer_id": "CUST-5678",
"customer_name": "John Doe",
"invoice_date": "2026-01-05",
"due_date": "2026-01-20",
"amount": 1770.00,
"paid_amount": 0.00,
"balance_due": 1770.00,
"currency": "INR",
"status": "unpaid",
"billing_period": {
"start": "2026-01-01",
"end": "2026-01-31"
}
}
]
}
}
Error Responses
HTTP Status Code Description
401 UNAUTHORIZED Invalid or expired authentication credentials
404 NOT_FOUND No invoices found for this customer
3. Post Payment for an Invoice
Why we need this: After we successfully collect payment from the customer (via UPI, card, etc.), we need to post this
payment back to your system so your records are updated and the customer's account reflects the payment.
What we send: The invoice ID, customer ID, amount paid, payment date, payment method, and our transaction
reference.
Endpoint
POST /invoices/payments
Request Body
Field Type Required Description
The invoice being paid (as returned by Fetch
invoice_id string Yes
Invoice)
customer_id string Yes Customer identifier
payment_amount number Yes Amount paid
payment_date string Yes Date of payment (format: YYYY-MM-DD)
payment_method string Yes upi, card, bank_transfer, cash, or cheque
Our unique transaction ID — use this for
transaction_reference string Yes
reconciliation
remarks string No Additional notes
Example Request
{
"invoice_id": "INV-2026-001234",
"customer_id": "CUST-5678",
"payment_amount": 1770.00,
"payment_date": "2026-01-14",
"payment_method": "upi",
"transaction_reference": "DP-TXN-123456789"
}
Expected Success Response
{
"status": "success",
"data": {
"payment_id": "PAY-2026-000567",
"invoice_id": "INV-2026-001234",
"invoice_status": "paid",
"invoice_balance": 0.00
},
"message": "Payment recorded successfully"
}
Error Responses
HTTP
Code Description
Status
400 VALIDATION_ERROR Invalid or missing fields in request
HTTP
Code Description
Status
Payment amount is more than the outstanding
400 PAYMENT_EXCEEDS_BALANCE
balance
401 UNAUTHORIZED Invalid or expired authentication credentials
404 INVOICE_NOT_FOUND Invoice ID does not exist
Payment with this transaction reference was
409 DUPLICATE_PAYMENT
already recorded
Important: The 409 DUPLICATE_PAYMENT response is critical. If we retry a payment (due to network issues),
your system must detect the duplicate transaction_reference and return 409 instead of recording it twice.
4. Check Payment Status
Why we need this: After posting a payment, we may need to verify its status — especially if the payment processing on
your side is asynchronous, or if we need to confirm the status for customer support or reconciliation.
What we send: The payment ID or transaction reference from the Post Payment response.
Endpoint
GET /invoices/payments/{payment_id}
Path Parameters
Parameter Type Required Description
Payment ID (from your system) or the
payment_id string Yes
transaction_reference we sent
Expected Success Response
{
"status": "success",
"data": {
"payment_id": "PAY-2026-000567",
"invoice_id": "INV-2026-001234",
"customer_id": "CUST-5678",
"payment_amount": 1770.00,
"payment_status": "success",
"invoice_status": "paid",
"invoice_balance": 0.00,
"created_at": "2026-01-14T10:30:00Z"
}
}
Payment Status Values
Status Description
success Payment processed and invoice updated
pending Payment is being processed (not yet reflected in invoice)
failed Payment processing failed — invoice remains unpaid
refunded Payment was reversed/refunded
Error Responses
HTTP Status Code Description
401 UNAUTHORIZED Invalid or expired authentication credentials
404 PAYMENT_NOT_FOUND No payment found with this ID or transaction reference
5. Get Plans
Why we need this: We display available plans to customers so they can choose a plan for new subscription or renewal.
We also need plan details for automated renewals.
What we need: All active plans for a given business/operator, including plan name, price, duration, speed, and data
limits.
Endpoint
GET /plans
Request Parameters
Parameter Type Required Description
status string No Filter by active or inactive. Defaults to active
Required Fields in Response
Each plan object must include:
Field Type Required Description
plan_id string Yes Unique plan identifier in your system
plan_name string Yes Display name of the plan
plan_price number Yes Base price (before tax)
plan_duration integer Yes Duration value (e.g. 30, 90, 365)
plan_duration_unit string Yes Duration unit: days, months, or years
total_price number Yes Final price including tax
currency string No Currency code (defaults to INR)
status string Yes active or inactive
Optional but recommended:
Field Type Description
plan_description string Human-readable plan description
speed string Internet speed (e.g. "100 Mbps")
data_limit string Data cap (e.g. "Unlimited", "3000 GB")
tax number Tax amount
Example Response
{
"status": "success",
"data": {
"plans": [
{
"plan_id": "PLAN-001",
"plan_name": "100 Mbps Unlimited",
"plan_description": "100 Mbps unlimited broadband with no FUP",
"plan_price": 799.00,
"plan_duration": 30,
"plan_duration_unit": "days",
"speed": "100 Mbps",
"data_limit": "Unlimited",
"tax": 143.82,
"total_price": 942.82,
"currency": "INR",
"status": "active"
}
]
}
}
Error Responses
HTTP Status Code Description
401 UNAUTHORIZED Invalid or expired authentication credentials
404 NOT_FOUND No plans found
6. Renew Plan for a Customer
Why we need this: When a customer's plan is expiring or they want to switch plans, we initiate the renewal on your
system. This supports two scenarios:
With payment: We have already collected the payment from the customer. We send the payment details along
with the renewal request so your system can activate the new plan and record the payment in one step.
Without payment: The renewal is initiated without a payment — for example, a free upgrade, a loyalty offer, or
cases where payment has already been collected through a separate channel.
Endpoint
POST /customers/{customer_id}/renew
Path Parameters
Parameter Type Required Description
customer_id string Yes Customer identifier (as returned by Get Customer List)
Request Body
Field Type Required Description
Plan to renew or switch to (as returned by Get
plan_id string Yes
Plans)
renewal_type string Yes with_payment or without_payment
Required when renewal_type is with_payment.
payment_amount number Conditional
The amount paid.
Required when renewal_type is with_payment.
payment_method string Conditional
Values: upi, card, bank_transfer, cash, cheque
Required when renewal_type is with_payment.
transaction_reference string Conditional
Our unique transaction ID for reconciliation.
When the new plan should start (format: YYYY-
effective_date string No
MM-DD). Defaults to today.
remarks string No Additional notes
Example Request — With Payment
{
"plan_id": "PLAN-002",
"renewal_type": "with_payment",
"payment_amount": 1178.82,
"payment_method": "upi",
"transaction_reference": "DP-TXN-987654321",
"remarks": "Upgrade to 200 Mbps"
}
Example Request — Without Payment
{
"plan_id": "PLAN-001",
"renewal_type": "without_payment",
"remarks": "Free renewal - loyalty offer"
}
Expected Success Response
{
"status": "success",
"data": {
"renewal_id": "REN-2026-000123",
"customer_id": "CUST-5678",
"previous_plan": {
"plan_id": "PLAN-001",
"plan_name": "100 Mbps Unlimited",
"expiry_date": "2026-01-31"
},
"new_plan": {
"plan_id": "PLAN-002",
"plan_name": "200 Mbps Unlimited",
"start_date": "2026-02-01",
"expiry_date": "2026-03-02"
},
"renewal_type": "with_payment",
"payment_id": "PAY-2026-000890",
"renewal_status": "active"
},
"message": "Plan renewed successfully"
}
Error Responses
HTTP
Code Description
Status
Invalid or missing fields (e.g. payment_amount missing
400 VALIDATION_ERROR
for with_payment)
401 UNAUTHORIZED Invalid or expired authentication credentials
404 CUSTOMER_NOT_FOUND Customer ID does not exist
404 PLAN_NOT_FOUND Plan ID does not exist or is inactive
409 ACTIVE_RENEWAL_EXISTS Customer already has a pending renewal in progress
General Notes for ERP Partners
1. Response format: All responses should be JSON. Use the status field ("success" or "error") at the top
level.
2. Date formats: Use YYYY-MM-DD for dates and ISO 8601 (YYYY-MM-DDTHH:mm:ssZ) for timestamps.
3. Currency: Default to INR unless otherwise specified.
4. Idempotency: The Post Payment API (API #3) must be idempotent. If we send the same
transaction_reference twice, your system should return the existing payment record (or 409) — never
create a duplicate.
5. Pagination: For list endpoints (customers, invoices, plans), support page and page_size parameters. Return
total_count in the response so we know how many pages to fetch.
6. Error responses: Always include a meaningful code and message in error responses. The code should be a
machine-readable constant (e.g. INVOICE_NOT_FOUND), not an HTTP status code.
7. Environments: Provide separate base URLs and credentials for staging/testing and production.
HTTP Status Codes Summary
Code Description
200 Success — request completed
201 Created — resource created successfully
400 Bad Request — invalid parameters or payload
401 Unauthorized — authentication failed
404 Not Found — resource not found
409 Conflict — duplicate or conflicting data
500 Internal Server Error