Endpoint Specific Requirements
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
- /request_kyc for individuals
- /request_kyc for businesses (KYB)
- /link_account
- /issue_sila
- /redeem_sila
- agreement & disclosures
/register specific requirements
- /register endpoint documentation page
- Show where an end user enters their PII to register
- Show the end user entering PII and successfully registering
- 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.
- Overview of the different KYC Flow options
- Advanced KYC implementation guide
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
- Request KYC with either /request_kyc (Classic) or /kyc (Advanced)
- 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
- Request KYC on a registered entity with /kyc
- Confirm the entity needs further verification by calling one of the /get_verifications endpoints
- 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
- Resume the verification by calling /resume_verification
- 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
- Resume verification with /resume_verification
- Show that user's verification status changing to Passed
Classic KYC Unhappy Path
- Request KYC on a registered entity with /request_kyc
- Confirm the entity needs further verification by calling /check_kyc
- 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
- 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
- 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.
- Request KYB on the business entity with either /request_kyc (Classic) or /kyc (Advanced) - this will automatically KYC the business members as well
- 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
- You only need to demo linking business members once - do so either here or during the happy path demo
- Request KYB on the business entity with /kyc - this will automatically KYC the business members as well
- Confirm the business entity needs further verification by calling one of the /get_verifications endpoints
- Show that the user receives an opportunity to update their registration data with /update. Fix the test trigger registration data so it will pass
- Call /resume_verification
- Show that user's verification status has changed to Passed
Classic KYC Unhappy Path
- You only need to demo linking business members once - do so either here or during the happy path demo
- Request KYB on the business entity with /request_kyc - this will automatically KYC the business members as well
- Confirm the business entity needs further verification by calling /check_kyc
- 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
- 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
- /link_account endpoint documentation
- Plaid Integration
- MX Integration
- 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 theprocessor_token
from Plaid or theauthorization_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.
- ACH Returns Codes and Descriptions:
- How to retrieve ACH Return Codes
ACH return codes in R02, R03, R04, R20, R13, R14, R15 require that you first permanently delete the linked account, then notify the the end user, and consider removing them from your platform.
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.
- You can accomplish this by using our ACH Processing Calendar and reviewing the Staus Diagrams for /issue_sila, /transfer_sila and /redeem_sila.
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.
- ACH Returns Codes and Descriptions:
- How to retrieve ACH Return Codes
ACH return codes in R02, R03, R04, R20, R13, R14, R15 require that you first permanently delete the linked account, then notify the the end user, and consider removing them from your platform.
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.
- You can accomplish this by using our ACH Processing Calendar
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