PPPHP

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.

Two steps to go live. (1) Enter your gateway keys once in Payments (the project sidebar → Payments). (2) Drop a Payment component (components palette → Sections) onto a page, set the amount + gateway, and rebuild. The Test gateway needs no keys and works immediately.

Contents

How it works

  1. 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.
  2. 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).
  3. 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.
  4. The result is saved to pp_payments and 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.

Keep it in test until you’ve verified. Stripe/Razorpay switch to live automatically when you paste a live key (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

GatewayNotes
TestA built-in simulator — no keys, no real money. It models the full flow so you can build and demo checkout instantly.
Manual / Bank transferRecords the order as pending and shows your own instructions (bank details, cash on delivery). You confirm it later. No gateway needed.
StripeGlobal cards via Stripe Checkout (hosted). Test with an sk_test_ key and card 4242 4242 4242 4242.
PayPalGlobal PayPal. Create a sandbox app for Client ID + Secret; set mode to sandbox to test.
RazorpayCards, UPI & wallets (India/South Asia). Test with an rzp_test_ key.
KhaltiKhalti wallet (Nepal). NPR only. Test keys come from the Khalti dev portal; sandbox uses Khalti test logins.
eSewaeSewa wallet (Nepal). NPR only. Test mode uses eSewa’s sandbox (merchant EPAYTEST) with no keys at all.
FonepayFonepay (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.
Khalti, eSewa and Fonepay are NPR-only. Set the Payment component’s currency to NPR for those gateways. Online payments need the server’s cURL extension (standard on almost every host).
How Fonepay confirms a payment. Fonepay is a two-step gateway: the payer is sent to Fonepay’s hosted page, then returned to your app without a status. Your app then makes a signed server-to-server verification call to Fonepay and trusts only that result — so a payment is marked paid only after Fonepay confirms it (fail-closed). Nothing extra to configure: enter your PID + secret in Payments and it just works. Fonepay needs no webhook.

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

Every property

PropertyWhat it does
Payment gatewayWhich gateway to use (or Test / Manual). Keys come from Settings → Payments.
AmountThe amount to charge — fixed on the server (tamper-proof).
Currency3-letter code (USD, EUR, NPR, INR…). Khalti/eSewa/Fonepay require NPR.
DescriptionShown to the payer on the checkout page and saved with the record.
Button label / Show amount / AlignHow the button looks.
Success URLWhere to send the payer after paying. Blank = the built-in receipt page.
Cancel / failure URLWhere 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.