API Documentation

Endpoint Specific Requirements

Suggest Edits

👍

Have you checked out the Checklist?

Please utilize both this page and the Demo Checklist page as you build your demo. The checklist is an overview of the full checklist - this page goes into detail on what specifically to demo for each endpoint included on the checklist.

There are items on the checklist not included on this page as they do not involve endpoints.

/register specific requirements

  1. Show where an end user enters their PII to register
  2. Show the end user entering PII and successfully registering
  3. Your application must include a notice about your customer identification program (CIP). Incorporate 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 at least closely match.

  • Introduction:
    “For security purposes we need a few more details to prove that you're a real person”
  • Name/Address/DOB:
    “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:
    “US Federal regulations require us to obtain your Social Security Number to confirm your identity. This will not impact your credit.”

KYC/KYB specific requirements

We recommend using Advanced KYC.

Advanced KYC Specific Endpoints

Classic KYC Specific Endpoints

Endpoints Applicable to both Classic and Advanced Flows

  • /update - updating end user PII provided during /register
  • /documents - uploading documentation for either KYC flow

Test triggers for requiring further verification for an entity, then passing KYC

KYB

Individual Entity KYC

Happy Path

  1. Request KYC with either /request_kyc (Classic) or /kyc (Advanced)
  2. Confirm the entity has passed KYC by calling either /check_kyc (Classic) or /get_verifications (Advanced)

Use either endpoint for Advanced KYC on this step:

/get_verifications for a list of all verification records for a specified user_handle
/get_verifications/<verification_uuid> for a single verification record

Advanced KYC Unhappy Path

  1. Request KYC on a registered entity with /kyc
  2. Confirm the entity needs further verification by calling one of the /get_verifications endpoints
  3. Show that the user first receives an opportunity to update their registration data with /update. They should still require additional verification after this step for your demo so you can show the document upload step
    • End users should be given the opportunity to update or confirm their registration PII before proceeding to uploading documentation with /documents
    • End users should only have one opportunity to update their registration PII at this stage. Updating some data is possible after KYC has been passed
  4. Resume the verification by calling /resume_verification
  5. Demonstrate the end user uploading documentation with /documents
    • Do NOT display the field that needs the additional verification, as this tells bad actors exactly what they got right and wrong. Instead, only display the document types they can choose between to upload.
    • For the same reason, do NOT display the reason tags
  6. Resume verification with /resume_verification
  7. Show that user's verification status changing to Passed

Classic KYC Unhappy Path

  1. Request KYC on a registered entity with /request_kyc
  2. Confirm the entity needs further verification by calling /check_kyc
  3. Show that the user first receives an opportunity to update their registration data with /update. They should still require additional verification after this step for your demo so you can show the document upload step
    • End users should be given the opportunity to update or confirm their registration PII before proceeding to uploading documentation with /documents
    • End users should only have one opportunity to update their registration PII at this stage. Updating some data is possible after KYC has been passed
  4. Demonstrate the end user uploading documentation with /documents and that user's verification status changing to Passed
    • Do NOT display the field that needs the additional verification, as this tells bad actors exactly what they got right and wrong. Instead, only display the document types they can choose between to upload.
    • For this same reason, do NOT display reason tags

Business Entity KYB

Skip if you are not utilizing business entities

Happy Path

  1. Link all business members to the business with /link_business_member
    • You will need to have registered the business and individual entities to become business members, but you do not need to demo the registration.
    • You only need to demo linking business members once, do so either here or during the unhhappy path demo.
  2. Request KYB on the business entity with either /request_kyc (Classic) or /kyc (Advanced) - this will automatically KYC the business members as well
  3. Confirm the business has passed KYB by calling either /check_kyc (Classic) or /get_verifications (Advanced)
    • If applicable, certify beneficial owners and business to fully pass KYB.

Advanced KYC Unhappy Path

  1. You only need to demo linking business members once - do so either here or during the happy path demo
  2. Request KYB on the business entity with /kyc - this will automatically KYC the business members as well
  3. Confirm the business entity needs further verification by calling one of the /get_verifications endpoints
  4. Show that the user receives an opportunity to update their registration data with /update. Fix the test trigger registration data so it will pass
  5. Call /resume_verification
  6. Show that user's verification status has changed to Passed

Classic KYC Unhappy Path

  1. You only need to demo linking business members once - do so either here or during the happy path demo
  2. Request KYB on the business entity with /request_kyc - this will automatically KYC the business members as well
  3. Confirm the business entity needs further verification by calling /check_kyc
  4. Show that the user first receives an opportunity to update the business registration data with /update. They should still require additional verification after this step for your demo so you can show the document upload step
    • End users should be given the opportunity to update or confirm their registration PII before proceeding to uploading documentation with /documents
    • End users should only have one opportunity to update their registration PII at this stage. Updating some data is possible after KYC/KYB has been passed
  5. Demonstrate the end user uploading documentation for the business with /documents and the business's verification status changing to Passed
    • Do NOT display the field that needs the additional verification, as this tells bad actors exactly what they got right and wrong. Instead, only display the document types they can choose between to upload.
    • For this same reason, do NOT display reason tags

/link_account specific requirements

  1. Demonstrate a bank account being successfully linked with either Plaid or MX using /link_account
    • You will need a contract with either Plaid or MX. See the integration pages for specifics on what products should be included in that contract to utilize the integration.
    • /link_account requires a provider_token to be passed in. This is either the processor_token from Plaid or the authorization_code from MX. Use the integration pages on how to obtain these items.

❗️

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.

/issue_sila specific requirements

🚧

Transactions - use /transact

/issue, /redeem, and /transfer will, in the long-term, be deprecated in favor of our /transact endpoint. We have no current date set for that deprecation, and we will continue supporting existing use of these endpoints until all customers can implement /transact.

Please implement /transact for all transaction types.

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 8 days ago