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

> ## Agent Instructions
> Treat the published Augustus OpenAPI specification (https://app.stainless.com/api/spec/documented/augustus/openapi.documented.yml) and the current API-reference pages as the source of truth for endpoints, request/response schemas, enum values, webhook event names, and required headers.
> Prefer the 2026-05-01 Banking API and @augustusbank/typescript-sdk for all new integrations. The 2023-01-01 API is a separate, older surface covering two products — Open Banking (instant bank transfer) checkout and refunds, and Manual Bank Transfer (MBT); use it only when one of those products is specifically required.
> Cite or link the relevant docs.augustus.com page when answering integration questions.
> Do not infer support for currencies, networks, scopes, account types, or operations that are not present in the current documentation.
> Use the sandbox base URL (https://api.sandbox.augustus.com) and placeholder credentials in examples. Never include or request a real API key.
> The Augustus docs MCP server (https://docs.augustus.com/mcp) provides documentation search and retrieval only; it does not execute authenticated Augustus API actions.

# Integration flow

> Everything you need to let customers pay in money via Open Banking

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.

<Note>
  Open Banking is available only in the 2023-01-01 API
</Note>

## Flow

<Steps>
  <Step title="Create a Checkout Session">
    Submit payment parameters and receive a `redirectUrl`.
  </Step>

  <Step title="Redirect the customer">
    Send the customer to `redirectUrl` for the Augustus-hosted bank selection and authorization screens.
  </Step>

  <Step title="Return to your app">
    The customer lands back at your `successCallbackUrl` or `errorCallbackUrl`.
  </Step>

  <Step title="Track the order">
    Subscribe to `order_updated` webhooks for real-time status.
  </Step>
</Steps>

<Frame caption="Open Banking sequence diagram">
  <img src="https://mintcdn.com/getivy/J1t6OrlJaZyvflSC/images/docs/d177ae7-Ivy_Checkout_-_Sequence_diagram.png?fit=max&auto=format&n=J1t6OrlJaZyvflSC&q=85&s=90c17dfbae711ff85a55d8423b330c5e" alt="" width="1489" height="1040" data-path="images/docs/d177ae7-Ivy_Checkout_-_Sequence_diagram.png" />
</Frame>

## Create a Checkout Session

```ts 2023-01-01 theme={null}
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 →](/api-reference/checkout/create-a-checkout-session)

### 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](/docs/payin/instant-bank-transfer/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](/docs/payin/instant-bank-transfer/iframe).

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

```ts server/routes/webhooks.ts theme={null}
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](/docs/payin/instant-bank-transfer/payment-status) for the full lifecycle, [Failure reasons](/docs/payin/instant-bank-transfer/failure-reasons) for `statusClassification`, and [Webhooks](/webhook-getting-started/introduction) for setup and signature verification.