Hosted checkout

Hosted checkout

Hosted checkout is the simplest way to take a payment: you create a session through the API, send the customer to the returned URL, and Biz Invoice Pay handles the card form, confirmation, and redirect. You never handle card data.

The flow

Your website / app
        │  POST /api/v1/payment-sessions
        │  { amount_cents, description, success_url, cancel_url, ... }
        ▼
   Biz Invoice Pay API
        │  201 { id, url, status: "open", expires_at }
        ▼
Your website ──redirect──▶  Hosted pay page (/checkout/[id])
                                    │
                    ┌───────────────┼───────────────┐
                    ▼               ▼               ▼
                 Customer       Customer         Session
                 pays OK        cancels          expires
                    │               │               │
                    ▼               ▼               ▼
              success_url      cancel_url     (you poll GET
              (append ?id)     (append ?id)    /payment-sessions/:id
                                               or listen to webhooks)

Steps in detail

1. Create the session — POST /api/v1/payment-sessions with an idempotency key. You get back id, url, and expires_at.
2. Redirect the customer to url, or display the session's QR code.
3. Customer pays on the branded pay page (your logo and business name). The session status moves open → paid.
4. Customer returns to your success_url (paid) or cancel_url (cancelled). We append ?id=<session id> so you can match the return to the session.
5. Confirm server-side — never trust the redirect alone. Call GET /api/v1/payment-sessions/:id or GET /api/v1/payments?reference= to verify the payment before fulfilling the order. Better yet, listen for the payment.succeeded webhook.

Success and cancel URLs

• success_url — e.g. https://yourshop.com/thanks. Shown after a successful payment.
• cancel_url — e.g. https://yourshop.com/cart. Shown if the customer clicks back/cancel without paying.

Both must be absolute HTTPS URLs in live mode.

Expiry

Sessions expire at expires_at (a few hours after creation in dev; check the value returned). An expired session shows status: "expired" and its URL stops accepting payment. Create a fresh session if the customer comes back later.

Test the whole flow

Use the success test card 4242 4242 4242 4242 on the pay page, then verify with the lookup endpoints. Full card table and dev tips are in Testing.