Payments — take money on any page
The Payment component adds a secure checkout button to any page. Pick a
gateway, set the amount, and the payer is handed off to the gateway’s own hosted page to pay — so
card details never touch your app. The payment is confirmed on your server and recorded
automatically in a pp_payments table (created for you on first use). Supported gateways:
Stripe, PayPal, Razorpay, Khalti, eSewa, Fonepay, plus a built-in Test simulator and a
Manual / bank-transfer mode.
Contents
- How it works
- Entering your keys
- The gateways
- Where payments are recorded
- Security
- Every property
- Testing
How it works
- The visitor clicks your Pay button. The button sends only the component’s id to the server — never the amount — so the price can’t be changed from the browser.
- Your server creates a payment with the chosen gateway and sends the visitor to the gateway’s hosted checkout (Stripe/PayPal/Khalti/eSewa/Fonepay) or opens its secure widget (Razorpay).
- After paying, the visitor returns and your server confirms the payment authoritatively (retrieving the session, capturing the order, verifying the signature, or looking it up — depending on the gateway). Only a confirmed payment is marked paid.
- The result is saved to
pp_paymentsand the payer sees a receipt (or your own success page).
Entering your keys
Open Payments in the project sidebar. Each gateway shows exactly the fields it needs; secret keys are stored encrypted and are never shown again or sent to the browser. Enable the gateways you want, set your store currency and a default gateway, then rebuild the app to apply. Only the gateways you enable (with their keys) are shipped to the built app.
sk_live_… / rzp_live_…); PayPal, Khalti and eSewa have a
mode field — leave it on test/sandbox and run a sandbox payment before you
flip it to live.The gateways
| Gateway | Notes |
|---|---|
| Test | A built-in simulator — no keys, no real money. It models the full flow so you can build and demo checkout instantly. |
| Manual / Bank transfer | Records the order as pending and shows your own instructions (bank details, cash on delivery). You confirm it later. No gateway needed. |
| Stripe | Global cards via Stripe Checkout (hosted). Test with an sk_test_ key and card 4242 4242 4242 4242. |
| PayPal | Global PayPal. Create a sandbox app for Client ID + Secret; set mode to sandbox to test. |
| Razorpay | Cards, UPI & wallets (India/South Asia). Test with an rzp_test_ key. |
| Khalti | Khalti wallet (Nepal). NPR only. Test keys come from the Khalti dev portal; sandbox uses Khalti test logins. |
| eSewa | eSewa wallet (Nepal). NPR only. Test mode uses eSewa’s sandbox (merchant EPAYTEST) with no keys at all. |
| Fonepay | Fonepay (Nepal) — one hosted page that accepts any bank or wallet (including eSewa). NPR only. Enter your Merchant code (PID) + Shared secret key from Fonepay; set mode to test for the dev-clientapi.fonepay.com sandbox. |
NPR for those
gateways. Online payments need the server’s cURL extension (standard on almost every host).Where payments are recorded
Every attempt is written to a pp_payments table in your app’s database — created automatically the first
time a payment runs (works on MySQL, MariaDB, PostgreSQL, SQLite and SQL Server). Each row has a unique reference, the
gateway, amount, currency, status (pending / paid / failed), the gateway’s transaction id, and the payer’s
details. Build a List page on pp_payments to see and manage them, or reconcile Manual payments there.
Security
- No card data touches your app — the gateway hosts the card page, so your PCI exposure stays minimal.
- The amount is fixed on the server (read from the component by id), so a visitor can’t change the price.
- Every payment is confirmed server-side — a returned browser is never treated as proof; the server retrieves/captures/verifies with the gateway before marking anything paid (fail-closed).
- Secret keys stay on the server, encrypted at rest, and ship only to the built app’s server files.
- Webhooks are signature-verified (Stripe’s signing secret, Razorpay’s webhook secret) so an async confirmation can’t be spoofed.
Every property
| Property | What it does |
|---|---|
| Payment gateway | Which gateway to use (or Test / Manual). Keys come from Settings → Payments. |
| Amount | The amount to charge — fixed on the server (tamper-proof). |
| Currency | 3-letter code (USD, EUR, NPR, INR…). Khalti/eSewa/Fonepay require NPR. |
| Description | Shown to the payer on the checkout page and saved with the record. |
| Button label / Show amount / Align | How the button looks. |
| Success URL | Where to send the payer after paying. Blank = the built-in receipt page. |
| Cancel / failure URL | Where to send the payer if they cancel or it fails. Blank = the built-in page. |
Testing
Start with the Test gateway to see the whole flow end-to-end (button → gateway page → receipt →
recorded payment) without any keys. Then add a real gateway’s sandbox keys and run one sandbox payment
before switching to live. A payment left pending (the payer never returned) can always be reconciled later from
the pp_payments records.