# Bank linking

A bank linking flow is necessary due to [NACHA](https://www.nacha.org/) operating rules (an agreed upon set of rules for ACH transfers) which prohibits one entity to sharing bank linking with another. This blocks a Partner from sharing information about any bank accounts that an employer has previously linked and authenticated with that Partner with Basic Capital. Resulting in the employer having to separately link their bank account to Basic Capital.

## Requirements

- Embed a plaid bank linking flow that allows the employer to link their bank account directly to Basic Capital’s plaid account via Plaid’s [Link React Native SDK](https://plaid.com/docs/link/react-native/).
- Provide Basic Capital with a redirect URL we provide to plaid in our backend. This is the URL you will want to redirect to after the plaid linking flow is complete in the client.
- Include a potential verify bank account flow if additional verification such as micro deposits is required to link the employer’s bank account.


## Integration Diagram

### Callouts

- If linking fails you will get a failure from the Plaid link SDK.
- If verification fails, Plaid link SDK will succeed, but the Basic Capital API call to `CompleteBankLink` will return a `BankAccount` with `is_verified` set to `false` which means a second bank link flow will be required.


```mermaid
sequenceDiagram
    participant Partner
    participant BC as Basic Capital
    participant Plaid

    Note over Partner, Plaid: Step 1: Begin Bank Link
    Partner->>BC: BeginBankLink
    BC->>Plaid: Create Link Token
    Plaid-->>BC: Link Token
    BC-->>Partner: Link Token Response

    Note over Partner, Plaid: Step 2: Plaid Client Flow
    Partner->>Plaid: Open Plaid Link (with Link Token)
    Plaid-->>Partner: Redirect with Public Token + Account Metadata

    alt Plaid Link fails
        Note over Partner: Error from Plaid, flow ends
    else Plaid Link succeeds
        Note over Partner, Plaid: Step 3: Complete Bank Link
        Partner->>BC: CompleteBankLink (Public Token + Account Info)
        BC-->>Partner: CompleteBankLinkResponse (is_verified)

        alt is_verified = true
            Note over Partner: Bank account linked and verified, done!
        else is_verified = false
            Note over Partner, Plaid: Step 4: Micro-deposit Verification
            Partner->>BC: ListBankAccounts
            BC-->>Partner: Bank Account ID

            Partner->>BC: VerifyBankLink (Bank Account ID)
            BC->>Plaid: Create Link Token (for verification)
            Plaid-->>BC: Link Token
            BC-->>Partner: Link Token Response

            Partner->>Plaid: Open Plaid Link (verification flow)
            Plaid-->>Partner: Redirect with Public Token + Account Metadata

            Partner->>BC: CompleteBankLink (Public Token + Account Info)
            BC-->>Partner: CompleteBankLinkResponse (is_verified = true)
            Note over Partner: Bank account verified, done!
        end
    end
```