Skip to main content

Troubleshooting

When integrating banking connect flows, you may encounter some common issues. Below are some troubleshooting tips to help you resolve these problems.

Purpose and Scope​

This guide provides structured troubleshooting support for issues occurring during:

  • Bank connection establishment
  • Consent management and renewal
  • Synchronization processes
  • Webhook delivery
  • Recurring background synchronization

It covers typical failure scenarios for banking connections and synchronization.

This guide is intended for:

  • Technical support teams
  • Integration engineers
  • Operations teams

Quick Triage Checklist​

Before investigating protocol-specific details, verify the following:

Session Validation​

Bank Login Status​

Use: Get Logins Synchronization Status

Check:

  • status
    • OK
    • SCA_REQUIRED
    • SYNC_FAILED
  • active
  • lastSynchronization
  • Is there a valid consent?
  • Has the consent expired?
  • Was a new consent created that invalidated a previous one?
  • Refer to the above bank login status for the consent status.

Webhook Configuration​

  • Is webhook configuration active?
  • Is webhook endpoint reachable?
  • Are webhook signatures verified correctly?
  • Are responses returning HTTP 2xx?

Connection Establishment Issues​

User Cannot Select Bank​

Symptoms

  • Bank not found in search
  • Bank selectable but connection fails immediately

Possible Causes

  • Bank interface temporarily unavailable
  • Bank removed or migrated to new interface
  • Regional restrictions
  • Maintenance window

Actions

  • Verify bank availability at their own online banking portal
  • Retry after short delay
  • Escalate if issue persists across multiple users

Account Type Not Available​

Symptoms

  • User cannot see expected account types (e.g., credit card missing)

Possible Causes

  • Bank exposes different account types per interface
  • Selected interface does not support requested account type
  • Bank-side filtering

Actions

  • Verify selected account type during connection
  • Retry using alternative available interface
  • Inform user that availability depends on bank configuration

Authentication Fails During Login​

Common Root Causes

  • Invalid credentials
  • Account locked
  • Multifactor authentication required
  • Redirect URI mismatch
  • Session timeout

Actions

  • Verify user credentials
  • Confirm bank access works directly in bank app/website
  • Check for multifactor setup changes
  • Retry after ensuring no account lock

SCA Flow Issues​

Embedded SCA Fails​

Possible Causes

  • TAN expired
  • Challenge timed out
  • Incorrect TAN
  • Device binding changed

Decoupled SCA Not Confirmed​

Possible Causes

  • User did not approve in banking app
  • Approval window expired
  • Push notification disabled

Redirected Flow Breaks​

Possible Causes

  • Redirect URI mismatch
  • User manually closed window
  • Third-party cookie blocking
  • Session timeout

General Actions

  • Restart connection session
  • Ensure user completes SCA within allowed timeframe
  • Confirm redirect URL configuration
  • Check OAuth callback handling

Detection

  • status = SCA_REQUIRED
  • Webhook ubasyncerror with type = CHALLENGE_REQUIRED

Resolution Options

Notes

  • Only one valid consent per bank login
  • New consent invalidates previous one
  • User interaction is mandatory

SYNC_FAILED Status​

Possible Causes

  • Bank API temporarily unavailable
  • Rate limiting
  • Interface change
  • Authentication error during background sync

Actions

  • Retry manual synchronization
  • Check webhook payload for error details
  • Escalate if persistent

Duplicate Bank Logins​

Symptoms

  • Same bank account appears twice
  • Multiple bank logins for same user and bank

Causes

  • Duplicate connection attempt

Resolution

  • Identify active bank login
  • Delete obsolete login
  • Ensure users are guided to Management Session for additional accounts

Synchronization Issues​

Manual Synchronization Not Triggering​

Checklist

  • Valid consent?
  • Bank login active?
  • Correct bankLoginId used?

If consent expired:

  • User must complete SCA challenge

Recurring Synchronization Not Running​

Check

  • active = true
  • No recent SCA_REQUIRED
  • Webhook subscription active

Common Causes

  • Consent expired silently
  • Bank-side downtime
  • Recurring user flag not set

Background Sync Stops After Error​

By design:

  • Automatic synchronization is disabled if user action required

Resolution:

  • Trigger renewal via management session
  • After renewal, confirm active = true

Webhook Delivery Issues​

Webhook Not Received After Connection​

Checklist

  • Webhook configured?
  • Endpoint publicly reachable?
  • TLS certificate valid?
  • Returns HTTP 2xx?

Common Causes

  • 4xx or 5xx response
  • Timeout on receiver side
  • IP allowlisting missing

Webhook Not Received After Sync​

Possible causes

  • Sync failed
  • Consent expired
  • Recurring disabled
  • Delivery failed and retried unsuccessfully

Check

  • Synchronization status
  • Webhook logs

Escalation Guidelines​

Escalate if:

  • Same issue affects multiple users for same bank
  • Persistent SYNC_FAILED across retries
  • Bank interface recently changed
  • Webhook delivery failing across tenants

Provide when escalating:

  • userId
  • bankLoginId
  • ID of failing request or error code from UI
  • Bank name
  • Timestamp of failure
  • Synchronization status response

For recurring setups:

  • Periodically poll synchronization status
  • Subscribe to webhook error events

Alert on:

  • SCA_REQUIRED
  • SYNC_FAILED
  • inactive recurring connections
  • Track lastSynchronization timestamps

Known Operational Characteristics​

  • Only one valid consent per bank login
  • Consent always tied to bank login, not account level
  • User interaction mandatory for renewal
  • Recurring sync disabled automatically after challenge-required errors
  • Synchronization schedule not configurable
  • Bank behavior may differ per account type and interface