Embedding the webview

Blend's checkout is a web page that your app shows inside a webview. Your app does not implement seat selection, pricing or ticket delivery. Blend draws all of that. What your app owns is small and precise: fetch a private link from your own backend, show it, and be ready to charge the buyer on your own payment rail when the page asks. This page describes those responsibilities without reference to any one platform; the iOS, Android and React Native pages turn them into code.

What the app does, and does not do

The app has exactly three jobs.

1. Ask your own backend for a session URL

   Your backend, not the app, calls Blend. The app receives a URL and nothing else, no key, no secret, no buyer record.

2. Show that URL in a webview

   A webview with JavaScript and DOM storage enabled, cookies that survive navigation, and navigation that stays inside the webview for Blend's hosts.

3. Register the payment bridge, and charge when asked

   Before the page loads, the app registers a native message handler. When the buyer taps Pay, the page posts a small charge message through it. The app tells its own backend, which charges the buyer and confirms to Blend.

Everything else, reserving inventory, confirming the order, issuing the ticket, happens between your backend and Blend, server-to-server. The app never talks to the Blend API directly and never holds Blend credentials.

Where the session URL comes from

Your backend creates a session by telling Blend who is about to buy. Blend answers with a private, single-use link that is valid for 30 minutes.

Keyed call: send x-blend-key and x-blend-secret. Full reference on Buyer sessions.

A typical shape: the app calls a route on your backend, the name is yours, for example GET /api/blend/session, with the app's normal user authentication. Your backend looks up the signed-in user, calls Blend, and returns only url to the app.

// Runs on YOUR server. Keys come from your secret store, never from the app.
const BLEND_API = 'https://api.blendapp.ai/api/v1';

export async function mintBlendSession(buyer: {
  name: string;
  email: string;
  phone?: string;
}): Promise<{ url: string; expiresAt: string }> {
  const res = await fetch(BLEND_API + '/channel/session', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-blend-key': process.env.BLEND_KEY!,     // ck_live_xxxxxxxx
      'x-blend-secret': process.env.BLEND_SECRET!, // cs_live_xxxxxxxx
    },
    body: JSON.stringify({
      buyerName: buyer.name,
      buyerEmail: buyer.email,
      buyerPhone: buyer.phone,
    }),
  });

  const json = await res.json();
  if (!res.ok || !json.success) {
    throw new Error('Blend session failed: ' + res.status);
  }
  // Return only what the app needs. The app receives { url } and nothing else.
  return { url: json.data.url, expiresAt: json.data.expiresAt };
}

Webview requirements

These apply on every platform. Most are one line of configuration; all of them matter, because the checkout depends on a session cookie and on JavaScript, and a webview with either switched off shows a page that looks fine and cannot buy anything.

The payment bridge

When the buyer taps Pay, Blend's page sends the native host one message. The message has the same shape everywhere: a JSON object with type, orderId, amount and currency.

{
  "type": "charge",
  "orderId": "<string>",
  "amount": 42.5,
  "currency": "USD"
}

How the message reaches native code differs by platform. The name is fixed; the case differs between iOS and Android, and each must be exact.

Powered by Blend

The trust model

Your app and backend must, in order:

1. Origin-check before acting

   Confirm that the webview delivering the message is showing a Blend page. On iOS read message.webView?.url; on Android read webView.url; in React Native read event.nativeEvent.url. If the host is not Blend's, discard the message silently. This does not make the channel authenticated, nothing about a webview bridge can, but it closes the “some other page entirely” case.

2. Re-fetch the authoritative amount server-to-server, and charge that

   Your app sends orderId to your backend. Your backend asks Blend for that order (keyed, with your secret, see Confirming & settlement) and charges the amount Blend returns. The amount in the message exists so your payment sheet can show a number immediately, before that round-trip completes. Nothing more.

3. Never share the bridge with non-Blend content

   The controller or interface that carries the handler must belong to a webview that loads only Blend. A webview that also renders ads, marketing pages or any third-party content hands those pages the same ability to post a charge message. Give the checkout its own webview, its own registration, and its own lifecycle.

After the charge

Once your rail reports success, the app tells your backend, and your backend confirms to Blend with a signed, server-to-server call. The app does not call Blend, and the app does not need to tell the webview anything.

The page discovers the outcome on its own. After it posts the charge message it polls Blend for the order's status every 3 seconds for up to 6 minutes, then displays the ticket when the order is paid. Your app does not navigate, reload or inject anything into the webview after charging. Full reference on Confirming & settlement.

Session lifecycle

• A session URL is valid for 30 minutes from creation and is single use. Once loaded, the token in it is consumed and the session continues on the cookie.
• Reloading the current page (pull-to-refresh, a normal reload) is safe: the cookie carries the session.
• Reloading the original …/channel/session?token=… URL after it has been consumed is not safe. It will not restore the session. If your retry path needs a URL, ask your backend for a new one.
• Use expiresAt. If the buyer comes back to the checkout screen after it has passed, mint a fresh session rather than showing a stale page.
• Create the session when the buyer opens the checkout screen, not when they sign in. A session minted early and shown late is a session that expires mid-purchase.

A checklist for review

For whoever signs off on the integration, the things that matter, in one place.

• No Blend key or secret appears anywhere in the app binary, its configuration, or its build pipeline.
• The app calls only your own backend. There is no request to api.blendapp.ai from the app.
• The charge amount is fetched by your backend from Blend using orderId. The amount in the bridge message is only ever displayed.
• The bridge handler checks the webview's current host before acting.
• The checkout webview loads Blend only. Its handler registration is not shared with any other webview.
• The bridge is registered before the URL is loaded.
• JavaScript, DOM storage and persistent cookies are on. Cookies are not cleared while the checkout screen is alive.
• Blend hosts navigate inside the webview. Back navigation goes through the webview first.
• Retry after failure mints a new session; it does not reload a consumed URL.
• The user agent is the platform default.

Next