Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.augustus.com/llms.txt

Use this file to discover all available pages before exploring further.

This guide covers the optimal client integration on each platform:
  • Desktop web - embed Augustus via the React SDK or an iframe so customers complete payment without leaving your site
  • Mobile web - redirect users to the Augustus-hosted checkout for a clean experience on smaller screens
  • Mobile native app - open the Augustus-hosted checkout in the user’s default browser and return to your app 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

For desktop web applications, iframe integration with the React SDK provides the best user experience and conversion rates.
  • Embedded iframe: append &iframe=true to the checkout URL before rendering it.
  • Modal iframe: append &popup=true to the checkout URL before rendering it.
The API can’t include these parameters by default because it doesn’t know your rendering method.

​
React SDK

1

Install the SDK

npm install @getivy/react-sdk
2

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.
3

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

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 cancellation
          }
        } catch (e) {
          // Ignore non-JSON messages
        }
      }
    </script>
  </body>
</html>
The iframe sends a postMessage with the following fields:
FieldDescription
sourceAlways "ivy"
typeAlways "iframe"
valueEither "success" or "error"
referenceIdYour 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 web, redirect to the Augustus-hosted checkout instead of using an iframe.
An iframe on mobile web can break the flow when users move to or return 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 iframe on desktop - see above
  }
}
Make sure the successCallbackUrl and errorCallbackUrl you pass to the Checkout Session point to pages on your site that the user lands on after the bank flow completes.

​
Mobile native app

For native mobile applications, always open the checkout in the user’s default browser. Using a WebView interferes with bank authentication, deep linking, SSL handling, and session management. 
// 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)
  }
}

​
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 in your app config so the return URLs from Augustus checkout open your app.

​
Need help?

Contact help@augustus.com.