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.

The core concept of Open Banking payments is the Checkout Session. Create a new Checkout Session for each payment attempt - it returns a redirectUrl where users complete the payment.

​
High-level flow

1

Create a Checkout Session

Submit the payment parameters and receive a unique redirectUrl.
2

Redirect the user to Augustus

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

Return to your environment

After the user completes the payment at their bank, they’re redirected back to your successCallbackUrl or errorCallbackUrl.
4

Track the status

Subscribe to webhooks to receive real-time payment updates, including settlement of the payment to your account.

​
1. Create a Checkout Session

2023-01-01 (Ivy)
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',
})

const { redirectUrl, id } = session
Pass a customer email to enable the Remember Me feature. This typically boosts conversion rates by 2-5x.

​
2. Redirect the user to Augustus

After receiving the response, redirect your user to session.redirectUrl. They complete the payment in the Augustus Checkout interface. You can also embed the checkout in your page - see the Client Integration guide for iframe and React SDK options.

​
3. Return to your environment

The user lands back at your successCallbackUrl or errorCallbackUrl with these query parameters:
ParamTypeDescription
referenceIdstringYour original reference ID from checkout creation
order-idstringThe Augustus order ID (success only)
user_closedbooleantrue if the user explicitly closed the checkout via the cancel flow
When user_closed is true, you can optionally expire the checkout session via client.checkoutsession.expire({ id }). This triggers webhooks to update your internal status.

​
4. Track the status

When a customer completes payment, the checkoutSession is set to closed and a new order object is created with a status field tracking the payment. Subscribe to the order_updated webhook event to react to status changes. The key statuses to handle:
StatusMeaningSuggested action
paidFunds have settled (or are guaranteed by Augustus)Fulfil the order
failedPayment did not succeed and won’t arriveNotify the customer, offer retry
canceledSession expired or was explicitly cancelledClean up your internal state
Example webhook receiver:
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 fulfilOrder(payload.referenceId)
        break
      case 'failed':
      case 'canceled':
        await markOrderFailed(payload.referenceId, payload.statusClassification)
        break
    }
  }

  res.sendStatus(200)
})

export default router
See Status Flow for every status in the lifecycle, Failure Reasons for the statusClassification field, and Webhooks for subscription setup and signature verification. A few options on the Checkout Session create call have a noticeable impact on user experience and conversion.

​
Payment scheme selection

Augustus is connected to all instant payment rails in each country (e.g. SEPA Instant for EUR, Faster Payments for GBP). By default, Augustus uses the instant rail wherever it’s free; you can override this:
  • instant_only - use only instant rails
  • instant_preferred - prefer instant, fall back to standard
  • standard - use standard (slower, free) rails
If unspecified, the default scheme comes from your application configuration. Speak to your account manager to change it.

​
Default market selection

Pre-select the most relevant country for your customers. Pass an ISO 3166-1 alpha-2 country code (e.g. DE, GB) as market. If omitted, Augustus auto-detects from the user’s IP.
market is ignored if you also pass prefill.bankId to pre-select a specific bank.

​
Customer object

Pass either an email or a pre-created customer ID to enable Remember Me for returning users.
Pass the email under customer.email, not under prefill. Only customer.email is used for Remember Me recognition.
Passing a customer ID or email can boost conversion rates by over 20%.
2023-01-01 (Ivy)
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',
  },
})