API Reference

Complete reference for the SeedhaPe HTTP API. Base URL: https://seedhape.onrender.com

Authentication

All merchant endpoints require a Bearer API key in the Authorization header. Keys start with sp_live_ (production) or sp_test_ (sandbox).

HTTP header

Authorization: Bearer sp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

⚠️

Warning: Never expose your API key in client-side code or commit it to source control. Store it as a server-side environment variable (SEEDHAPE_API_KEY). Public endpoints under /v1/pay/* require no authentication.

Errors

All error responses return a JSON body with error (human-readable message) and code (machine-readable constant).

Error response body

{
  "error": "Order not found",
  "code": "ORDER_NOT_FOUND"
}

400

Validation error — check the error.code for details

401

Invalid or missing API key

404

Resource not found or belongs to another merchant

503

Merchant Android device is offline — payments temporarily unavailable

Orders — Authenticated

POST/v1/orders🔑 Auth required

Create a payment order

Creates a new UPI payment order. Returns a UPI deep-link and QR code for the customer to pay. The order ID is embedded in the UPI transaction note (tn) for reliable auto-matching.

Request body (application/json)

amountintegerrequiredbody

Amount in paise. ₹1 = 100 paise. So ₹499 = 49900.

descriptionstringbody

Shown on the hosted payment page and in some UPI apps. Max 100 characters.

externalOrderIdstringbody

Your own order ID for deduplication. Echoed back in all webhook payloads.

expectedSenderNamestringbody

Payer's name as shown in their UPI app. Strongly recommended — used as a fallback matching signal when the UPI transaction note is unavailable.

customerEmailstring (email)body

Customer email address. Stored on the order for reference.

customerPhonestringbody

Customer phone number. E.g. +919876543210.

expiresInMinutesintegerbody

Order time-to-live in minutes. Defaults to 30. After expiry the order moves to EXPIRED and cannot be paid.

metadataobjectbody

Arbitrary JSON object. Stored on the order and echoed verbatim in all webhook payloads. Useful for passing userId, planKey, etc.

Example request

curl

curl -X POST "https://seedhape.onrender.com/v1/orders" \
  -H "Authorization: Bearer sp_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 49900,
    "description": "Pro plan subscription",
    "externalOrderId": "your_order_123",
    "expectedSenderName": "Rahul Sharma",
    "expiresInMinutes": 15,
    "metadata": { "userId": "usr_abc", "planKey": "PRO" }
  }'

201 Response

application/json

{
  "id": "sp_ord_ab12cd34ef56",
  "amount": 49900,
  "originalAmount": 49900,
  "currency": "INR",
  "description": "Pro plan subscription",
  "status": "CREATED",
  "upiUri": "upi://pay?pa=merchant@ybl&pn=My+Store&am=499.00&tn=sp_ord_ab12cd34ef56&cu=INR",
  "qrCode": "data:image/png;base64,iVBORw0KGgoAAAANSUh...",
  "expiresAt": "2026-03-15T12:34:56.000Z",
  "createdAt": "2026-03-15T12:19:56.000Z",
  "externalOrderId": "your_order_123",
  "metadata": { "userId": "usr_abc", "planKey": "PRO" }
}

Responses

201

Order created — returns full OrderData object

400

Validation error (e.g. missing amount, amount <= 0)

401

Invalid or missing API key

503

Merchant device is offline

GET/v1/orders/{orderId}🔑 Auth required

Get order details

Returns the full order object including status, amounts, QR code, and metadata. Use this for server-side order lookup.

Path parameters

orderIdstringrequiredpath

The SeedhaPe order ID (e.g. sp_ord_ab12cd34ef56).

Example request

curl

curl "https://seedhape.onrender.com/v1/orders/sp_ord_ab12cd34ef56" \
  -H "Authorization: Bearer sp_live_YOUR_KEY"

Responses

200

Order found — returns full OrderData object

401

Invalid or missing API key

404

Order not found or belongs to another merchant

GET/v1/orders/{orderId}/status🔑 Auth required

Poll order status

Lightweight status poll. Returns only id, status, amount, and verifiedAt. Prefer this over fetching the full order when polling from your backend.

Path parameters

orderIdstringrequiredpath

The SeedhaPe order ID.

Example request

curl

curl "https://seedhape.onrender.com/v1/orders/sp_ord_ab12cd34ef56/status" \
  -H "Authorization: Bearer sp_live_YOUR_KEY"

200 Response

application/json

{
  "id": "sp_ord_ab12cd34ef56",
  "status": "VERIFIED",
  "amount": 49900,
  "verifiedAt": "2026-03-15T11:11:09.000Z"
}

Responses

200

Returns id, status, amount, and verifiedAt

401

Invalid API key

404

Order not found

Payment Page — Public (no auth)

GET/v1/pay/{orderId}

Get public order data

Returns payment page data for the hosted checkout UI. No authentication required — safe to call from the browser. Returns 503 if the merchant device is offline.

Path parameters

orderIdstringrequiredpath

The SeedhaPe order ID.

200 Response

application/json

{
  "id": "sp_ord_ab12cd34ef56",
  "amount": 49900,
  "originalAmount": 49900,
  "currency": "INR",
  "description": "Pro plan subscription",
  "status": "PENDING",
  "upiUri": "upi://pay?pa=merchant@ybl&am=499.00&tn=sp_ord_ab12cd34ef56&cu=INR",
  "qrCode": "data:image/png;base64,iVBOR...",
  "expiresAt": "2026-03-15T12:34:56.000Z",
  "expectedSenderName": "Rahul Sharma"
}

Responses

200

Order data for payment page (PublicOrderData object)

404

Order not found

503

Merchant device is offline — payments temporarily blocked

POST/v1/pay/{orderId}/expectation

Set expected payer name

Stores the payer's name on the order to improve fallback matching accuracy. Called by the hosted payment page after the customer enters their name. Only valid for CREATED / PENDING / DISPUTED orders.

Path parameters

orderIdstringrequiredpath

The SeedhaPe order ID.

Request body (application/json)

expectedSenderNamestringrequiredbody

The payer's name as it appears in their UPI app. 2–100 characters. Used for fallback matching when the transaction note is missing.

200 Response

application/json

{
  "ok": true,
  "expectedSenderName": "Rahul Sharma"
}

Responses

200

Name saved successfully

400

Validation error or order is in a terminal state (VERIFIED/EXPIRED/etc.)

404

Order not found

POST/v1/pay/{orderId}/screenshot

Upload dispute screenshot

Uploads a screenshot of the UPI payment confirmation. Creates or updates a dispute record for manual review. Only accepted for PENDING or DISPUTED orders. File must be an image ≤ 5 MB.

Path parameters

orderIdstringrequiredpath

The SeedhaPe order ID.

Request body (multipart/form-data)

screenshotfile (binary)requiredbody

Image file in JPEG, PNG, or WebP format. Maximum size 5 MB.

Example request

curl

curl -X POST "https://seedhape.onrender.com/v1/pay/sp_ord_ab12cd34ef56/screenshot" \
  -F "screenshot=@/path/to/payment-confirmation.jpg"

200 Response

application/json

{
  "ok": true,
  "screenshotUrl": "https://cdn.seedhape.com/disputes/sp_ord_ab12cd34ef56.jpg",
  "message": "Screenshot uploaded. Our team will review within 24 hours."
}

Responses

200

Screenshot uploaded, dispute record created/updated

400

No file provided or order is in wrong state

404

Order not found

GET/v1/pay/qr/{orderId}

Get QR code as PNG image

Returns the UPI QR code as a raw PNG image (not a data URL). Useful for embedding in emails, PDFs, or custom UIs. Returns 503 if the merchant device is offline.

Path parameters

orderIdstringrequiredpath

The SeedhaPe order ID.

Example usage

HTML

<img src="https://seedhape.onrender.com/v1/pay/qr/sp_ord_ab12cd34ef56" alt="Pay with UPI" />

Email template (e.g. Nodemailer)

attachments: [{
  filename: 'payment-qr.png',
  path: `https://seedhape.onrender.com/v1/pay/qr/${order.id}`,
}]

Responses

200

PNG image (Content-Type: image/png)

404

Order not found

503

Merchant device is offline

Schemas

OrderStatus

The lifecycle state of a payment order. Terminal states are VERIFIED, RESOLVED, EXPIRED, and REJECTED.

CREATED

Order created, no payment attempt yet

PENDING

Payment notification received, matching in progress

VERIFIED

Payment verified — trigger fulfillment

DISPUTED

Payer claims payment but auto-match failed

RESOLVED

Dispute manually resolved by merchant

EXPIRED

Order TTL elapsed without payment

REJECTED

Dispute rejected by merchant

OrderData

Returned by POST /v1/orders and GET /v1/orders/:id.

idstring

SeedhaPe order ID, e.g. sp_ord_ab12cd34ef56

amountinteger

Final amount in paise (may differ from originalAmount if amount was randomized to aid matching)

originalAmountinteger

The amount you requested when creating the order

currencystring

Always "INR"

statusOrderStatus

Current lifecycle status

upiUristring

UPI deep-link for payment apps. Render as a button on mobile.

qrCodestring

Base64 PNG data URL of the QR code. Use directly as <img src={order.qrCode} />

expiresAtdate-time

ISO 8601 timestamp when the order expires

createdAtdate-time

ISO 8601 creation timestamp

verifiedAtdate-time | null

Set when the payment is confirmed (status = VERIFIED or RESOLVED)

externalOrderIdstring | null

Your own order ID, echoed back

descriptionstring | null

Order description shown on the payment page

metadataobject | null

Arbitrary JSON passed at creation, echoed in all webhook payloads

Webhook Event Types

Events are delivered via HTTP POST to your webhook URL. See the Webhooks section in the main docs for signature verification.

order.verified

Payment confirmed. Trigger order fulfillment. The data object includes utr, senderName, upiApp, verifiedAt.

order.expired

Order TTL elapsed without a verified payment.

order.disputed

Payer claims to have paid but auto-match failed. A dispute screenshot may have been uploaded.

order.resolved

Dispute manually resolved. Check data.status: RESOLVED (approve) or REJECTED (decline).

Looking for the SDK or React integration?

Back to Integration Docs