Authorisation Flows

When a user authorises access to their bank account, the flow depends on the bank (institution) they're using. Verify supports all standard Open Banking authorisation flows.

Available Markets

Verify is currently available in Austria and Germany. More countries coming soon.

Overview

The authorisation flow determines how a user authenticates with their bank and consents to sharing account information. There are three main flows:

Flow	User Experience	Common In
Redirect	User redirected to bank website/app	Most banks
Embedded	Credentials entered in your app	Some German banks
Decoupled	Approval via separate banking app	Mobile-first banks

Redirect Flow

The most common authorisation flow. The user is redirected to their bank's website or app to authenticate and provide consent.

Sequence

Your App → Volt → Bank Website → Bank Auth → Consent → Volt → Your App

Initiate account access

Your app calls the Verify API to start the flow.

Redirect to bank

User is redirected to Volt's bank selection page, then to their bank.

Authenticate at bank

User logs in using their bank credentials (username, password, 2FA).

User reviews and approves sharing account information.

Return to your app

User is redirected back to your callback URL with the result.

API Response

When redirect is needed, the API returns:

{
  "accountAccessFlow": {
    "status": "PROCESSING",
    "details": {
      "reason": "AWAITING_USER_REDIRECT",
      "redirect": {
        "url": "https://vo.lt/verify/XY123",
        "directUrl": "https://bank.de/authorize?session=abc"
      }
    }
  }
}

Field	Description
`url`	Volt's hosted page with bank selection
`directUrl`	Direct link to bank (if bank already selected)

Embedded Flow

With the embedded flow, the user's banking credentials are captured directly in your application (or Volt's hosted page) and sent to the bank for authentication.

Sequence

Your App → Credentials Input → Volt → Bank API → Your App

Capture credentials

User enters their bank login details in your UI or Volt's hosted page.

Submit to bank

Volt sends credentials to the bank's API for authentication.

Handle challenges

Bank may request additional authentication (SMS code, push notification).

Receive result

Account information is returned if successful.

API Response

When embedded authentication is needed:

{
  "accountAccessFlow": {
    "status": "PROCESSING",
    "details": {
      "reason": "AWAITING_CREDENTIALS",
      "fields": [
        {
          "name": "username",
          "type": "TEXT",
          "label": "Bank Username"
        },
        {
          "name": "password",
          "type": "PASSWORD",
          "label": "Bank Password"
        }
      ]
    }
  }
}

Submitting credentials

curl -X PATCH https://api.volt.io/account-access/{id} \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "credentials": {
      "username": "user_input",
      "password": "user_password"
    }
  }'

Security note: If implementing embedded flow yourself, ensure credentials are transmitted securely and never stored. Consider using Volt's hosted page which handles this securely.

Decoupled Flow

With decoupled authorisation, the user approves the request through a separate channel - typically their mobile banking app.

Sequence

Your App → Volt → Bank API → Push to User's Phone → User Approves → Volt → Your App

{
  "accountAccessFlow": {
    "status": "PROCESSING",
    "details": {
      "reason": "AWAITING_DECOUPLED_AUTHORIZATION",
      "message": "Please approve the request in your banking app"
    }
  }
}

Polling for status

curl -X GET https://api.volt.io/account-access/{id} \
  -H "Authorization: Bearer YOUR_TOKEN"

Handling multiple flows

The authorisation flow is determined by the bank, not by you. Your integration should handle all three flows:

async function handleAccountAccess(response) {
  const { accountAccessFlow } = response;
  
  switch (accountAccessFlow.details.reason) {
    case 'AWAITING_USER_REDIRECT':
      // Redirect flow
      window.location.href = accountAccessFlow.details.redirect.url;
      break;
      
    case 'AWAITING_CREDENTIALS':
      // Embedded flow - show credential form
      showCredentialForm(accountAccessFlow.details.fields);
      break;
      
    case 'AWAITING_DECOUPLED_AUTHORIZATION':
      // Decoupled flow - show message and poll
      showMessage(accountAccessFlow.details.message);
      startPolling(response.id);
      break;
      
    default:
      // Handle completed or error states
      handleResult(response);
  }
}

Flow comparison

Aspect	Redirect	Embedded	Decoupled
User leaves your app	Yes	No	No
Credential handling	Bank handles	You/Volt handles	Bank handles
2FA support	Full	May require challenges	Via banking app
Mobile experience	Varies	Good	Best
Implementation complexity	Low	Medium	Medium

Best practices

Use Volt's hosted page - It handles all flows automatically
Don't assume a flow - Always check the API response
Handle timeouts - Decoupled flows may take time
Provide clear messaging - Tell users what to expect
Test all flows - Different banks use different flows

Integration Guide

Step-by-step integration

Payment Initiation Flows

Similar flows for payments

Authorisation Flows

Overview

Redirect Flow

Sequence

Initiate account access

Redirect to bank

Authenticate at bank

Return to your app

API Response

Embedded Flow

Sequence

Capture credentials

Submit to bank

Handle challenges

Receive result

API Response

Submitting credentials

Decoupled Flow

Sequence

Initiate request

Bank sends push notification

User approves in app

Poll for completion

API Response

Polling for status

Handling multiple flows

Flow comparison

Best practices

Integration Guide

Payment Initiation Flows

On this page