Bank linking

Link a customer's own bank account through Plaid Link, and handle every outcome.

A customer links one bank account in their own name. It is used to add funds, to pay by bank and to withdraw. A2A InstaPay checks that the account holder matches the customer and that the bank can be reached over RTP.

The flow#

Your server requests a link token for the customer.
Your app opens Plaid Link with the link token. The customer chooses their bank, signs in and picks an account.
Plaid Link returns a public token to your app, which sends it to your server.
Your server submits the public token. The linked account is pending while checks run.
linked_account.verified or linked_account.failed follows.

Shell

curl -X POST https://sandbox.a2ainstapay.com/v1/customers/cus_.../link-tokens \
  -H "Authorization: Bearer $A2A_ACCESS_TOKEN" -H "Idempotency-Key: $(uuidgen)" -H "Content-Type: application/json" \
  -d '{"platform":"web","redirect_uri":"https://app.example.com/bank-return"}'

`platform`	Notes
`web`	`redirect_uri` is required: the page Plaid returns to after a bank's own sign-in. Register it in the portal settings
`ios`, `android`	For native apps

Shell

curl -X POST https://sandbox.a2ainstapay.com/v1/customers/cus_.../linked-accounts \
  -H "Authorization: Bearer $A2A_ACCESS_TOKEN" -H "Idempotency-Key: $(uuidgen)" -H "Content-Type: application/json" \
  -d '{"public_token":"public-sandbox-...","plaid_account_id":"acc-..."}'

In the sandbox#

Load the bank-linking simulator in place of Plaid's script. It has the same Plaid.create interface, so your code does not change:

HTML

<script src="https://sandbox.a2ainstapay.com/plaid-sim/link-initialize.js"></script>
<!-- production: https://cdn.plaid.com/link/v2/stable/link-initialize.js -->

Some banks send the customer to their own site to sign in. Plaid then returns the customer to your redirect_uri.

Before opening Plaid Link, save the link token, for example in localStorage.
On the return page, open Plaid Link again with the saved token and receivedRedirectUri: window.location.href.
The customer finishes choosing the account, and onSuccess gives you the public token as usual.

If the return page opens without the saved token, for example in a different browser, ask the customer to start bank linking again. In the sandbox, Summit National Bank uses its own sign-in.

Outcomes and capabilities#

Status	Meaning
`pending`	Checks are running
`verified`	Ready to use; `capabilities` says what for
`held_for_review`	The account holder name does not match; the compliance team reviews it
`failed`	`failure_code` explains: for example `not_rtp_reachable`, `already_linked` or `unsupported_account_type`
`removed`	Removed by your request; a new account can then be linked

capabilities has three flags: load, pay_by_bank and withdrawal. A bank that cannot receive Requests for Payment can still receive withdrawals. After a customer replaces a linked account, withdrawals to the new account are held for a period set by your program (24 hours in the sandbox), shown in withdrawal_hold_until.

Questions about this page? Contact developer support.

Bank linking

The flow#

In the sandbox#

Banks that use their own sign-in (web apps)#

Outcomes and capabilities#