LogoZebo Studio

Zebo Checkout

Finalize an order to generate a hosted payment page. Send customers the link, and they can review the invoice and complete the supported payment flow without a custom checkout UI.

What is Zebo Checkout

When you create an order with /orders/new and set finalize: true, Commerce generates two URLs: a web page for payment and a PDF for printing. The web page displays order details—line items, amounts, due dates—and lets customers pay through the supported checkout methods.

The hosted page collects payment details and handles any confirmation required by the selected payment method. Your server creates and tracks the order, but doesn't collect the customer's payment credentials.

Why use Zebo Checkout

Security and compliance

Your servers don't collect payment details or confirmation codes when you use the hosted page. Treat each invoice URL as a bearer capability: send it only to the intended customer and avoid placing it in public logs or analytics attributes.

Zero maintenance

We manage form validation, OTP collection, error handling, retry logic, payment confirmation, and receipt generation. When mobile money providers update their APIs or add security requirements, we update the hosted pages immediately—no code changes from you.

Better conversion

The hosted flow keeps payment-method selection, required confirmation, and final status in one customer-facing experience.

How Zebo Checkout works

Invoice generation

Finalized orders include two invoice URLs in order.invoice.format:

  • Web invoice (invoice.format.web.url) - Mobile-optimized payment page at pages.zebo.dev
  • PDF invoice (invoice.format.pdf.url) - Downloadable/printable version

The links don't require an API key. Anyone who receives a link can open the corresponding invoice, so handle it as sensitive customer data.

Payment flow

  1. Customer opens the web invoice URL
  2. Sees order details: line items, amounts, due date, beneficiary
  3. Selects an available payment method
  4. Enters phone number and taps "Pay Now"
  5. Receives OTP via SMS
  6. Enters 6-digit code on the page
  7. We verify with provider and complete payment
  8. Customer gets instant receipt and confirmation

The exact confirmation steps and completion time depend on the payment method and customer response.

Handling cancellations

Configure checkout_settings when creating orders to control where customers land after payment or cancellation. Set redirect_url for completed payments and cancel_url for abandoned checkouts. When customers click "Cancel" or close the payment page without completing checkout, they land on your cancel URL where you can show incomplete order details, offer alternative payment methods, or provide support contact information.

Both URLs are strongly recommended for a delightful customer experience—redirect URL lets you show order confirmation and next steps, while cancel URL gives customers a clear path forward when they abandon checkout.

Status tracking

Use /orders/lookup to check payment status. Poll at reasonable intervals (30-60 seconds) or check when the customer returns to your app. The response includes current status, payment timestamps, and balance transaction IDs.

Invoice URLs

Web invoice structure

https://pages.zebo.dev/invoices/{order_id}

The order_id serves as both identifier and security token. Anyone with the URL can view and pay the invoice, but they can't modify amounts or see other orders.

PDF invoice structure

https://pages.zebo.dev/invoices/{order_id}/pdf

Same security model. Download and attach to emails, or let customers print for records.

Delivery methods

The invoice URL works in any sharing context:

Direct redirect

After order creation, return the invoice URL to your client and redirect immediately. Recommended for in-app flows where the customer is already engaged.

Email or SMS

Send the URL through your existing notification system. Invoice URLs are ~70 characters—fits in one SMS with context.

WhatsApp or messaging apps

Share the URL directly. Works in all in-app browsers: WhatsApp, Facebook Messenger, Telegram, or any WebView context.

Common patterns

Subscriptions

Create a new order each billing cycle. Send the Zebo Checkout URL. Customers pay through the same flow every time. Clean audit trail per transaction.

Deposits and installments

Create separate orders for each payment. Each gets its own invoice URL and receipt. Link via the reference field for tracking.

Multi-currency

Create one order per currency. Zebo Checkout displays amounts in the order's currency automatically—no conversion logic.

When to use custom checkout

Zebo Checkout works for 90% of cases. Build custom checkout only if you need:

  • Embedded payment - Form inside your app without redirect
  • Pre-order payment - Collect payment before showing details
  • Complex conditional logic - Multi-step flows based on user input
  • Per-vendor branding - Marketplace where each seller needs unique styling

Otherwise, Zebo Checkout is simpler, safer, and faster. You can migrate to custom checkout later—the underlying APIs are the same.

Next steps

Was this page helpful?