Instant Account Verification (IAV)

Instant Account Verification (IAV)

Instant Account Verification (IAV)

Link Money’s Instant Account Verification (IAV) is a safe, secure, and fast way to instantly connect verified accounts in real time with reduced risk. Developers using IAV gain access to verified accounts which can be used to facilitate ACH transfers.

What is Instant Account Verification?

At the core of financial technology lies the ability to move money. Most modern fintech applications move money in some capacity - whether transferring to a savings account, creating a piggy bank, or funding an investment account, money movement makes fintechs run. Instant Account Verification, or IAV, offers developers a fast and secure method for retrieving the data required to initiate transfers on the user’s behalf.

This documentation is for developers who want to set up and use IAV on their own application to get verification details which they can pass to applications and APIs that facilitate money transfers. If you are a developer who only needs account and transaction data without full account numbers, refer to the LinkMoney Quickstart to set up up Link Money with aggregation.

This documentation offers a series of quickstart guides to help developers get started with Link Money IAV specifically. For a more generic quickstart to implementing the Link Money API for aggregation, see the LinkMoney Quickstart.

Plaid Identity Quickstart

Prerequisites

This quickstart is intended as a supplement to the Plaid

quickstart. The Switch Kit quickstart covers linking accounts, grabbing Plaid accounts from callback data, and pulling Plaid transactions from the API.

What is Plaid Identity?

During the aggregation process, we pull account and transaction data from users’ financial institutions and surface it in the aggregation APIs. It is also possible to pull additional account information - like account holder details, account numbers, and PII - through the verification process.

Because this data is more sensitive, it is not returned in accounts or transactions API requests. To grab account holder information, we must use the identity route.

To get identity, you must use an item-specific token (see

). If you followed the Switch Kit quickstart, the item-specific token you generated will still work for identity. 

var axios = require('axios');
var data = JSON.stringify({
  "options": {}
});

var config = {
  method: 'post',
  url: '{LINK_MONEY_BASE_URL}/v1/plaid/identity/get',
  headers: { 
    'Authorization': 'Bearer {YOUR_ITEM_TOKEN}', 
    'Content-Type': 'application/json'
  },
  data: data
};

try {
	const response = await axios(config);
} catch(error) {
	console.log(error);
}

If you want to restrict the accounts for which you receive identity information, you may include account_ids as an array in your request body options: 

var data = JSON.stringify({
  "options": {
		"account_ids": ["1234567"]
	}
});

If the call succeeds, you will receive account information along with holder identity details for each account in the return data. The added identity details are in under the owners property. As an example:

{
    "accounts": [
        {
            "account_id": "1234567",
            "balances": {
                "limit": null,
                "current": 2276.78,
                "available": 2276.78,
                "iso_currency_code": null,
                "unofficial_currency_code": null
            },
            "name": "Lyra's Savings",
            "mask": "1111",
            "official_name": "Bank of the North Preferred Savings",
            "type": "depository",
            "subtype": "savings",
            "owners": [
                {
                    "addresses": [
                        {
                            "data": {
                                "city": "Louisville",
                                "country": "US",
                                "postal_code": "80027",
                                "region": "CO",
                                "street": "1054 example drive"
                            },
                            "primary": true
                        }
                    ],
                    "emails": [
                        {
                            "data": "PrimaryEmail@y.com",
                            "primary": true,
                            "type": "primary"
                        },
                        {
                            "data": "SecondaryEmail@y.com",
                            "primary": false,
                            "type": "secondary"
                        },
                        {
                            "data": "PersonalEmail@y.com",
                            "primary": false,
                            "type": "personal"
                        },
                        {
                            "data": "workEmail@y.com",
                            "primary": false,
                            "type": "work"
                        },
                        {
                            "data": "OthersEmail@y.com",
                            "primary": false,
                            "type": "others"
                        },
                        {
                            "data": "AccountEmai@y.com",
                            "primary": false,
                            "type": "others"
                        }
                    ],
                    "names": [
                        "Lyra Belacqua"
                    ],
                    "phone_numbers": [
                        {
                            "data": "8095190932",
                            "primary": false,
                            "type": "home"
                        },
                        {
                            "data": "8095190933",
                            "primary": false,
                            "type": "work"
                        },
                        {
                            "data": "8095190931",
                            "primary": false,
                            "type": "landline"
                        },
                        {
                            "data": "8095190934",
                            "primary": false,
                            "type": "mobile"
                        }
                    ]
                }
            ]
        }
    ]
}
Schemas

address: {
	data: {
		city: String,
		country: String,
		postal_code: String,
		region: String,
		street: String,
	}
	primary: boolean
}

phone_number: {
	data: String; // the number itself
	primary: boolean,
	type: String,
}

email: {
	data: String, // the address itself
	primary: boolean,
	type: string
}

Note that not all of these fields return for every account - some institutions do not yet support account verification, while others may only supply limited data. Refer to the endpoints if you wish to know the verification availability for a particular financial institution.

Plaid Auth Endpoints

Plaid Auth Webhooks

Yodlee Account Verification

‣

Verification Flows

Instant Account Verification (IAV) configuration is specified by the developer in the Link Money Gateway. A developer can initiate three IAV-specific user experiences in the gateway (note that standalone aggregation is also an option, though not included here):

  • Standalone IAV lets users verify their accounts and exit the Link Money Gateway. If the verification is successful, the resulting account data can be used for transfers.
ℹ️
Use standalone IAV when you only need accounts verified.
  • IAV & Aggregation lets users verify their accounts for use in transfers; following this initial verification, the user is prompted with an optional step to aggregate transaction data for their verified accounts.
ℹ️
Use IAV & Aggregation when you need account verification but would like aggregation if possible. If a provider doesn’t support verification, aggregation will not be offered to the user.
  • Aggregation & IAV lets users link their accounts for aggregation of accounts and transaction data; following the initial aggregation, the user is prompted with an optional step to verify the accounts they’ve aggregated from for use in transfers.
ℹ️
Use Aggregation & IAV when you need aggregation but would like accounts to be verified if possible.

The Verification User Experience

1. The User Authenticates with a Third-Party Financial Institution.

Every time a user loads the Link Money Gateway, some authentication is acquired. See Authentication for information on how to get a LinkMoney JSON web token, and the LinkMoney Quickstart or generic information on accessing the portal.

When the user loads the LinkMoney Gateway in their browser, they are prompted with an account selection screen.

The user may be prompted either with an Open Banking login (a direct connection with their banking application) or a login from that runs directly from the LinkMoney Gateway.

Application Selection Screen
Application Selection Screen
Example of Open Banking Authentication with Wells Fargo
Example of Open Banking Authentication with Wells Fargo
Example of non-open banking authentication with Discover.
Example of non-open banking authentication with Discover.

2. The User Selects Which Applications They Want to Authorize for IAV.

After successfully authenticating with a third-party application, the user is able to select which accounts they would like to verify specifically.

Aggregation Account Authorization
Aggregation Account Authorization
Verification Account Authorization
Verification Account Authorization

3. The user is prompted with any optional steps.

Prompt for Verification, in the Aggregation & Verification flow.
Prompt for Verification, in the Aggregation & Verification flow.

If a mixed flow (Aggregation & IAV, IAV & Aggregation) has been specified, the user will be offered the option of commencing the secondary flow.

⚠️
Remember that the user can opt out of engaging with the optional flow, and any data resulting from the second step should be considered as optional in application architectures.

‣

Resetting your Configuration

If you wish to change your Link Money Gateway type, simply reset the type parameter in your invocation to the Link Money Web Gateway - eg, 

https://external-accounts-webapp.herokuapp.com/api/authenticate?token={YOUR_TOKEN}&type={TYPE}

The type parameter can be assigned to one of three options:

  1. verify, to invoke a verification-only flow.
  2. aggregate-and-verify, to invoke an aggregate, then verify, flow.
  3. verify-and-aggregate, to invoke a verify, then aggregate, flow.