Hosted Checkout — a VezmoPay-hosted payment page

Hosted Checkout is the simplest way to take a payment: you create a payment session on your server, redirect the customer to a VezmoPay-hosted page, they pay, and we redirect them back. Nothing is embedded on your site, you write no checkout UI, and card data never touches your servers — so it's the lowest-effort, lowest-compliance option (PCI SAQ‑A).

It uses the same session you create for the embed and Elements — you simply use the returned url instead of mounting anything. Compare the options:

• Hosted Checkout (this page) — redirect to a VezmoPay page. Zero front-end code.
• Embed / Checkout JS — drop our payment form into your own page via vezmo.js.
• Elements — build your own UI with composable fields.

How it works

1. Your server creates a session with your API key and gets back a url.
2. You redirect the customer to that url.
3. The customer pays on the VezmoPay-hosted page; we redirect them to your successUrl (or cancelUrl), and a webhook confirms the payment server-side.

1. Create a session — POST /v1/merchant/secure-payments

Authenticate first (exchange your key + secret for an access token via POST /merchant/api-auth/login — see Authentication), then create the session. The amount is fixed here, server-side. Pass your customer's name and email in client, and the successUrl / cancelUrl you want them returned to. You may also pass phone and an optional address (line1, line2, city, state, postalCode, country) in client — it's kept on the payment record.

curl -X POST https://api.vezmo.com/api/v1/merchant/secure-payments \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Order #1234",
    "amount": 49.99,
    "currency": "USD",
    "client": {
      "name": "Ada Lovelace",
      "email": "ada@example.com",
      "country": "US",
      "postalCode": "94103"
    },
    "successUrl": "https://your-store.com/order/success",
    "cancelUrl":  "https://your-store.com/order/cancelled",
    "theme": "light"
  }'

The response carries the hosted url:

{
  "success": true,
  "data": {
    "securePayment": {
      "clientToken": "eyJ...",
      "url": "https://api.vezmo.com/api/v1/secure-payments/eyJ...",
      "expiresAt": "2026-06-30T14:30:00.000Z"
    }
  }
}

2. Redirect the customer to the URL

Send the customer to data.securePayment.url. It is a public, single-session link that 302-redirects to the white-label VezmoPay checkout page — no API key, no token handling on your side. The link is short-lived (default 30 min, max 24 h; set ttlMinutes to adjust).

// e.g. in your route handler after creating the session:
res.redirect(session.url);

// or client-side:
window.location = session.url;

3. Handle the return

After the payment resolves server-side, VezmoPay redirects the customer to:

• successUrl?paymentId=<id>&status=success — on a confirmed payment;
• cancelUrl?status=failed — on a terminal failure or cancellation.

Both URLs must be on your Trusted Origins (open-redirect protection rejects anything else, and any non-https scheme). If you omit them, nothing redirects — the page just shows the result and you reconcile by webhook.

What the customer sees

A fully white-label VezmoPay page — your business name, your brand color and logo, the amount, and the available payment methods (card, wallets — Apple Pay / Google Pay — and bank transfer / ACH when eligible). No processor branding beyond the unavoidable bank-connect step. 3‑D Secure is handled automatically. Footer reads “Secured by VezmoPay”.

Theming

Set theme on the session (light / dark / auto; auto follows the customer's device). Your company logo and brand color are applied automatically from your VezmoPay branding settings.

Test cards

• 4242 4242 4242 4242 — success
• 4000 0000 0000 3220 — 3‑D Secure required
• 4000 0000 0000 0002 — declined

Going live

• Add your successUrl / cancelUrl origins to your Trusted Origins (Developer Settings).
• Your account must be approved to collect payments.
• Use your live API key; the hosted page renders in live mode automatically.
• Subscribe a webhook endpoint to payment.success and fulfil from it.

Webhooks

Hosted-checkout payments settle through the same pipeline as every other VezmoPay charge and emit the same events — payment.success, payment.failed, payment.refunded, and the dispute.* events. See Webhooks. For the underlying endpoints (when you want raw control), see the endpoint reference.