API Documentation (UPI) (v2)

You are helping me integrate the Matrix Pay UPI payment gateway API into my application. Use only the specification below. Do not guess at endpoints, field names, or behaviour that is not written here, and do not try to fetch the documentation online: it sits behind an authenticated merchant dashboard and is not publicly reachable.

# 1. Non-negotiable constraints

1. This is a SERVER-TO-SERVER API. It enforces strict request validation and rejects browser-origin requests with CORS errors. Never call it from frontend JavaScript, browser applications, or mobile client code. All API calls must originate from my backend server.
2. The base host is https://matrixpay.vercel.app. THIS IS THE LIVE PRODUCTION HOST. There is no sandbox environment and no mock test mode. Testing is performed directly against production using real low-cost transactions of ₹1. Every transaction interacts with real banking and UPI infrastructure.
3. Every API call is an HTTP POST request with a JSON body and Content-Type: application/json.
4. Authentication is performed via canonical HMAC-SHA256 request signing sent in custom HTTP request headers. Never put the API Secret Key in the JSON request body or URL parameters.
   Required headers on every request:
   - X-Client-Id: My Merchant Live Client ID
   - X-Signature: Hex-encoded HMAC-SHA256 signature
   - X-Timestamp: Unix timestamp in seconds (integer string, valid within ±300s window)
   - X-Nonce: Cryptographically random unique nonce string (8-16 bytes hex, replay protection)
5. HMAC-SHA256 Request Signing Protocol:
   - Canonicalize the JSON body: sort all keys alphabetically (A-Z) recursively, eliminate all whitespace between keys and values.
   - Construct signing string: "${canonical_json_body}.${timestamp}.${nonce}"
   - Compute HMAC-SHA256 using my API Secret Key as the HMAC key. Output the result as a lowercase hexadecimal string.
6. IP Whitelisting: My server's static outbound IP address must be registered in the Developer Hub -> IP Whitelist tab. Requests originating from unlisted IPs are rejected with 403 IP_RESTRICTED.
7. The API Secret Key is confidential. It must never appear in frontend code, version control commits, public repositories, or client-side network inspect tabs. Store it as a secure environment variable on the server.

# 2. Endpoints

All endpoints accept HTTP POST with JSON body and the 4 authentication headers.

## Create UPI Order
POST https://matrixpay.vercel.app/api/v2/payment_gateway/create_upi_order
Headers:
  Content-Type: application/json
  X-Client-Id: <client_id>
  X-Signature: <hmac_sha256_signature>
  X-Timestamp: <timestamp_seconds>
  X-Nonce: <unique_nonce>
Request Body:
{
  "customer_name": "Customer Name",
  "customer_email": "customer@example.com",
  "customer_mobile": "9876543210",
  "amount": 100.00,
  "customer_reference": "YOUR_UNIQUE_ORDER_REF",
  "redirect_url": "https://yourstore.com/checkout/return",
  "service_type": "UPI"
}
Response (HTTP 200 or 201):
{
  "order_id": "MP_MUEC7JEV_4977",
  "customer_reference": "YOUR_UNIQUE_ORDER_REF",
  "amount": 100.00,
  "currency": "INR",
  "payment_url": "https://matrixpay.vercel.app/pay/MP_MUEC7JEV_4977",
  "upi_intent_url": "upi://pay?pa=matrixpay@icici&pn=MatrixPay&am=100.00&tr=MP_MUEC7JEV_4977",
  "qr_data": "upi://pay?pa=matrixpay@icici&pn=MatrixPay&am=100.00&tr=MP_MUEC7JEV_4977",
  "status": "pending",
  "expires_at": "2026-09-24T12:00:00Z"
}

## Check UPI Order Status
POST https://matrixpay.vercel.app/api/v2/payment_gateway/check_upi_order_status
Headers:
  Content-Type: application/json
  X-Client-Id: <client_id>
  X-Signature: <hmac_sha256_signature>
  X-Timestamp: <timestamp_seconds>
  X-Nonce: <unique_nonce>
Request Body:
{
  "order_id": "MP_MUEC7JEV_4977"
}
Response (HTTP 200 or 422):
{
  "order_id": "MP_MUEC7JEV_4977",
  "customer_reference": "YOUR_UNIQUE_ORDER_REF",
  "amount": 100.00,
  "status": "success",
  "paid_at": "2026-09-24T10:15:30Z",
  "utr": "426189912001",
  "gateway_reference": "RZP_PAY_991823"
}

# 3. Order Lifecycle & Statuses

The workflow sequence is:
  1. Generate unique customer_reference on your server (e.g. ORD_${Date.now()}_${randomUUID()}).
  2. Call create_upi_order with canonical HMAC-SHA256 signature headers.
  3. Store order_id and customer_reference in your database.
  4. Redirect user to payment_url or render the upi_intent_url / qr_data for mobile checkout.
  5. Listen for incoming webhook notifications OR poll check_upi_order_status at 5-10s intervals until a terminal status is reached.

There are exactly four order statuses:
  pending    Order created and awaiting payment by customer. Not terminal. Do NOT deliver goods.
  success    Payment verified and captured. Terminal. Fulfil customer order and grant access.
  refunded   Transaction reversed or refunded. Terminal.
  failed     Transaction timed out, expired, or cancelled. Terminal.

# 4. Webhook Handling

Matrix Pay delivers asynchronous HTTP POST event updates to your configured Webhook URL.
Incoming Webhook Headers:
  Content-Type: application/json
  X-Webhook-Signature: <hmac_sha256_hex_signature>
  X-Webhook-Event: payment.success | payment.failed | payment.refunded
  X-Webhook-Id: <delivery_uuid>
Webhook Payload:
{
  "event": "payment.success",
  "order_id": "MP_MUEC7JEV_4977",
  "customer_reference": "YOUR_UNIQUE_ORDER_REF",
  "amount": 100.00,
  "currency": "INR",
  "status": "success",
  "utr": "426189912001",
  "timestamp": 1735689600
}

Signature Verification:
  You MUST verify the signature using the raw request body buffer/string before JSON parsing:
  expected_sig = HMAC_SHA256(secret = API_KEY, message = raw_request_body_string)
  Compare expected_sig with header "X-Webhook-Signature" using a constant-time comparison.
  Reject with 401 Unauthorized if signatures do not match. Respond with 200 OK immediately once verified.

# 5. How I want the integration written

- Implement a single, clean backend client class or module (e.g. MatrixPayClient).
- Keep API credentials strictly in environment variables (MATRIXPAY_CLIENT_ID and MATRIXPAY_API_KEY).
- Persist the customer_reference before sending the request and treat it as the idempotency key.
- Never retry a creation request with a new reference on network timeout — look up the order with check_upi_order_status instead.
- Implement exponential backoff retry logic for transient errors (HTTP 500, 502, 503).
- Do not retry client errors (HTTP 400, 401, 403, 429).
- Never log raw API secrets or sensitive signing keys.

# 6. What I want from you

Ask me which backend language/framework I am using (e.g. Node.js/TypeScript, Python/FastAPI/Django, PHP/Laravel, Go, Java/Spring, C#/.NET) and whether I prefer webhook delivery or status polling, then write the complete, production-ready integration client and webhook handler.