API Documentation

All API requests require a JWT bearer token issued by POST /api/auth/login or POST /api/auth/signup.

Authorization: Bearer <your-jwt-token>

JWT tokens are valid for 7 days. Razorpay endpoints currently allow unauthenticated checkout to make integration easy — auth-only mode coming in v2.

POST /api/razorpay/create-order creates a Razorpay order on your behalf and returns the order_id + key_id needed to open the Razorpay checkout widget on the client.

Request

curl -X POST https://payzoplus.com/api/razorpay/create-order \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1000,
    "currency": "INR",
    "customer_email": "customer@example.com",
    "customer_name": "Customer Name"
  }'

Response

{
  "success": true,
  "order_id": "order_RxxxXXXXXXXXXX",
  "amount": 1000,
  "currency": "INR",
  "key_id": "rzp_live_XXXXXXXXXXXXXX",
  "mode": "live"
}

After the customer completes payment, call POST /api/razorpay/verify-payment with the three values Razorpay returns in the success handler.

{
  "razorpay_order_id": "order_RxxxXXXXXXXXXX",
  "razorpay_payment_id": "pay_RxxxXXXXXXXXXX",
  "razorpay_signature": "<hmac-sha256-signature>"
}

Signature is computed as HMAC-SHA256(order_id|payment_id, secret_key). PayzoPlus verifies server-side before crediting the wallet.

Subscribe to server-to-server events at POST /api/razorpay/webhook. Every request includes an X-Razorpay-Signature header that we verify with the shared webhook secret.

Supported events

• • payment.captured — payment successful, funds with Razorpay
• • payment.failed — payment unsuccessful
• • payment.authorized — captured pending settlement
• • order.paid — order fully paid
• • refund.created — refund initiated

Webhook events are persisted idempotently — duplicates from Razorpay's retry logic are deduped by event_id.

Standard HTTP status codes plus a JSON body with detail.

{ "detail": "Minimum amount is ₹1.00" }

• • 400 — Bad request (invalid amount, malformed body)
• • 401 — Auth failed or signature mismatch
• • 500 — Razorpay API failure (logged & retryable)