Open Banking

Let customers pay you directly from their bank account. Create a Checkout Session for each payment attempt, redirect the customer to authorize the payment in their bank, and track the resulting order via webhooks.

Open Banking is available only in the 2023-01-01 API.

Integration flow

Create a Checkout Session

Submit payment parameters and receive a redirectUrl.

Redirect the customer

Send the customer to redirectUrl for the Augustus-hosted bank selection and authorization screens.

Return to your app

The customer lands back at your successCallbackUrl or errorCallbackUrl.

Track the order

Subscribe to order_updated webhooks for real-time status.

Create a Checkout Session

2023-01-01

import Ivy from '@getivy/node-sdk'

const client = new Ivy()
const session = await client.checkoutsession.create({
  price: { total: 119, currency: 'EUR' },
  referenceId: 'my-unique-reference-id',
  successCallbackUrl: 'https://my-website.com/success',
  errorCallbackUrl: 'https://my-website.com/try-again',
  paymentSchemeSelection: 'instant_preferred',
  market: 'DE',
  customer: { email: 'customer@example.com' },
})

const { redirectUrl, id } = session

POST /api/service/checkout/session/create in the API Reference →

Configuration options

Field	Description
`paymentSchemeSelection`	`instant_only`, `instant_preferred` (default), or `standard`. Controls whether Augustus uses instant rails (SEPA Instant, Faster Payments) or falls back to standard. Default is set per application — contact your account manager to change it.
`market`	ISO 3166-1 alpha-2 code (e.g. `DE`, `GB`) to pre-select the country. Auto-detected from the customer’s IP if omitted. Ignored if `prefill.bankId` is set.
`customer.email`	Email of the paying customer. Enables Remember Me. Must be under `customer.email`, not `prefill`.

Redirect the customer

Redirect the customer to session.redirectUrl. To embed instead of redirect, see Client integration.

Handle the return

The customer lands at your successCallbackUrl or errorCallbackUrl with these query parameters:

Param	Type	Description
`referenceId`	string	Your original reference ID.
`order-id`	string	The Augustus order ID (success only).
`user_closed`	boolean	`true` if the customer explicitly closed the checkout.

When user_closed is true, you can expire the Checkout Session with client.checkoutsession.expire({ id }) to trigger webhooks and update your internal state.

Track the order

When the customer completes payment, the Checkout Session is closed and a new order is created. Subscribe to order_updated and handle these statuses:

Status	Action
`paid`	Funds have settled or are guaranteed by Augustus. Fulfill the order.
`failed`	Payment did not succeed and won’t arrive. Offer a retry.
`canceled`	Session expired or was canceled. Clean up your state.

server/routes/webhooks.ts

import express from 'express'

const router = express.Router()

router.post('/webhooks/augustus', express.json(), async (req, res) => {
  const { type, payload } = req.body

  if (type === 'order_updated') {
    switch (payload.status) {
      case 'paid':
        await fulfillOrder(payload.referenceId)
        break
      case 'failed':
      case 'canceled':
        await markOrderFailed(payload.referenceId, payload.statusClassification)
        break
    }
  }

  res.sendStatus(200)
})

export default router

See Status flow for the full lifecycle, Failure reasons for statusClassification, and Webhooks for setup and signature verification.

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

Remember Me

Pass a customer.email or a stored customer.id on each Checkout Session. Augustus recognizes the returning customer and skips bank selection.

Pass the email under customer.email, not under prefill. Only customer.email is used for Remember Me recognition.

First-time flow

Recurring flow

Pass a customer email

2023-01-01

import Ivy from '@getivy/node-sdk'

const client = new Ivy()
const session = await client.checkoutsession.create({
  price: { total: 119, currency: 'EUR' },
  referenceId: 'my-unique-reference-id',
  successCallbackUrl: 'https://my-website.com/success',
  errorCallbackUrl: 'https://my-website.com/try-again',
  customer: { email: 'customer@example.com' },
})

Show Or create a customer upfront and reuse the ID

2023-01-01

import Ivy from '@getivy/node-sdk'

const client = new Ivy()
const customer = await client.customers.create({ email: 'customer@example.com' })

const session = await client.checkoutsession.create({
  price: { total: 119, currency: 'EUR' },
  referenceId: 'my-unique-reference-id',
  successCallbackUrl: 'https://my-website.com/success',
  errorCallbackUrl: 'https://my-website.com/try-again',
  customer: { id: customer.id },
})

Status flow

Augustus tracks Open Banking and Manual Bank Transfer payments through the order.status field. Poll the order or subscribe to order_updated webhooks — status values are identical in both.

2023-01-01

import Ivy from '@getivy/node-sdk'

const client = new Ivy()
const order = await client.orders.retrieve({ id: 'your-order-id' })

Statuses

Status	Description	Next	Terminal
`processing`	Order created and payment flow started.	`waiting_for_payment`, `paid`, `finalizing`, `failed`, `canceled`	No
`waiting_for_payment`	Customer authorized the payment. Settlement pending. Not guaranteed. Skipped if settlement happens first.	`paid`, `finalizing`, `failed`, `canceled`	No (yes for direct settlement)
`finalizing`	Payment received, booking verification in progress. Usually minutes, up to 48 hours. Can still be expired via API.	`paid`, `canceled`	No
`paid`	Funds arrived or are guaranteed by Augustus. Settlement takes anywhere from instant to 3 business days depending on scheme. Only appears when Augustus holds your collection account.	`in_refund`	Yes (unless refunded)
`canceled`	Session expired or was canceled. Late payments are auto-returned.	—	Yes
`failed`	Funds did not arrive in time (6 days for `instant_preferred` / `standard`, 24 hours for `instant_only`). Late payments are auto-returned.	—	Yes
`in_refund`	Refund in flight to the customer’s bank.	`refunded`, `partially_refunded`	No
`refunded`	Fully refunded.	—	Yes
`partially_refunded`	Part of the order was refunded.	`in_refund`	No

Payments don’t always follow the common path — handle every transition in your integration.

Failure reasons

When an order fails or is canceled, the order_updated webhook includes a statusClassification object with a broad primary category and a specific secondary reason.

{
  "statusClassification": {
    "primary": "payment_execution_failed",
    "secondary": "insufficient_funds"
  }
}

Primary classifications

Primary	Meaning	Common causes	Handling
`payment_authorization_failed`	Rejected during authorization at the bank.	Wrong credentials, canceled at bank, account restrictions.	Suggest retry, check credentials, try a different bank.
`payment_execution_failed`	Authorized but couldn’t execute.	Insufficient funds, account limits, blocked international transfer, bank rejection or outage.	Retry — if the original payment arrives late, it’s auto-returned.
`payment_abandoned`	Started but never completed.	Customer closed the browser, session timed out, canceled at the bank.	Show clear messaging, allow retry.

Secondary classifications

Code	Description
`wrong_credentials`	User entered incorrect bank credentials during authentication.
`incorrect_2fa_response`	User provided an incorrect two-factor authentication response.
`pin_blocked`	User’s PIN is blocked, e.g. after multiple failed attempts.
`no_active_tan_methods_available`	No active TAN (Transaction Authentication Number) methods available.
`timeout`	The payment request timed out due to slow response from bank systems.
`connection_to_bank_failed`	The user’s bank is not responding to the payment request.
`bank_error`	The bank’s system returned an error during processing.
`bank_under_maintenance`	The user’s bank is currently under maintenance.
`insufficient_funds`	The user’s account has insufficient funds for the payment.
`account_limit_exceeded`	The payment exceeds the user’s account transfer limits.
`international_transfer_blocked`	International transfers are blocked for this account.
`international_transfer_limit_exceeded`	The payment exceeds international transfer limits.
`instant_transfers_not_enabled`	Instant transfers are not enabled for this account.
`user_blocked`	The user’s account is blocked or restricted.
`unsupported_bank_account`	The bank account type is not supported for the requested transfer.
`payment_rejected`	The payment was explicitly rejected by the bank.
`cancelled`	The payment was canceled by the user or bank.
`payment_not_settled`	The payment was not settled within the required timeframe.

See Webhooks for setup and signature verification.

Closed-loop payouts

Pay out to a customer from a previous checkout by referencing their order ID instead of bank details:

2023-01-01

import Ivy from '@getivy/node-sdk'

const client = new Ivy()
const payout = await client.payouts.create({
  amount: 100,
  currency: 'EUR',
  destination: { type: 'customer', orderId: 'order_abc123' },
})

POST /api/service/payout in the API Reference →

Basics

Accounts

Payments

Conversions

Loans

Legacy (2023-01-01)

Integration flow

Create a Checkout Session

Configuration options

Redirect the customer

Handle the return

Track the order

Client integration

Backend setup

Desktop web

React SDK

Plain HTML (without the SDK)

Mobile web

Mobile native

Open the checkout

Deep linking back to your app

Remember Me

First-time flow

Recurring flow

Pass a customer email

Status flow

Statuses

Failure reasons

Primary classifications

Secondary classifications

Closed-loop payouts

​Integration flow

​Create a Checkout Session

​Configuration options

​Redirect the customer

​Handle the return

​Track the order

​Client integration

​Backend setup

​Desktop web

​React SDK

​Plain HTML (without the SDK)

​Mobile web

​Mobile native

​Open the checkout

​Deep linking back to your app

​Remember Me

​First-time flow

​Recurring flow

​Pass a customer email

​Status flow

​Statuses

​Failure reasons

​Primary classifications

​Secondary classifications

​Closed-loop payouts

Integration flow

Create a Checkout Session

Configuration options

Redirect the customer

Handle the return

Track the order

Client integration

Backend setup

Desktop web

React SDK

Plain HTML (without the SDK)

Mobile web

Mobile native

Open the checkout

Deep linking back to your app

Remember Me

First-time flow

Recurring flow

Pass a customer email

Status flow

Statuses

Failure reasons

Primary classifications

Secondary classifications

Closed-loop payouts