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.

Authentication

Newly onboarding customers are required to use our OAuth2 JWT authentication method. Please disregard references to the ECDSA method.

OAuth2 documentation can be found here.

End User Onboarding

/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

🚧

Advanced KYC

Newly onboarding customers are required to use the Advanced KYC system.

Endpoints

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

KYB

Individual Entity KYC

Happy Path

  1. Request KYC with /kyc
  2. Confirm the entity has passed KYC by calling /get_verifications

Use either endpoint on this step:

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

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

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 /kyc - this will automatically KYC the business members as well
  3. Confirm the business has passed KYB by calling one of the /get_verifications endpoints
    • If applicable, certify beneficial owners and business to fully pass KYB.

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

/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.

Transacting

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. If there are not enough funds, then you should prompt your user to choose a different amount or wait until they do have enough.

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

/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.

Returns

Sometimes ACH transactions can be returned to the end user by their bank. You must have a way to triage ACH returns. End users who regularly generate ACH returns should be removed from your platform permanently.

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.

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.

ACH Pull (bank account > Sila wallet) specific requirements

🚧

Recommendation: 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.

Use /issue_sila for this step if you are not implementing /transact.

  1. Show how an end user initiates this transaction which includes:
  • specified bank account
  • specified user wallet
  • transaction amount
  • any applicable service fees
  1. Show where the end user sees a “Transaction Authorization Screen” where the end user confirms their choice to begin the transaction request. Includes:
  • transaction amount
  • bank account information (last four digits of the account number and account name)
  • any recurrence information
  • end user should also have the option to cancel or make changes
  1. Show where the end user sees a confirmation screen showing the transaction request has been accepted and is being processed.

Internal Transfer Transaction (Sila wallet > Sila wallet)

If this step is not applicable to your use case skip this step.

🚧

Recommendation: 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.

Use /transfer_sila for this step if you are not implementing /transact.

Show how an end user initiates a transfer from their Sila wallet to a specified destination wallet:

  1. Show how an end user initiates this transaction which includes:
    • specified user wallet (source and destination)
    • transaction amount
    • any applicable service fees
  2. Show where the end user sees a “Transaction Authorization Screen” which includes:
    • transaction amount
    • specified source
    • specified destination
    • any recurrence information
    • end user should also have the option to cancel or make changes
  3. Show where the end user sees a confirmation screen showing the transaction request has been accepted and is being processed.

ACH Push (Sila wallet > bank account)

🚧

Recommendation: 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.

Use /redeem_sila for this step if you are not implementing /transact.

/transact documentation

/redeem_sila documentation

  1. Show how an end user initiates this transaction which includes:
  • specified bank account
  • specified user wallet
  • transaction amount
  1. Indicate where the end user sees a “Transaction Authorization Screen” where they can confirm and submit the transaction, make changes, or cancel. Includes:
  • transaction amount
  • bank account information (last four digits of the account number)
  • any recurrence information
  • any applicable service fees
  1. Show where the end user sees a confirmation screen showing the transaction request has been accepted and is being processed.

Updated about 2 months ago