Client integration

Recommended integration per platform:

Desktop web — embed via the React SDK or an iframe.
Mobile web — redirect to the Augustus-hosted checkout.
Mobile native — open the Augustus-hosted checkout in the user’s default browser; return via deep linking.

Backend setup

Create a server-side endpoint that initiates a Checkout Session and returns the redirectUrl to your frontend.

server/routes/checkout.ts

import express from 'express'
import Ivy from '@getivy/node-sdk'

const router = express.Router()
const client = new Ivy()
router.post('/api/checkout', async (req, res) => {
  const session = await client.checkoutsession.create({
    referenceId: 'order_123',
    price: {
      total: req.body.amount,
      currency: req.body.currency || 'EUR',
    },
    locale: req.body.locale || 'en',
    successCallbackUrl: 'https://example.com/success',
    errorCallbackUrl: 'https://example.com/error',
    customer: {
      email: 'john.doe@example.com',
    },
  })

  res.json({ url: session.redirectUrl })
})

export default router

Desktop web

Use the React SDK to embed the checkout in your page.

Embedded iframe: append &iframe=true to the checkout URL.
Modal iframe: append &popup=true to the checkout URL.

The API doesn’t include these parameters — you set them at render time. The React SDK does this automatically.

React SDK

Install the SDK

npm install @getivy/react-sdk

Create the checkout component

components/IvyCheckout.tsx

import { IvyCheckout } from '@getivy/react-sdk'

export function Checkout({
  amount,
  currency = 'EUR',
  locale = 'de',
  handleSuccess,
  handleCancel,
}: {
  amount: number
  currency?: string
  locale?: string
  handleSuccess: (data: { redirectUrl: string; referenceId: string }) => void
  handleCancel: (data: { redirectUrl: string; referenceId: string }) => void
}) {
  const response = await fetch('/api/checkout', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ amount, currency, locale }),
  })

  const { url } = await response.json()

  return (
    <IvyCheckout
      checkoutUrl={url}
      displayOptions={{ type: 'embedded' }}
      onSuccess={handleSuccess}
      onCancel={handleCancel}
    />
  )
}

The React SDK automatically appends &iframe=true when using embedded mode.

Add styling

styles/ivy-checkout.css

@import "@getivy/react-sdk/dist/index.css";

.ivy-embedded-checkout-screen {
  width: 100%;
  height: 100%;
  border: none;
}

.ivy-modal-content {
  position: fixed;
  inset: 0;
  z-index: 999999;
  display: flex;
  align-items: center;
  justify-content: center;
  background-color: rgba(10, 10, 10, 0.25);
}

.ivy-modal-content .ivy-modal-iframe-container {
  width: 100%;
  height: 100%;
  border-radius: 16px;
  overflow: hidden;
}

@media (max-width: 450px) {
  .ivy-modal-content .ivy-modal-iframe-container {
    border-radius: 0;
  }
}

Plain HTML (without the SDK)

If you can’t use React, render the iframe directly. The iframe communicates with your page via postMessage.

checkout.html

<!DOCTYPE html>
<html>
  <body>
    <button onclick="startCheckout()">Pay with Augustus</button>
    <div id="iframe-container"></div>

    <script>
      async function startCheckout() {
        const response = await fetch('/api/checkout', {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify({ locale: 'de' }),
        })

        const { url } = await response.json()
        const iframeUrl = url + '&iframe=true'

        document.getElementById('iframe-container').innerHTML = `
          <iframe
            src="${iframeUrl}"
            sandbox="allow-scripts allow-same-origin allow-popups allow-forms allow-popups-to-escape-sandbox allow-top-navigation"
            allow="clipboard-write"
            style="width:100%; height:650px; border:none; border-radius:8px;"
          ></iframe>
        `

        window.addEventListener('message', handleMessage)
      }

      function handleMessage(event) {
        try {
          const { source, type, value, referenceId } = JSON.parse(event.data)
          if (source !== 'ivy' || type !== 'iframe') return

          if (value === 'success') {
            // Handle success — referenceId matches your original.
          } else if (value === 'error') {
            // Handle failure or cancelation.
          }
        } catch (e) {
          // Ignore non-JSON messages
        }
      }
    </script>
  </body>
</html>

The iframe sends a postMessage with the following fields:

Field	Description
`source`	Always `"ivy"`.
`type`	Always `"iframe"`.
`value`	Either `"success"` or `"error"`.
`referenceId`	Your original `referenceId` from Checkout Session creation.

The iframe sandbox attributes are required:

allow-scripts — required for the checkout to function.
allow-same-origin — enables secure communication.
allow-forms — required for payment form input.
allow-popups, allow-popups-to-escape-sandbox — required for bank redirects.
allow-top-navigation — required for completion redirects.
allow="clipboard-write" — required for copy-to-clipboard buttons.

Mobile web

On mobile, redirect to the Augustus-hosted checkout. An iframe breaks the flow when the customer moves to and from their banking app.

function isMobile() {
  return /Android|webOS|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i.test(navigator.userAgent)
}

async function startCheckout() {
  const response = await fetch('/api/checkout', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ amount: 100, currency: 'EUR' }),
  })

  const { url } = await response.json()

  if (isMobile()) {
    window.location.href = url
  } else {
    // Render the iframe on desktop — see above.
  }
}

Make sure the successCallbackUrl and errorCallbackUrl you pass to the Checkout Session point to pages on your site where the user lands after the bank flow completes.

Mobile native

Open the checkout in the user’s default browser. Do not use a WebView — it breaks bank authentication, deep linking, SSL, and session handling.

// Don't do this
<WebView source={{ uri: checkoutUrl }} />

// Do this instead
Linking.openURL(checkoutUrl)

Open the checkout

import { Linking } from 'react-native'

const openCheckoutInBrowser = async () => {
  const response = await fetch('/api/checkout', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ amount: 100, currency: 'EUR' }),
  })

  const { url } = await response.json()

  if (await Linking.canOpenURL(url)) {
    await Linking.openURL(url)
  }
}

import SafariServices

func openCheckoutInBrowser() {
    guard let url = URL(string: checkoutUrl) else { return }
    let safariVC = SFSafariViewController(url: url)
    safariVC.delegate = self
    present(safariVC, animated: true)
}

fun openCheckoutInBrowser() {
    val intent = Intent(Intent.ACTION_VIEW, Uri.parse(checkoutUrl))
    intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
    startActivity(intent)
}

Deep linking back to your app

Configure deep linking so the user returns to your app after payment:

import { Linking } from 'react-native'

useEffect(() => {
  const handleDeepLink = ({ url }) => {
    if (url.includes('payment-success')) {
      navigation.navigate('PaymentSuccess')
    } else if (url.includes('payment-error')) {
      navigation.navigate('PaymentError')
    }
  }

  const subscription = Linking.addEventListener('url', handleDeepLink)
  return () => subscription.remove()
}, [])

Configure your app’s deep-linking scheme so the Augustus return URLs open your app.

Basics

Accounts

Incoming Payments

Outgoing Payments

On- / Off-Ramp

Loans

Backend setup

Desktop web

React SDK

Plain HTML (without the SDK)

Mobile web

Mobile native

Open the checkout

Deep linking back to your app

​Backend setup

​Desktop web

​React SDK

​Plain HTML (without the SDK)

​Mobile web

​Mobile native

​Open the checkout

​Deep linking back to your app

Backend setup

Desktop web

React SDK

Plain HTML (without the SDK)

Mobile web

Mobile native

Open the checkout

Deep linking back to your app