End-to-End Payment Flow
This page documents the complete payment lifecycle for CellPay UPG — from the customer clicking "Pay Now" to the merchant confirming payment.
The 3 APIs in the Full Flow
| Step | API | Who Calls It |
|---|---|---|
| 1 | GET /upg/payment-methods/{merchantId} | Your backend (on checkout page load) |
| 2 | POST /upg/checkout | Your backend (after customer selects payment method) |
| 3 | GET /upg/check-status/{transactionId} | Your backend (after customer returns via redirect URL) |
Flow Diagram
┌────────────────┐ ┌──────────────────┐ ┌─────────────────────┐
│ Customer / │ │ Your Backend │ │ CellPay UPG │
│ Browser │ │ Server │ │ + Provider │
└───────┬────────┘ └────────┬─────────┘ └──────────┬──────────┘
│ │ │
│ 1. Opens checkout page │ │
│─────────────────────────► │
│ │ 2. GET /upg/payment-methods/{merchantId}│
│ │────────────────────────────►
│ │◄────────────────────────────
│ │ [EBanking, MBanking, │
│ │ CheckoutGateway] │
│ │ │
│ 3. Render payment │ │
│ method options │ │
│◄───────────────────────── │
│ │ │
│ 4. Customer selects │ │
│ method (e.g. eSewa) │ │
│ under CheckoutGateway│ │
│─────────────────────────► │
│ │ │
│ │ 5. Generate HMAC-SHA256 │
│ │ signature (server-side) │
│ │ │
│ │ 6. POST /upg/checkout │
│ │ (multipart/form-data) │
│ │────────────────────────────►
│ │ │
│ 7. CellPay returns │ │
│ Checkout Gateway HTML│ │
│ page to customer │◄────────────────────────────
│◄───────────────────────── │
│ │ │
│ 8. Customer selects │ │
│ specific bank/wallet │ │
│ and completes payment│ │
│─────────────────────────────────────────────────────►
│ │ │
│ │◄────────────────────────────
│ │ Payment confirmed │
│ │ │
│ 9. CellPay redirects │ │
│ customer to your │ │
│ Redirect URL with │ │
│ concatenated TxnID │ │
│◄──────────────────────────────────────────────────────
│ │ │
│ 10. Frontend parses │ │
│ Transaction ID │ │
│─────────────────────────► │
│ │ 11. GET /upg/check-status/ │
│ │ {transactionId} │
│ │────────────────────────────►
│ │◄────────────────────────────
│ │ { paymentStatus: SUCCESS }
│ │ │
│ │ 12. Update order in DB │
│ │ │
│ 13. Success/failure page│ │
│◄───────────────────────── │
Step-by-Step Responsibilities
Your Responsibility
| Step | What You Build |
|---|---|
| 1–3 | Render checkout page with payment methods from the API |
| 4 | Capture the customer's payment method selection |
| 5 | Generate HMAC-SHA256 signature server-side |
| 6 | POST to CellPay Checkout API and return/render the gateway HTML |
| 10 | Frontend page at Redirect URL — parses Transaction ID from URL |
| 11–13 | Backend calls Check Status, updates order, renders result to customer |
CellPay's Responsibility
| Step | What CellPay Handles |
|---|---|
| 7–8 | Checkout Gateway page — payment method selection, bank/wallet sub-options |
| Provider auth | OTP, authentication, payment confirmation |
| 9 | Redirecting customer back to your URL with transaction data |
Key Differences From a Typical JSON REST API
CellPay UPG has some design characteristics your developers should know upfront:
| Characteristic | Detail |
|---|---|
| Checkout sends form-data | Not JSON — use multipart/form-data for POST /upg/checkout |
| Checkout response is HTML | Not a JSON redirect token — CellPay renders the payment page directly |
| Amount in NPR decimal | Not paisa — 89.99 for NPR 89.99 |
| Signature is hex | Not Base64 — 64-character lowercase hex string |
| Transaction ID via redirect | Not a checkout API response field — arrives in the redirect URL callback |
Status code is 1/0 | Not HTTP status codes — check response.data.status === 1 for success |
Order State Machine
[Order Created in your DB]
│
▼
[PENDING] ──── customer closes browser ────► [PENDING — needs reconciliation]
│ │
│ CellPay redirect received │ Background job after 30 min
│ │ → call Check Status API
▼ ▼
Call Check Status API Resolve to final status
│
┌────┴────┐
▼ ▼
[SUCCESS] [FAILED / CANCELLED]
│ │
Fulfil Allow retry
order (new orderId)