How Rupay works
Rupay is a hosted checkout and payment orchestration platform for businesses that want to accept cards and local payment methods through one consistent payment experience. It connects the merchant's application, the customer, payment providers, and the merchant's fulfillment system without making each merchant build and maintain those connections independently.
Rupay owns the payment journey: it creates a secure checkout, presents the available ways to pay, verifies the provider's result, records the payment lifecycle, and tells the merchant when a payment is confirmed. The merchant continues to own its customer relationship, orders, subscriptions, donations, invoices, and fulfillment.
A customer reaching a success page is not proof of payment. A payment is complete only after Rupay verifies the provider result and reports the Checkout Session as paid.
What Rupay is
Rupay combines three parts of a payment system in one product:
- A customer-facing checkout that clearly presents the merchant, purchase, total, currency, and eligible payment methods.
- A merchant integration layer with an API for dynamic Checkout Sessions, reusable payment links for fixed pricing, and signed webhooks for reliable fulfillment.
- An operations layer that tracks sessions and payments across providers, keeps test and live environments separate, and gives operators tools to investigate and reconcile incomplete flows.
The result is a single boundary between a merchant's business system and the different services that actually move money. The merchant integrates with Rupay's payment lifecycle; Rupay handles the provider-specific journey behind it.
One checkout, two ways to start
Rupay supports two complementary ways to collect a payment.
| Checkout Session | Reusable payment link | |
|---|---|---|
| Best for | A dynamic order, donation, invoice, or one-time payment created by another application | A fixed product, service, membership, or contribution shared with many customers |
| Created by | The merchant's backend through the Rupay API | A merchant in the Rupay dashboard |
| Payment URL | Unique to one payment attempt | The same public link can be shared repeatedly |
| Amount and context | Sent securely by the merchant for that transaction | Configured in Rupay before the link is shared |
| Customer result | One Checkout Session tracks one customer's payment | Rupay creates a separate Checkout Session for every customer who uses the link |
Both paths lead to the same hosted checkout, provider verification, payment status model, reconciliation tools, and signed webhook events.
The complete payment journey
1. The merchant prepares the payment
For a dynamic payment, the merchant's server sends Rupay the amount, currency, line items, customer details, an internal reference, and the URLs to use when the customer finishes or cancels. Rupay returns a unique Checkout Session and its hosted URL.
For a reusable payment link, the merchant selects a product or enters a custom description and price in the Rupay dashboard. The resulting public URL can be placed on a website, sent in a message, or shared as a payment request.
The amount is stored in integer minor units and is controlled by the merchant, not by browser query parameters. A stable idempotency key lets the merchant safely retry a Checkout Session request without creating duplicate payments.
2. Rupay creates the hosted checkout
The customer is sent to a Rupay-hosted page that shows the merchant, what they are paying for, the exact total, the currency, and the available payment methods. A reusable link first collects the customer's required contact details, then creates an individual Checkout Session for that payment attempt.
The checkout is intentionally separate from the merchant's application. This gives customers a consistent payment experience while Rupay handles provider configuration, payment state, security checks, and recovery behavior in one place.
3. The customer chooses how to pay
Rupay can present card payments and eSewa from the same checkout. The exact options depend on the transaction currency, whether the merchant is in a test or live environment, and which provider credentials are configured. Card payments can support NPR and USD; eSewa is shown for eligible NPR payments.
Sensitive payment credentials stay with the payment provider. Card fields are provider-hosted, so the merchant does not receive raw card numbers or security codes. For eSewa, the customer reviews and authorizes the payment in eSewa's flow before returning to Rupay.
4. The payment provider processes the transaction
The selected provider authenticates the customer and attempts the payment. It may approve, decline, or leave the transaction pending while additional processing completes. Rupay keeps the Checkout Session tied to the original merchant, amount, currency, and reference throughout this handoff.
Provider availability is not treated as payment success. Rupay verifies the provider's signed response or webhook and checks that the transaction details match the Checkout Session that initiated it.
5. Rupay reconciles the result
After provider confirmation, Rupay records the successful payment, updates the Checkout Session, and reconciles the corresponding invoice record. Duplicate provider callbacks and safe merchant retries resolve against the same payment identity, which reduces the chance of double creation or double fulfillment.
If a result is delayed, interrupted, or temporarily unavailable, Rupay keeps the payment in a non-final state until it can be confirmed. It does not turn an uncertain browser return into a successful payment.
6. The merchant receives a signed event
When the Checkout Session becomes paid, Rupay sends the merchant a signed
checkout.session.completed webhook. The event contains the Checkout Session
ID, merchant reference, amount, currency, payment method, and confirmed payment
status.
The merchant verifies the signature against the exact request body, deduplicates the event ID, compares the amount and reference with its own records, and only then fulfills the order or records the donation. Failed deliveries are retried, and operators can inspect and replay delivery attempts from Rupay's reconciliation tools.
7. The customer returns to the merchant
Rupay sends the browser to the merchant's configured success or cancellation URL. This redirect is for customer experience only. The signed webhook, or an authenticated retrieval of a paid Checkout Session, remains the source of truth for fulfillment.
Payment states in plain language
| State | What it means | What the merchant should do |
|---|---|---|
| Created or pending payment | The checkout is open, but money is not confirmed | Wait; do not fulfill |
| Paid | Rupay has a provider-confirmed payment | Verify the event and fulfill once |
| Fulfilled | Rupay-side downstream processing has completed, when applicable | Keep the merchant record reconciled |
| Failed | The provider reported an unsuccessful attempt | Let the customer retry through a valid checkout |
| Expired | The payment window ended before confirmation | Create a new session if payment is still needed |
| Cancelled | The checkout was cancelled | Keep the order unpaid |
Only a payment_status of paid means the payment has been confirmed.
What each party is responsible for
| Merchant | Rupay | Payment provider |
|---|---|---|
| Creates the order, invoice, donation, or other business record | Creates and hosts the Checkout Session | Collects sensitive payment credentials |
| Sends the correct amount, currency, and reference | Presents eligible payment methods | Authenticates the customer when required |
| Keeps API and webhook secrets on the server | Verifies and reconciles provider results | Authorizes, captures, approves, or declines the transaction |
| Verifies signed webhooks and fulfills exactly once | Tracks payment state and retries merchant event delivery | Returns signed transaction results to Rupay |
| Handles the product, service, refund policy, and customer support | Provides dashboard visibility and reconciliation controls | Operates the underlying card or local payment network |
Rupay is not the merchant's order-management system, accounting ledger, or shipping system. It supplies the verified payment event those systems need.
Security and reliability by design
- Hosted payment collection: sensitive card fields are handled directly by the configured payment provider rather than the merchant's application.
- Server-only access: merchant API keys and webhook secrets never belong in browser JavaScript.
- Isolated environments: staging and live merchants have separate credentials, data, products, links, sessions, and provider configuration.
- Protected redirects: live success and cancellation URLs must use approved HTTPS origins.
- Idempotent creation: retrying the same creation request with the same identity returns the same operation instead of starting another charge.
- Verified callbacks: Rupay checks provider signatures, status, amount, currency, and transaction references before marking a payment paid.
- Signed merchant events: every webhook can be authenticated, deduplicated, and matched with an immutable merchant record.
- Operational recovery: failed event deliveries are retried and remain visible for reconciliation instead of disappearing silently.
Why businesses use Rupay
Without an orchestration layer, every merchant must build separate provider handoffs, result verification, payment state, retries, webhook delivery, checkout UI, and support tooling. Rupay turns those concerns into one hosted checkout and one merchant-facing lifecycle.
That gives a merchant:
- one integration for card and local payment methods;
- a consistent, branded checkout across providers;
- dynamic API-created payments and no-code reusable links;
- fewer payment states to model in the merchant application;
- a reliable fulfillment signal that does not depend on the browser; and
- one place to investigate sessions, payments, provider events, and webhook delivery.
Getting started
- Create an organization and use its staging environment for integration.
- Choose a reusable payment link for fixed pricing or the Checkout Session API for dynamic payments.
- Configure the payment methods needed for the intended currency.
- Register a webhook endpoint and store its signing secret securely.
- Test successful, failed, cancelled, expired, duplicated, and delayed-payment paths before switching to the separate live environment.
- Fulfill only after a verified paid event, never from the success-page redirect alone.
Read the developer documentation for the API contract, payment links, webhook verification, examples, and production checklist, or open the Rupay dashboard to create a checkout.