Checkout Modes
A payment runs in one of two modes, fixed at creation by checkoutMode:
- Hosted (
"HOSTED", or omit the field) — Finomesh renders the payment page. You redirect the customer to it and receive a callback + optional webhook. Least code. - API (
"API") — you render your own payment UI and drive the flow server-to-server. IP-allowlisted. Most control.
Both modes produce the same payment object and use the same verify call as the source of truth. The differences are only in who renders the page and how outcomes reach you.
Side by side
| Hosted (default) | API mode | |
|---|---|---|
| Payment page | Finomesh-hosted checkout | Your own UI |
checkoutMode | "HOSTED" (or omitted) | "API" |
callbackUrl | Required | Forbidden (no hosted page to redirect from) |
webhookUrl | Optional | Required — the only push channel |
| Server IP allowlist | Not needed | Required (configured in the dashboard) |
| Outcome channels | Callback redirect + webhook | Webhook only (+ verify polling) |
| Create response | Slim { paymentUid, paymentUrl } | Also inlines the full payment object |
Which to choose
- Choose hosted unless you have a specific reason not to — it is the smallest, safest surface: no payment UI to build, no IP allowlist to maintain.
- Choose API mode when the payment experience must live entirely inside your own product and you can call the API from allowlisted servers.
Next
- Hosted Checkout — integrate the default flow.
- Embedded Checkout / API Mode — build your own payment page.