Quickstart

1. Install

npm install @suqo/react-native react-native-webview

2. Mount the provider

Mount the provider once, at your app root:

import { SuqoProvider } from '@suqo/react-native'

export default function App() {
  return (
    <SuqoProvider mode="sandbox">
      <Navigation />
    </SuqoProvider>
  )
}

mode="live" points at app.suqo.ai; the default, "sandbox", points at test.suqo.ai — so an app that names neither cannot accidentally take a live payment. Pass baseUrl to go somewhere else entirely (a staging mirror, a local mock server); it overrides mode when set.

3. Create a checkout session on your backend

Your backend creates the session and passes its id to the app. The session must already have a customer assigned when you create it — this package has no way to attach one. See Create a checkout session.

4. Open a payment

Open a payment from anywhere below the provider:

import { useState } from 'react'
import { Button, Text } from 'react-native'
import { useNavigation } from '@react-navigation/native'
import { useSuqoCheckout } from '@suqo/react-native'

function PayButton({ sessionId }: { sessionId: string }) {
  const { open } = useSuqoCheckout()
  const navigation = useNavigation()
  const [error, setError] = useState<string | null>(null)

  return (
    <>
      <Button
        title="Pay"
        onPress={() =>
          open({
            sessionId,
            onSuccess: ({ params }) => navigation.navigate('Receipt', { params }),
            onFailure: ({ status, message }) =>
              setError(status === 'cancelled' ? null : (message ?? 'Payment failed')),
            onClose: () => {},
          })
        }
      />
      {error && <Text>{error}</Text>}
    </>
  )
}

navigation here is React Navigation; use whatever your app navigates with — the SDK does not depend on it.

Exactly one of the three callbacks fires per open(). open() also resolves with the outcome, if you prefer await to callbacks:

const outcome = await open({ sessionId })
if (outcome.result === 'success') {
  /* … */
}

There is nothing about the buyer here

The checkout session is created on your own backend with your API key, and it must already carry the buyer by the time you pass its id to open() — their name, email and address never pass through this SDK, never reach the device, and never end up in a log.

open() rejects before the sheet appears, for exactly two reasons: a checkout is already open, or the session id and base URL cannot produce a checkout URL. Check error instanceof SuqoConfigError rather than matching its message.

What the buyer sees

A full-height screen slides in with the SUQO payment block inside it: a back button, a title, and the block filling the rest. The block scrolls — a seller with NPS enabled lists every supported bank, which runs well past a phone screen.

It is presented as a full-screen Modal, not a route in your navigator — nothing to register, no route name to agree on — and it still behaves like a pushed screen, including Android's hardware back button. Back, hardware back, or close() all dismiss it and report onClose — unless the page had already verified a payment, in which case that result is delivered instead (see Handle outcomes).

When the buyer's bank needs its own app, the screen hands the deeplink to the OS and the bank app opens over yours. Coming back leaves the screen exactly as it was, mid-payment.