@paymux-js/sdk provides a type-safe backend client, Standard Webhooks verifier,
and a separate browser checkout entry point. The browser flow opens the provider
selected by Paymux without showing the hosted payment page.
Hosted checkout remains available and is the simplest option. Both modes use the same payment API, routing, provider webhooks, reconciliation, and normalized app webhooks.
| Experience | Merchant implementation | Best when |
|---|---|---|
| Backend-resolved provider checkout | Set the App's checkout_mode to provider_action. Payment creation returns an action and the browser calls executeCheckout. No Paymux URL or token enters the browser. |
The merchant wants checkout to begin on its own storefront and keep Paymux out of browser requests. |
| Browser-resolved provider checkout | Keep hosted mode but pass the server-created checkout_url to checkout. The SDK opens the routed provider without displaying the Paymux-hosted page. |
An existing integration wants SDK-managed billing and retries with the least backend code. |
| Paymux-hosted checkout | Redirect the browser to the server-created checkout_url. |
The merchant wants the smallest integration or cannot allow provider scripts and frames on its storefront. |
Do not create a separate provider integration in the merchant browser. The checkout entry point handles redirects, signed form posts, official provider SDKs, required billing details, and recovery behavior without exposing backend or provider secrets.
npm install @paymux-js/sdkChoose the default on Apps → your app → Settings → checkout_mode. The application backend creates a payment with the JavaScript SDK, Go SDK, or HTTP API. Never create payments from browser code because that would expose the API key.
import { Paymux } from "@paymux-js/sdk";
const paymux = new Paymux({ apiKey: process.env.PAYMUX_API_KEY, baseURL: "https://payments.example.com" });
const payment = await paymux.payments.create(
{ amount: 49900, currency: "INR", order_ref: "order-1048", return_url: "https://shop.example.com/orders/1048" },
{ idempotencyKey: "order-1048-payment-v1" },
);The backend entry point covers payments, refunds, links, subscriptions, invoices, credit notes, payouts, PDF downloads, and webhook verification.
Every mutation requires an idempotencyKey; use the same key only to retry the
same logical operation. API errors are typed as APIError and include HTTP
status, error type, request ID, replay status, and retry delay.
With checkout_mode=provider_action, payment creation returns
checkout_mode: "provider_action", no checkout_url, and an executable
checkout action. Include required customer billing data in the same request:
const payment = await paymux.payments.create(
{ ...params, customer: { name: order.customerName, billing: order.billing } },
{ idempotencyKey: `order-${order.id}-payment-v1` },
);
// Return only this action to the authenticated owner of this order.
return payment.checkout;The merchant UI executes that JSON directly:
import { executeCheckout } from "@paymux-js/sdk/checkout";
const checkoutAction = await fetch(`/api/orders/${orderId}/checkout`, {
method: "POST",
credentials: "same-origin",
}).then((response) => response.json());
await executeCheckout(checkoutAction);The merchant UI receives no Paymux checkout URL or token. Razorpay stays in its
modal on the merchant page: the checkout-action API omits Paymux's hosted
callback, and the JavaScript SDK also removes those fields defensively before
launching Razorpay. Completion runs through Razorpay's handler. Webhooks and authenticated backend
lookups remain authoritative. Providers that require a redirect may still
return the customer through Paymux's verified return endpoint before Paymux
redirects to the merchant return_url; configure an App custom domain if that
return hop must use the merchant's domain. Include all customer and billing
information required by the App's tax policy when creating the payment; this
mode does not ask Paymux to collect missing billing data in the browser. Use
payments.checkoutAction only for recovery or an intentionally fresh provider
attempt, and use a new idempotency key only when the merchant intentionally
requests one.
Verify webhooks against the exact raw request bytes:
import { WebhookVerifier } from "@paymux-js/sdk";
const verifier = new WebhookVerifier(process.env.PAYMUX_WEBHOOK_SECRET);
const event = await verifier.verify(request.headers, new Uint8Array(await request.arrayBuffer()));Return only the customer checkout URL to that order's authenticated browser:
{"checkout_url":"https://pay.example.com/pay/TuSgrD0tRwOTok?t=..."}The checkout URL is returned only when the payment is created; retrieving the
payment does not reproduce its customer token. Keep the URL in encrypted or
equivalently access-controlled server storage until payment expiry, return it
only to the authenticated order owner, and remove it after expiry or a terminal
outcome. If it is lost, inspect and cancel the old payment when possible before
creating a replacement. Keep every payment linked to the order so a late
success or needs_review result is reconciled instead of causing automatic
duplicate fulfilment.
Then open it:
import { checkout } from "@paymux-js/sdk/checkout";
await checkout({ checkoutUrl });The return_url origin must exactly match the storefront origin running the
SDK. Paymux enforces that boundary before returning a provider action. Use HTTPS
except on loopback during local development.
The SDK exchanges the customer checkout token for a server-validated action:
redirect: navigate to Stripe, Whop, the simulator, or another hosted checkout;form_post: create and submit PayU's signed form without exposing the PayU salt;sdk: load and launch Razorpay, Cashfree, or Zoho's official browser SDK.
If billing details are required, the SDK displays an accessible dialog with keyboard focus management, inline validation, retry, and recovery states. Supply the customer and billing details when creating a payment to skip this dialog.
The checkout token is a customer credential. Do not log it, persist it in analytics, put it in HTML generated for another customer, or send it anywhere except the matching Paymux origin. Responses are CORS-bound to the payment's return origin and are never cacheable.
Razorpay, Cashfree, and Zoho run their own scripts and frames on the storefront.
The storefront CSP must include the origin that issued checkout_url in
connect-src, because the checkout SDK first posts to that Paymux origin. It
must also permit the selected provider's declared checkout hosts. Use hosted
Paymux checkout when the storefront cannot allow those resources. Redirect and
form-post integrations leave the page and do not execute provider scripts in
it.
With a nonce-based policy, pass the fresh nonce generated for the current HTML response. Paymux applies it to the built-in dialog style and dynamically loaded provider script:
await checkout({ checkoutUrl, nonce: window.cspNonce });The CSP must still allow the selected provider's script, frame, image, form, and connection hosts. Do not reuse a nonce across responses.
Browser events are for interface state only. A customer can close the page,
forge query parameters, or return before a delayed payment settles. Mark an
order paid only after a verified Paymux payment.succeeded webhook, or after
the backend retrieves the payment with its Paymux API key.
The return page should show a neutral "Confirming payment" state until its own backend reports the order paid, failed, or still processing.
Coding agents can start with /llms.txt and use the complete
/llms-full.txt integration contract and acceptance tests.