Visa: Instant Account Verification

Overview

This guide dives into leveraging Dwolla’s Open Banking Services in collaboration with Visa, a world leader in digital payments, to streamline bank account verification within your Dwolla-powered application. Open banking empowers your users to more securely share their financial data with Dwolla and your application, eliminating the need for manual entry and improving the overall user experience. We’ll walk you through the steps to set up and integrate Visa Instant Account Verification (Visa IAV) using Dwolla’s Exchange Sessions API. Dwolla’s powerful Exchange Sessions API acts as the bridge between your application and Visa Open Banking Solutions. This established connection facilitates real-time verification of your user’s bank account details. To gain hands-on experience, we recommend following along with the provided integration-examples sample app, which provides a practical understanding of the integration process for your own application. Instant Account Verification (IAV) is a one-time process that verifies the account being added by an end user is open and active. At the end of this guide, you’ll obtain a Funding Source URL, which is a unique identifier that represents a bank account being used for account-to-account payments.

Prerequisites

Before starting the integration, make sure you have taken the following steps:

Set up a Dwolla Production account, or a Dwolla Sandbox account if you’re still developing or testing your application.
Before creating a funding source, your application will need to create a Customer. If you have not created a Customer yet, check out our Create a Customer API documentation.
Ensure you have a redirect URL registered with Dwolla. This is where the user lands after completing the IAV flow.

Contact Sales to set up a redirect URL for the Visa IAV flow. Verify your API keys have the required permissions.

Sandbox Testing

Testing within the sandbox environment is an essential step before deploying the Visa IAV solution to a production environment. The sandbox acts as a safe, isolated testing ground that mirrors real-world scenarios with test data. This allows you to validate the functionality of your integration without using actual user accounts or financial information. By thoroughly testing in the sandbox, you can identify and correct any potential issues before they impact your live users.

Demo Bank Test Credentials

When an end-user opens the Exchange Session URL, they are prompted to authenticate with their bank and choose a bank account to link. When testing Visa IAV in the sandbox environment, you can use the following test credentials for the Demo Bank to simulate different scenarios.

User	Username	Password	Description	Result
User 1	u51613239	cty440	User has successfully authenticated but no account information could be found	✅ Successful
User 2	u35490150	ckr403	Report with full information	✅ Successful
User 3	u92721594	nbs589	User failed to authenticate themselves at the financial institution	❌ Authentication error
User 4	u91902655	jtx720	Temporary error with a Visa service	❌ Temporary error

Dwolla Node SDK for API Interactions

Throughout this guide, we’ll assume you’re using the Dwolla Node SDK to interact with Dwolla’s API endpoints. This SDK simplifies making requests and handling responses for various Dwolla functionalities.

While we are using Dwolla’s Node SDK for the sake of demonstration in this guide, Dwolla also offers additional libraries for other server-side programming languages.

Demo

Visa Open Banking Demo

Coast Demo: Visa Open Banking Flow

Steps to Integrate

Step 1 - Initiate Exchange Session

Use Dwolla’s API endpoint to create an exchange session to initiate an Exchange Session for a Customer. Specify Visa as the desired open banking provider within the request body. The Exchange Partner ID for Visa can be found by calling the List Exchange Partners API endpoint.

Redirect URL Validation

When using Visa as the exchange partner for an exchange session, a redirect URL is required. This URL specifies where the user will be redirected after completing the authorization process with Visa. Dwolla will validate the provided redirect URL against the one previously configured for your application.

Guidelines:

Ensure your configured redirect URL with Dwolla exactly matches the one you include in the request body (including protocol, domain, port, and path).
Use HTTPS for your redirect URL to enhance security.
Consider whitelisting your redirect URL to restrict redirects to specific domains.

Example using Dwolla Node SDK

import { Client } from "dwolla-v2";
const dwolla = new Client({
  key: "YOUR_KEY",
  secret: "YOUR_SECRET",
  environment: "sandbox", // or 'production'
});

/**
 * Gets Visa's exchange partner href (link) within Dwolla's systems.
 */

export async function getExchangePartnerHref() {
  try {
    const response = await dwolla.get("/exchange-partners");
    const partnersList = response.body._embedded["exchange-partners"];
    const visaPartner = partnersList.filter(
      (obj: { name: string }) => obj.name.toLowerCase() === "visa"
    )[0];
    return visaPartner._links.self.href;
  } catch (error) {
    // Return an error message or handle the error appropriately
  }
}

/**
 * Creates an exchange session for a customer
 * @param customerId - The ID of the customer to create the exchange session for.
 */

export async function createExchangeSession(customerId: string) {
  const exchangePartnerHref = await getExchangePartnerHref();
  const requestBody = {
    _links: {
      "exchange-partner": {
        href: exchangePartnerHref,
      },
      "redirect-url": {
        href: "https://www.yourdomain.com/iav-callback",
      },
    },
  };
  try {
    const response = await dwolla.post(
      `customers/${customerId}/exchange-sessions`,
      requestBody
    );
    const location = response.headers.get("location");
    return location;
  } catch (error) {
    // Return an error message or handle the error appropriately
  }
}

// Example usage:

const exchangeSessionUrl = createExchangeSession(customerId); // => https://api.dwolla.com/exchange-sessions/fcd15e5f-8d13-4570-a9b7-7fb49e55941d

Step 2 - Retrieve Exchange Session and Complete Tink/Visa Link Flow

In this step, you’ll retrieve the exchange session details, including the Exchange Session URL. This URL is used to initiate the Visa Link flow within your application. Use the exchange session ID obtained in Step 1 to call Dwolla’s Retrieve an Exchange Session endpoint. During this flow, the user interacts with Visa’s interface to authorize their bank account information to be shared.

Example using Dwolla Node SDK

/**
 * Retrieves an exchange session URL by ID
 * @param exchangeSessionId - The ID of the exchange session to retrieve.
 */

export async function getExchangeSession(exchangeSessionId: string) {
  try {
    const response = await dwolla.get(
      `/exchange-sessions/${exchangeSessionId}`
    );
    const externalProviderSessionUrl =
      response.body._links["external-provider-session"].href;
    return externalProviderSessionUrl;
  } catch (error) {
    // Return an error message or handle the error appropriately
  }
}

// Example usage:
const visaExchangeSessionUrl = getExchangeSession(exchangeSessionId); // => "https://link.visa.com/1.0/account-check/connect?client_id=f16f7c7407f4434dbcaf269b230c12ed&redirect_uri=https://api-uat.dwolla.com/redirect/tink&authorization_code=47e23deab3924351a0c6193d90e5add5&market=US&locale=en_US&state=a2V5Ojk6dWRiRkRYWGlIVGdZZUNycUdCa0s3Zz09OmI1ZVE0YWRUYkFrSWNiKzFxTXdmQlVkcVNWWW5nMjtQNjBaWERxUDh5aTBpWEQzTHROdUZRd2xLMTUzYnZ4RU8=&session_id=628d927030ee43a38054da5166dcbee14e06dc02c00e45f2b4a5d986bab5d08f"

Redirect User - Next.js Example

import { useRouter } from "next/navigation";
const router = useRouter();

/**
 * Redirects the user to the Visa exchange session URL.
 */

router.push(visaExchangeSessionUrl);

Step 3 - Handle User Redirect

After completing the Visa IAV flow, Visa redirects the user back to your registered URL. This redirect URL will include a query string parameter of “exchange” or an “error” depending on the outcome of the Visa IAV flow. You’ll need to implement logic to route the user based on if the flow completed successfully or if there was an error.

Example Success and Error redirect URL

https://www.myapp.com/iav-redirect?exchange=10cde28b-6a39-4ed1-bce9-aa611a360720

https://www.myapp.com/iav-redirect?error=USER_CANCELLED

Parse the Redirect URL:

Upon receiving the user redirect, you need to capture the complete URL and extract relevant query parameters, such as the “exchange” parameter, which will contain information about the outcome of the IAV flow.

Handle Successful Verification Example - Using Next.js

import { useSearchParams } from "next/navigation";

function HandleUserRedirect() {
  /**
   * Get the exchangeId from the URL query parameters.
   */

  const searchParams = useSearchParams();
  const exchangeId = searchParams.get("exchange");
}

Handle Error - Example Using Next.js

import { useSearchParams } from "next/navigation";
function HandleUserRedirect() {
  /**
   * Get the error from the URL query parameters.
   */

  const searchParams = useSearchParams();
  const error = searchParams.get("error");
}

Errors

The Visa Link flow may lead to a recoverable error or a non-recoverable error which can’t be resolved by the user. In such cases, it’s important to provide clear and actionable messages to the user, and/or return the user to the pre-verification step based on the error. The decision to present an error screen or return the user to the pre-verification step depends on the specific error and your application’s design. Here’s a general guideline: Recoverable Errors: These are issues that can potentially be resolved by the user. In such cases, it’s important to provide clear and actionable messages to the user. An error screen is often suitable for recoverable errors. This allows the user to review the specific message, make corrections and retry the IAV process.

Examples:
- Invalid Credentials: The user might have entered incorrect bank login credentials. The error message should prompt the user to double-check their information and try again.
- Temporary Network Issues: A temporary network glitch might interrupt the communication. The message could suggest the user retry after a short while.
- User Cancelled: The user decided to abandon the Visa IAV process. Your application should acknowledge this and allow them to resume if needed.

Non-Recoverable Errors: These are more severe issues that cannot be resolved by the user and require intervention from your business or their bank. In these cases, the user should be informed of the issue and provided with instructions for contacting the right party for support. If a user reaches out to you about a system error, please contact Dwolla Support for assistance.

Examples:
- System Errors: Internal system errors within Dwolla or Visa’s infrastructure may prevent successful verification. The message should apologize for the inconvenience and direct the user to contact your support team.
- Account Lockout: The user’s bank account might be locked due to security reasons. The message should explain this possibility and advise the user to contact their bank directly.

List of possible redirect errors

Error Code	Description
AUTHENTICATION_ERROR	The error occurred during the authentication process with the bank.
USER_CANCELLED	The end user canceled the journey, either by going back or selecting the close button.
TEMPORARY_ERROR	A temporary error in Visa’s platform or a network issue. To resolve any of these errors, try again later.

Step 4 - Funding Source Creation

After successfully creating the exchange, the next step is to create a funding source for the customer. This involves calling Dwolla’s Create a Funding Source endpoint, where you’ll provide the exchange resource obtained from the previous step. In the following function, once a response is received, it will extract the Location header value, which is the fully-qualified URL specifying the resource location of your funding source.

/**
 * Creates a funding source for a customer.
 * @param options - The options including customerId, exchangeId, name, and type.
 */

export async function createFundingSource(options: CreateFundingSourceOptions) {
  const { customerId, exchangeId, name, type } = options;
  const exchangeUrl = "https://api.dwolla.com/exchanges/${exchangeId}";
  const requestBody = {
    _links: {
      exchange: {
        href: exchangeUrl,
      },
    },
    bankAccountType: type,
    name: name,
  };
  try {
    const response = await dwolla.post(
      `customers/${customerId}/funding-sources`,
      requestBody
    );
    const location = response.headers.get("location");
    return location;
  } catch (error) {
    // Return an error message or handle the error appropriately
  }
}

// Example usage:
const fundingSource = createFundingSource({
  customerId: "yourCustomerId",
  exchangeId: "exchangeId",
  name: "Your Funding Source Name",
  type: "checking", // or 'savings'
}); // https://api.dwolla.com/funding-sources/63508b1b-36be-4d68-b497-42eb7884b82d

Handling Re-authentication

When users initially connect their bank account via Instant Account Verification, they authenticate with their bank and grant permission to access their account information. This allows Dwolla to perform actions like checking bank balances. However, this access can be interrupted by changes on the bank’s end, such as a password update, multi-factor authentication reset, or revoked consent. To maintain a smooth user experience, your application needs to handle these scenarios gracefully. Dwolla’s API provides an UpdateCredentials error response to signal when a user’s bank connection needs to be refreshed.

`UpdateCredentials` error response

{
    "code": "UpdateCredentials",
    "message": "Re-authentication is required in order to access account data. Please initiate the exchange session flow to regain access.",
    "_links": {
        "about": {
            "href": "https://api.dwolla.com/exchanges/036c8a60-fa45-45d4-8f5d-181d348c6ec8/exchange-sessions",
            "type": "application/vnd.dwolla.v1.hal+json",
            "resource-type": "exchange-session"
        }
    }
}

Steps to manage re-authentication

Detect the UpdateCredentials error: When making calls to Dwolla’s API (e.g., checking a bank balance), implement error handling to catch the UpdateCredentials response, which is an HTTP 400 error.
Communicate with your user: It’s crucial to inform the user why they need to re-authenticate and how to do so. Use clear and concise language in in-app messages, emails, or text messages to guide them back to your application to complete the process.
Initiate the re-authentication flow: Upon receiving this error, redirect the user to re-authenticate their bank account. This is done by creating a new re-authentication exchange session. This will guide the user through the necessary steps to re-establish their bank connection.

By following these steps, you can ensure that your application can handle interruptions to bank connections effectively, providing a smooth and user-friendly experience.

Initiate re-authentication exchange-session

Use Dwolla’s API endpoint to create a re-authentication exchange session to initiate an Exchange Session for a Customer. Specify A redirect URL within the request body which is required for Visa exchange sessions. This URL will be used to redirect the user back to your application after completing the re-auth process.

Example using Dwolla Node SDK

import { Client } from "dwolla-v2";
const dwolla = new Client({
  key: "YOUR_KEY",
  secret: "YOUR_SECRET",
  environment: "sandbox", // or 'production'
});

/**
 * Creates a re-auth exchange session for a customer
 * @param exchangeId - The ID of the deactivated exchange to complete the re-authentication process.
 */

export async function initiateReauthentication(exchangeId: string) {
  const requestBody = {
    _links: {
      "redirect-url": {
        href: "https://www.yourdomain.com/iav-callback",
      },
    },
  };
  try {
    const response = await dwolla.post(
      `exchanges/${exchangeId}/exchange-sessions`,
      requestBody
    );
    const location = response.headers.get("location");
    return location;
  } catch (error) {
    // Return an error message or handle the error appropriately
  }
}

// Example usage:

const reauthExchangeSessionUrl = initiateReauthentication(exchangeId); // => https://api.dwolla.com/exchange-sessions/fcd15e5f-8d13-4570-a9b7-7fb49e55941d

Resources

Integration Example App

Introduction

Getting Started

Quickstarts

Customers

Funding Sources

Transfers

Integrations

Webhooks & Notifications

Overview

Prerequisites

Sandbox Testing

Demo Bank Test Credentials

Dwolla Node SDK for API Interactions

Demo

Visa Open Banking Demo

Steps to Integrate

Step 1 - Initiate Exchange Session

Redirect URL Validation

Guidelines:

Example using Dwolla Node SDK

Step 2 - Retrieve Exchange Session and Complete Tink/Visa Link Flow

Example using Dwolla Node SDK

Redirect User - Next.js Example

Step 3 - Handle User Redirect

Example Success and Error redirect URL

Parse the Redirect URL:

Handle Successful Verification Example - Using Next.js

Handle Error - Example Using Next.js

Errors

List of possible redirect errors

Step 4 - Funding Source Creation

Handling Re-authentication

`UpdateCredentials` error response

Steps to manage re-authentication

Initiate re-authentication exchange-session

Example using Dwolla Node SDK

Resources

Introduction

Getting Started

Quickstarts

Customers

Funding Sources

Transfers

Integrations

Webhooks & Notifications

​Overview

​Prerequisites

​Sandbox Testing

​Demo Bank Test Credentials

​Dwolla Node SDK for API Interactions

​Demo

Visa Open Banking Demo

​Steps to Integrate

​Step 1 - Initiate Exchange Session

​Redirect URL Validation

Guidelines:

​Example using Dwolla Node SDK

​Step 2 - Retrieve Exchange Session and Complete Tink/Visa Link Flow

​Example using Dwolla Node SDK

​Redirect User - Next.js Example

​Step 3 - Handle User Redirect

Example Success and Error redirect URL

Parse the Redirect URL:

​Handle Successful Verification Example - Using Next.js

​Handle Error - Example Using Next.js

​Errors

List of possible redirect errors

​Step 4 - Funding Source Creation

​Handling Re-authentication

UpdateCredentials error response

​Steps to manage re-authentication

​Initiate re-authentication exchange-session

​Example using Dwolla Node SDK

​Resources

Overview

Prerequisites

Sandbox Testing

Demo Bank Test Credentials

Dwolla Node SDK for API Interactions

Demo

Steps to Integrate

Step 1 - Initiate Exchange Session

Redirect URL Validation

Example using Dwolla Node SDK

Step 2 - Retrieve Exchange Session and Complete Tink/Visa Link Flow

Example using Dwolla Node SDK

Redirect User - Next.js Example

Step 3 - Handle User Redirect

Handle Successful Verification Example - Using Next.js

Handle Error - Example Using Next.js

Errors

Step 4 - Funding Source Creation

Handling Re-authentication

`UpdateCredentials` error response

Steps to manage re-authentication

Initiate re-authentication exchange-session

Example using Dwolla Node SDK

Resources