Talk to us

Omno for developers: hosted checkout, Direct Links, webhooks, API docs

Developers integrate Omno through one API with four options: the hosted checkout opened with the Web SDK, Card Fields for cards on your own checkout, Direct Links for local methods, wallets and crypto from your own buttons, or an iFrame. Routing and PSP eligibility run on every payment, and webhooks deliver the final status. The guides below cover every step, from credentials to go-live.

Updated

What your backend receives

Every final outcome reaches you as a webhook. This one shows a payment that was declined by the first provider and approved by the second.

Illustrative webhook after a cascade. Field names are simplified; the API reference has the exact schema.json
{
  "event": "payment.status_changed",
  "transaction_id": "txn_8f2c41e9",
  "status": "approved",
  "amount": 150.00,
  "currency": "BRL",
  "method": "card",
  "route": {
    "attempts": [
      { "psp": "psp_a", "result": "soft_decline", "code": "05" },
      { "psp": "psp_b", "result": "approved" }
    ]
  }
}
On this page5 sections

Which integration option fits my product?

Omno offers four ways to take payments.

  • Hosted checkout with the Web SDK. One checkout page in your brand for cards, Apple Pay, Google Pay, local methods and crypto. Your backend creates a session and your frontend opens it with the Web SDK. Routing, PSP eligibility and saved cards run inside the flow. This is the recommended option for new integrations. See the hosted checkout guide.
  • Card Fields. Your own checkout for cards. Three secure Omno card fields for card number, expiry and CVV sit inside your page, styled through the Omno SDK, and card data never touches your servers. See Card Fields.
  • Direct Links. Your own buttons for local methods, wallets and crypto, with no Omno payment page. Behind each button, Omno routes the payment across several providers of that method. See the Direct Links guide.
  • iFrame. The hosted checkout embedded in your own page, for teams that want the hosted flow without leaving their layout.

The older Payment Page remains for existing merchants only and is not available for new onboarding.

How does a hosted checkout integration work?

The flow has six steps:

  1. Your backend obtains an access token.
  2. Your backend creates a hosted checkout session and receives a session ID, a short-lived token and URLs for the checkout, payment and payout views.
  3. Your backend passes the session ID and token to your frontend.
  4. Your frontend opens the hosted checkout with the Web SDK.
  5. The customer pays, and the selected provider processes the payment.
  6. Omno sends a webhook with the final status to your backend, which can confirm it with Get Transaction Info.

When you create the session, include as much customer context as you can: customer groups, KYC levels (customer verification levels), whether the customer is KYC verified and how many previous transactions they have made. These fields drive PSP eligibility and routing.

Why are webhooks the source of truth?

A browser can close, a redirect can fail and a customer can refresh at the wrong moment. None of that changes whether the provider approved the payment. Omno therefore treats the webhook to your backend, and the Get Transaction Info endpoint, as the only authoritative statement of a transaction’s final status.

Build your integration around that:

  • Credit balances, ship goods and approve payouts only on a webhook or a confirmed status.
  • Check each webhook as described in the webhooks guide before acting on it.
  • Handle repeated deliveries idempotently.
  • Expect asynchronous outcomes. Statuses such as PENDING and PENDING_3DS resolve later, a timeout may resolve after the customer leaves, and an abandoned session produces no final webhook. Reconcile those with Get Transaction Info.

How do routing and PSP eligibility affect my requests?

Every payment passes through two steps. Eligibility first removes providers that cannot serve the customer, using country, method, customer groups sent as customer.customerGroups and KYC levels sent as customer.kyc.kycLevels. Routing then picks one provider from those that remain. Signals such as kycVerified and previousTransactionCount let rules treat first-time and returning customers differently.

You can pin a request to a specific router with routerId, or to a specific Direct Link route with directRouteId. Provide at most one. The routing and PSP eligibility guide lists every field and its effect.

How do I get from first test to live?

  1. Talk to Omno about your markets, methods and providers, and receive dashboard access.
  2. Create API credentials and pick your integration option; Getting started walks through the options.
  3. Build session creation, the frontend checkout and your webhook handler, testing against fake payment providers on your account (Omno has one production environment, so there is no separate test environment).
  4. Test approvals, declines, pending outcomes, timeouts and abandoned sessions, and check that your ledger only moves on webhooks.
  5. Configure providers, routers and eligibility rules for production with the Omno team.
  6. Switch credentials, go live and watch the real-time success metrics and routing logs on the dashboard.

Every endpoint is listed in the API reference.

Frequently asked questions

Which integration should I build first?

The hosted checkout, opened with the Web SDK. It is the recommended flow for new integrations and takes cards, Apple Pay, Google Pay, local methods and crypto on one page. Add Card Fields or Direct Links later if you want your own checkout.

Where do I get the final status of a transaction?

From the webhook Omno sends to your backend, or by calling Get Transaction Info. Redirects and client-side events are for the user interface only and are not authoritative.

Can I choose which PSP processes a payment?

You can pass a routerId to use a specific router, or a directRouteId for a specific Direct Link route. Provide at most one. Without either, default routing applies, filtered by PSP eligibility rules.

Is the legacy Payment Page available?

The Payment Page is a legacy flow and is not offered to new merchants. New integrations should use the hosted checkout, Card Fields or Direct Links.

Terms on this page

it will.

Tell us where your payments fail. We will show you how routing changes the outcome.

Talk to us Calculate your lost sales
esc

Jump to

Payment orchestrationOne API to many payment providers Page Smart routingRules, traffic splits, limits and cascading Page Hosted checkoutA no-code checkout builder, every method Page Card FieldsCustom checkout for cards, no card data Page E-commerce Page Coverage Page Integrations Page CompareOmno next to the platforms you shortlist Page GlossaryPayment terms, defined plainly Page BlogNotes on approval rates and routing Page Payment methodsLocal methods, country by country Page ContactTalk to the payments team Page

↑↓ to move ↵ to open All results