Integration flow

Create a Checkout Session for each payment attempt. It returns a redirectUrl where the customer authorizes the payment in their bank. Track the resulting order via webhooks.

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

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.

Basics

Accounts

Incoming Payments

Outgoing Payments

On- / Off-Ramp

Loans

Flow

Create a Checkout Session

Configuration options

Redirect the customer

Handle the return

Track the order

​Flow

​Create a Checkout Session

​Configuration options

​Redirect the customer

​Handle the return

​Track the order

Flow

Create a Checkout Session

Configuration options

Redirect the customer

Handle the return

Track the order