Integration Guide

This guide walks you through integrating Volt Verify into your application. By the end, you'll be able to verify bank account ownership in real-time.

Available Markets

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

Prerequisites

Before you begin, ensure you have:

Fuzebox account with Verify access enabled

Customer credentials (Username/Password)

Application credentials (Client ID/Client Secret)

Sandbox environment access for testing

→ Set up your Fuzebox account

Step 1: Authenticate

Obtain an access token using your credentials:

curl -X POST https://api.sandbox.volt.io/oauth \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "username=YOUR_USERNAME" \
  -d "password=YOUR_PASSWORD"

→ Full authentication details

Step 2: Request account access

Initiate an account access request to start the verification flow:

curl -X POST https://api.sandbox.volt.io/account-access \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "currencyCode": "EUR",
    "country": "DE",
    "callback": "https://your-app.com/verify/callback",
    "payer": {
      "reference": "customer_123",
      "email": "customer@example.com"
    }
  }'

Request parameters

Parameter	Required	Description
`currencyCode`	Yes	Currency code (EUR for Austria/Germany)
`country`	Yes	ISO country code (`AT` or `DE`)
`callback`	Yes	URL to redirect user after bank authorisation
`payer.reference`	Yes	Your unique reference for this customer
`payer.email`	No	Customer's email address

Response

{
  "id": "acc_abc123def456",
  "status": "AWAITING_AUTHORIZATION",
  "accountAccessFlow": {
    "status": "PROCESSING",
    "details": {
      "reason": "AWAITING_USER_REDIRECT",
      "redirect": {
        "url": "https://vo.lt/verify/XY123"
      }
    }
  }
}

Step 3: Redirect user to bank

Redirect the user to the URL provided in the response. The user will:

Select their bank
Authenticate with their bank credentials
Consent to sharing account information
Be redirected back to your callback URL

// Redirect user to Volt's hosted bank selection
window.location.href = response.accountAccessFlow.details.redirect.url;

Step 4: Handle the callback

After bank authorisation, the user is redirected to your callback URL with query parameters:

https://your-app.com/verify/callback?accountAccessId=acc_abc123def456&status=COMPLETED

Callback parameters

Parameter	Description
`accountAccessId`	The account access request ID
`status`	Current status (`COMPLETED`, `FAILED`, `CANCELLED`)

Step 5: Retrieve account information

Once the status is COMPLETED, fetch the account details:

curl -X GET https://api.sandbox.volt.io/account-access/acc_abc123def456 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response

{
  "id": "acc_abc123def456",
  "status": "COMPLETED",
  "accounts": [
    {
      "iban": "DE89370400440532013000",
      "accountHolderName": "Max Mustermann",
      "currency": "EUR",
      "accountType": "CURRENT"
    }
  ],
  "payer": {
    "reference": "customer_123"
  }
}

Step 6: Verify the account holder

Compare the returned accountHolderName with your customer's name.

Note: Bank account names may differ from customer-provided names (e.g., "Max" vs "Maximilian"). Implement appropriate name matching logic for your use case.

Account access statuses

Status	Description
`AWAITING_AUTHORIZATION`	Waiting for user to authorize at bank
`PROCESSING`	Authorization in progress
`COMPLETED`	Account information retrieved successfully
`FAILED`	Authorization failed
`CANCELLED`	User cancelled the authorization
`EXPIRED`	Authorization request expired

Error handling

Handle errors gracefully in your integration:

{
  "error": {
    "code": "AUTHORIZATION_FAILED",
    "message": "User denied consent at the bank"
  }
}

Common error codes:

Code	Description	Action
`AUTHORIZATION_FAILED`	User denied consent	Show friendly message, allow retry
`INSTITUTION_ERROR`	Bank-side error	Retry later or try different bank
`EXPIRED`	Request timed out	Start new verification flow
`INVALID_REQUEST`	Missing/invalid parameters	Check request payload