Endpoint Specific Requirements

Suggest Edits

Outlined below are the endpoint specific requirements and important need to know information for the following endpoints:

👍

Have you checked out the Check List?

/register specific requirements

Your application must include a notice about your customer identification program (CIP).

  • You can accomplish that by incorporating the following text into your application during the registration process of your user onboarding UI.

    The language you use does not need to match the below verbatim, but it should closely match nonetheless.

KYC-STANDARD flow must include the following language on why user meta data is being collected:

  • Introduction Screen:
    “For security purposes we need a few more details to prove that you're a real person”
  • Name/Address/DOB screen:
    “To help the government fight terrorism funding and money laundering, all financial institutions are required by federal law to obtain, verify, and record information about you, including your name, address, and date of birth. We may also ask to see your driver's license or other identifying documents.”
  • SSN Screen:
    “US Federal regulations require us to obtain your Social Security Number to confirm your identity. This will not impact your credit.”

Refers to Step 2 of the Demo Check List for demonstration requirements.

❗️

Private Keys & Sila's Info Management and Security Requirements

Private keys:

  • User private keys must never be generated client side.
  • User private keys must not be communicated over any network unencrypted
  • User private keys must be stored and retrieved with the use of a Key Management Store

More information about generating user private keys can be found here.

All applications must adhere to Sila's Information Management and Security Requirements for:

  • Encryption Standards
  • Database Hosting
  • Key Management Store (KMS)
  • Logging Data
  • Database Access
  • Data Disposal
  • Security Integration

/request_kyc for individuals specific requirements

Applications which make use of KYC-STANDARD must show the unhappy path where users fail their KYC evaluation and are subsequently asked to update information and/or send in verifying documents.

User’s are allowed to fail KYC and update their meta data once.

  • You can use the /update<registration-data> endpoint allow your end user a one-time opportunity to update their existing meta data.

If they fail again they must upload documents to verify their identity.

🚧

KYC Failures and updating user meta data

In an effort to prevent fraud your users should only be allowed to fail KYC and update their meta data once. If they fail again after updating their registration data they must upload documents to verify their identity.

The Unhappy Path:
Follow the links below for how to mock failing meta data for an end user and how to triage the resulting KYC failure with the required documents.

  • How to mock KYC failures in sandbox

  • How to Triage KYC failures

  • Users who fail KYC should be presented with the list of documents and document requirements which can be used to verify their identity (see: Triage KYC failures).

    In some cases this could be multiple lists (eg. they failed with multiple tags).
    In other cases one document can satisfy multiple failure scenarios (eg. A driver's license verifies Name and DOB).

    🚧

    How you handle this is up to you, but you must NEVER display the reason tags to your end user.

  • Document uploads are handled through the /documents endpoint and require kyc_level: KYC-STANDARD.

🚧

SANDBOX ONLY BUG: Unhappy Path - /check_kyc and /documents

Please note that at this time there is a known SANDBOX ONLY bug related to the /documents endpoints:

Bug: /documents (SANDBOX ONLY)
Uploading a document will not trigger a passed status for your mocked failed user.

For the Demo Review you will need to show two things:

  1. New user sign up - Unhappy Path: failed user info with a successfully uploaded a document.
  2. New user sign up -Happy Path: end user entering data with KYC-STANDARD and user getting a passing status /check_kyc

Refers to Step 3 of the Demo Check List for demonstration requirements.

/request_kyc for businesses (KYB) specific requirements

  • Everything for individuals applies to businesses except unlike with KYC, the "kyc_level" for a KYB request does not need to be specified explicitly in your API request. Instead, KYB levels are applied to the business entity based on the business type.

    Refer to KYC/KYB Levels for more information about the kyc_level parameter.

All KYB implementation must to be compliant with US laws.

  • End users must be asked to report if they are any of these three roles: admin, a controlling office, and/or a beneficial owner.

Refers to Step 6 of the Demo Check List for demonstration requirements.

/link_account specific requirements

Plaid Implementation
The /link_account endpoint requires that you use the Plaid implementation with the processor token method.

You will be required to have your own contract with Plaid that includes Plaid's Balance, Identity, and Auth products.

selected_account_id

  • The /link_account endpoint has a parameter "selected_account_id" which tells Sila which account the user selected in Plaid's Link Account modal. Without this parameter we will link the first checking account in the accounts array which we get back from Plaid.
  • To prevent errant bank account debits you are required to pass us the "selected_account_id" in your demo; this item comes from Plaid's onSuccess function and is synonymous with Plaid's "accountID". In other words, Sila's "selected_account_id" = Plaid's "accountID"

Note: the Plaid Processor Token method should include step to incorporate the selected_account_id.

account_name
It is important that you understand how the /link_account endpoint utilizes the account_name parameter.
/link_account.account_name is equal to /issue_sila.account_name and /redeem_sila.account_name

  • In other words, when there is more than one linked account you need to be able to specify the account name when you invoke /issue_sila and /redeem_sila.

  • The account_name key is not required, but can be used to set a "custom name" to identify the linked account.
    account_name: Custom Account Name

  • If you do not provide an account name, the first linked account will be assigned default and any subsequent accounts will be default<UUID>.

    Default is significant in that if you do not tell us which bank account to use we will the default account.

  • We highly recommend specifying a custom name.

Note: user handles cannot have two linked accounts with the same name.

Refers to Step 7 of the Demo Check List for demonstration requirements.

❗️

Legacy public token and Link token integration

Sila will support the Legacy public token and Link token integration for the near term, however, this functionality will no longer be supported as of May 2022.

  • Please seek a direct relationship with Plaid to use the Processor Token functionality.

Direct Accounts
Direct Account (manual) linking and Receive Only Entities have been prohibited due to a more restrictive regulatory environment.

  • As of July 2022 direct (manual) account linking was discontinued.
  • As of January 2023 the receive only kyc level was discontinued.

/issue_sila specific requirements

Sometimes ACH transactions can be returned to the end user by their bank.

Your customer support team must have a way to triage ACH returns.

Transaction Authorization Screen:
Your application must have a screen or modal where the end user confirms their choice to begin a transaction request.

  • Include the transaction amount and bank account information (last four digits of the account number and account_name) as well as any recurrence information.

ACH Processing

You are responsible for understanding how and when transactions are processed in order to inform users when to expect their funds.

Bank Account Balance

Your application is required to use the bank account balance to judge whether or not it is safe to perform a debit of the account. Obviously if they don't have enough money then you should prompt your user to choose a different amount or wait until they do have enough money.

  • Your application must check the end user’s bank balance before authorizing a transaction. This can be done with the /get_account_balance endpoint.

Warning: /get_account_balance is not available for accounts linked with Plaids same day micro deposit or for accounts linked with Sila's direct account linking method.

You will want to apply some cautious business logic to accounts linked in this manner to prevent these user from de-frauding you.
Example:

  • Allow 1 transaction only before allowing a second transaction.
  • Limit the 1st transaction to safe dollar amount maximum
  • Hold the minted tokens for 5-7 business to be sure the dollars don't get returned before allowing a second transaction.

IMPORTANT
/get_account_balance looks for the available_balance and current_balance however not all accounts can have their balances queried and some banks only return one or the other.

  • You will need to handle these errors however you see fit.

    Eg. if you can’t query the balance then the user should be subject to a lower transaction limit, or you should delay giving them access to their funds for 4 business days to ensure no returns occur.

Refers to Step 8 of the Demo Check List for demonstration requirements.

🚧

Minimizing needless ACH returns

Generally speaking a bank account should have 150% percent of the transaction amount available for you to comfortably authorize a debit.

  • Bank accounts with less than $100 generate far higher rates of ACH returns regardless of the transaction amount.

Think long and hard about how you will minimize your ACH return rate by employing common sense practices and by using all the tools available to you, such as /get_account_balance.

End users who regularly generate ACH returns should be removed from your platform permanently.

/redeem_sila specific requirements

Sometimes ACH transactions can be returned to the end user by their bank.

Your customer support team must have a way to triage ACH returns.

Transaction Authorization Screen:
Your application must have a screen or modal where the end user confirms their choice to begin a transaction request.

  • Include the transaction amount and bank account information (last four digits of the account number and account_name) as well as any recurrence information.

ACH Processing
Your application must inform users when to expect their funds.

Refers to Step 10 of the Demo Check List for demonstration requirements.

Disclosures and Agreement specific requirements

Review the specific requirements for required details related to Agreement & Disclosures.
Here: https://docs.silamoney.com/docs/agreement_and_disclosures_requirements

Refers to Step 1 and Step 11 of the Demo Check List

Updated about 2 months ago