Links a checking or savings bank account to a verified Sila entity, with a Plaid processor token.

Link a checking or savings account using Plaid

The /link_account endpoint accepts a token and account ID from a customer's interaction with a Plaid Link modal utilizing the Processor Token method.

Plaid Processor Token

Step 1: You will need to utilize the Plaid Integration with Sila to obtain a processor token. Please follow the step outlined in the Plaid documentation: https://plaid.com/docs/auth/partnerships/sila-money/.


Plaid Contract:

Sila requires the use of Plaid's Balance, Identity, and Auth products, please ensure these products are included in your Plaid contract.

Additionally, you may choose to take advantage of other Plaid products but they are not required by Sila.

Link Account

Step 2: Once you obtain a processor token you will link your customer's account with Sila by calling /link_account.

  • Pass the processor_token in the plaid_token parameter
  • Set the plaid_token_type parameter "processor".

Plaid Code Samples

  • Request and Response samples can be found below.
  • You can also check out the Plaid Processor Token Recipe and <insert_MX account> which will walk you through the entire flow.
    NOTE: You can use the endpoint /get_account_balance and pass account_name to verify bank account link.

Testing Bank Account Linking

In only the sandbox, you can test bank account linking with any bank that shows up in the Plaid Link interface. Specify the username as "user_good" and the password as "pass_good".

In only the sandbox, you can test the scenario when the entity name does not match the account holder name. Set a value of no match (case insensitive) in the ”account_name” field.

In only the sandbox, you can test bank account direct linking to set the web_debit_verified = false. The default will be true unless you set the numbers “420” anywhere in the account_name field to make the value false.

Account Linking Expiration

Once an account is linked, our /issue_sila and /redeem_sila endpoints will continue to work unless manually removed using /delete_account.

However, there are two cases in which a customer will need to re-enter their login credentials with Plaid if their login session expires.

  1. /get_account_balance will return an error with the message from Plaid, 'Login credentials to this financial institution are invalid. Retry linking this account.'
  2. Instant ACH is not available, as it requires our system verifying that the customer has sufficient funds with an account balance check.

Each individual banking institution controls how long a login session lasts, so there is no way to predict how long this will be. 30 days is a safe bet, though it may be either shorter or longer.


POST /0.2/link_account HTTP/1.1
Host: sandbox.silamoney.com
Content-Type: application/json

  "header": {
    "created": 1234567890, 
    "app_handle": "handle.silamoney.eth", 
    "version": "0.2", 
    "crypto": "ETH", 
    "reference": "<your unique id>"
  "plaid_token": "processor-xxx-xxx",
  "account_name": "Custom Account Name",
  "selected_account_id": "selected_account_id",
  "plaid_token_type": "processor"


HTTP/1.1  200 OK

  "success": true,
  "status": "SUCCESS",
  "reference": "ref",
  "response_time_ms": "1171",
  "message": "Bank account successfully linked.",
  "account_name": "Custom Account Name",
  "match_score": 0.825,
  "account_owner_name": "Sally Smith",
  "entity_name": "Sally Smith",

// Plaid verification flow (recommended)
const res = await Sila.linkAccount(
  accountName, // Account Name is not required
  accountId, // Account Id parameters is required,
  plaidTokenType, // Required.'processor,'

//Public token received in the /link/item/create plaid endpoint.

// Direct account-linking flow (restricted by use-case, contact Sila for approval)
const res = await Sila.linkAccountDirect(
); // Account Type and Account Name parameters are not required

//The only permitted account type is "CHECKING"

// Success Response Object
console.log(res.statusCode); // 200
console.log(res.data.reference); // Random reference number
console.log(res.data.status); // SUCCESS
console.log(res.data.message); // Bank account successfully linked
console.log(res.data.web_debit_verified); // true/false
### Link Account with Plaid
payload = {
    "public_token": "public-development-0dc5f214-56a2-4b69-8968-f27202477d3f",  # Required token from plaid
    "user_handle": "user.silamoney.eth",                                         # Required
    "account_name": "Custom Account Name",                                       # Optional (default value is "default")
    "selected_account_id": "account id",                                        # Optional
    "plaid_token_type": "plaid token type"                                      # Optional}                                         

User.linkAccount(silaApp, payload, user_private_key, plaid=True)

### Link Account with Direct Account Linking
            "user_handle": "user.silamoney.eth",    # Required
            "account_number": "123456789012",       # Required
            "routing_number": "123456780",          # Required
            "account_type": "CHECKING",             # Optional (default value is CHECKING)
            "account_name": "Custom Account Name"   # Optional (default value is "default"),


### Success Response Object
    status: 'SUCCESS',
    success: True,
    message: 'Bank account successfully manually linked.',
    reference: 'f9f23fc2-26e7-4358-99c8-75cb8aec76fb',
    account_name: 'default',
    status_code: 200,
    match_score: 0.825,
    account_owner_name: 'Sally Smith',
    entity_name: 'Sally Smith'


### Failure Response Object
    status: 'FAILURE'
String userHandle = 'user.silamoney.eth';
String accountName = 'plaid'; // Your desired account name
String publicToken = 'public-sandbox-xxx' // Your Plaid token
String userPrivateKey = 'some private key';
String accountId = 'plaid account id'; // Required
String plaidTokenType = "Processor";

ApiResponse response = api.linkAccountPlaidToken(userHandle, userPrivateKey, accountName, publicToken, accountId, plaidTokenType);

// For Direct Account Link
String userHandle = 'user.silamoney.eth';
String accountName = 'direct'; // Your desired account name
String accountNumber = '123456789012';
String routingNumber = '123456780';
String accountType = 'CHECKING'; // Currently the only allowed value
String userPrivateKey = 'some private key';

ApiResponse response = api.linkAccount(userHandle, userPrivateKey, accountName, accountNumber, routingNumber, accountType);

// Success Response
System.out.println(response.getStatusCode()); // 200
LinkAccountResponse parsedResponse = (LinkAccountResponse) response.getData();
System.out.println(parsedResponse.getStatus()); // SUCCESS
System.out.println(parsedResponse.getSuccess()); // true
System.out.println(parsedResponse.getReference()); // Reference number
System.out.println(parsedResponse.getMessage()); // Successfully linked
System.out.println(parsedResponse.getAccountName()); // Your desired account name
System.out.println(parsedResponse.getMatchScore()); // Match score
System.out.println(parsedResponse.getWebDebitVerified()); // true/false
use Silamoney\Client\Domain\PlaidTokenType;

// **IMPORTANT!** If you do not specify an `$account_id` in `linkAccount()`, the first account returned by Plaid will be linked by default.

// Plaid token flow
// Load your information
$userHandle = 'user.silamoney.eth';
$accountName = 'Custom Account Name'; // Defaults to 'default'
$plaidToken = 'public-xxx-xxx'; // A temporary token returned from the Plaid Link plugin. See above for testing.
$accountId = 'string'; // Recommended but not required. See note above.
$userPrivateKey = 'some private key'; // The private key used to register the specified user
$plaidTokenType = PlaidTokenType::Processor(); // Optional.  PROCESSOR

// Call the api
$response = $client->linkAccount($userHandle, $userPrivateKey, $plaidToken, $accountName, $accountId, $plaidTokenType);

// Direct Link account
// Load your information
$userHandle = 'user.silamoney.eth';
$accountName = 'Custom Account Name'; // Defaults to 'default' if not provided. (not required)
$routingNumber = '123456789'; // The routing number. 
$accountNumber = '123456789012'; // The bank account number
$userPrivateKey = 'some private key'; // The private key used to register the specified user
$accountType = 'CHECKING'; // The account type (not required). Only available value is CHECKING

// Call the api
$response = $client->linkAccountDirect($userHandle, $userPrivateKey, $accountNumber, $routingNumber, $accountName, $accountType);

// Success 200
echo $response->getStatusCode(); // 200
echo $response->getData()->getStatus(); // SUCCESS
echo $response->getData()->getReference();
echo $response->getData()->getMessage();
echo tAccountName();
echo $response->getData()->ge$response->getData()->getAccountOwnerName();
echo $response->getData()->getEntityName();
echo $response->getData()->getMatchScore();
echo $response->getData()->getWebDebitVerified()
ApiResponse<object> response = api.LinkAccount(userHandle, publicToken, walletPrivateKey, accountName, accountId, plaidTokenType);
// Account Name is not required 
// Account Id is required
// plaidTokenType is not required

ApiResponse<object> response = api.LinkAccountDirect(userHandle, walletPrivateKey, accountNumber, routingNumber, accountType, accountName); // Account Type and Account Name parameters are not required 

// Success Response Object

Console.WriteLine(response.StatusCode); // 200
parsedResponse = (LinkAccountResponse)response.Data;
Console.WriteLine(parsedResponse.Success); // true
Console.WriteLine(parsedResponse.Status); // SUCCESS
Console.WriteLine(parsedResponse.Reference); // Random reference number
Console.WriteLine(parsedResponse.ResponseTimeMs); // 2345
Console.WriteLine(parsedResponse.Message); // Bank account successfully linked.
Console.WriteLine(parsedResponse.AccountName); // Custom Account Name.
Console.WriteLine(parsedResponse.MatchScore); // 0.825           
Console.WriteLine(parsedResponse.AccountOwnerName); //Sally Smith
Console.WriteLine(parsedResponse.EntityName); //Sally Smith
Console.WriteLine(parsedResponse.WebDebitVerified); //true





JSON object

Required. Requires these keys in JSON format: created, app_handle, user_handle. See the /check_handle endpoint for the complete list of fields in this object.



Required if not setting account_number, routing_number .

If using Sila's Plaid account: Enter a valid public token from the Plaid Link modal consisting of letters, numbers, underscores, or hyphens.

If using your own Plaid account: pass a processor token obtained from Plaid. Example: processor-xxx-xxx.

This value should be match the required regex pattern: ^[-a-zA-Z0-9_]+$



Optional. Min length 1, Max length 40, default value if not sent in request is “default” Example: Custom Account Name
NOTE- We highly recommend specifying a custom name here as this is how an account is identified for /issue_sila, /redeem_sila, and /get_transactions.



Required unless using your own Plaid account and linking with a processor token. This is the Plaid account ID from list of selected account IDs returned from Plaid Link flow.

Max Length 100



Optional. Must match either "CHECKING" or "SAVINGS".



Optional. Must match "processor".


The request body for this endpoint is the link_account_msg JSON object.

Both authsignature and usersignature headers are required for this request.

The account_name key is not required, but can be used to set a custom name to identify the linked checking account. If not provided, the linked account's name will be "default". We highly recommend specifying a custom name. Note: user handles cannot have two linked accounts with the same name.

Fuzzy Name Match Algorithm


Fuzzy Name Match and the /link_account response body

Within the response body of /link_account you may see the error message: "Bank account linked, but in a frozen state. Requires manual review - contact support to unfreeze this bank account."

Make a call /get_accounts where you'll see the following meta for the linked account: "match_score": 0.825, "account_owner_name": "Test User", and "entity_name": "Test User". The account owner name is the name on the account provided by Plaid, while the entity name is the name of the person or business as provided to Sila through your request to /register. These two names need to closely match otherwise the account will not be useable.

If the match score is less than 0.73 the account will be frozen and not useable, and the users must use the /documents endpoint to provide proof they own the account or proof that they changed their name. They can also choose to link a different account.

How to unblock an End User with a frozen account due to a name mis-match

  • Call /get_accounts
  • Confirm that the account match score is less than 0.73
  • Confirm that the "account_owner_name" and the "entity_name" do not match
  • Have the End User upload proof they own the account or proof that they changed their name to the /documents endpoint.

    See the Name Verification docs for acceptable documents

  • Once the End User has uploaded acceptable documents reach out to Support via your Slack channel. You must provide the following information:
    • user_handle
    • the /link_account error message: "Bank account linked, but in a frozen state. Requires manual review - contact support to unfreeze this bank account."
    • the response from /get_accounts showing a match score of less than 0.73, "account_owner_name" and the "entity_name".
  • Support will then verify the documents.
  • If account ownership is verifiable with the provided documents Support will file a ticket to have the account unfrozen and notify you via your Slack channel.
  • If account ownership is NOT verifiable with the provided documents Support will not be able to unfreeze the account. You will be notified via your Slack channel and the End User will need to choose to link a different account.


Status Code

success Attribute




Bank account successfully linked.



Bank account not successfully linked (public token may have expired; tokens expire in 30 minutes after creation).



Bank account linked, but in a frozen state. Requires manual review - email [email protected] for steps to unfreeze this bank account.



Check validation_details for more information. PRODUCT_NOT_READY indicates the account is waiting to be linked (with microdeposit verification, for instance).



authsignature or usersignature header was absent or incorrect.


Legacy Plaid Integration - Link Token & Plaid Public Key


DEPRECATED: Legacy Plaid Integration - Link Token & Plaid Public Key

If you integrated Plaid through the Sila API before July 2021, you may have a legacy integration.

Per Plaid's request, the Plaid Link token integration will be deprecated May 2022.

Please establish a direct relationship with Plaid, https://plaid.com/docs/auth/partnerships/sila-money/ and begin integration with the Plaid processor token as soon as possible.

Selected Account ID

The selected_account_id is not required; if provided, it should be an account ID in the array of selected accounts returned in the metadata object from Plaid Link. This ID can identify either a checking account or a savings account to link. Currently, we do not link multiple accounts at once; you will need to send only one account ID. If no account ID is provided, we will link the first checking account we encounter from the array of accounts the customer has at their chosen bank.

Did this page help you?