Priority Integration
An implementation guide for Priority customers.
A NOTE ON THIS PAGE
This doc was originally written for existing Sila customers that migrated to Priority with functionality already built out that just needed to be updated.
The rest of our documentation, along with this page, is being updated as quickly as possible.
You will see a green callout banner on both this page and throughout the rest of the docs confirming if that page has been updated with Priority requirements and information yet.
Payment Instrument Terminology Note
- remote ledger account: a ledger account opened up at Priority, managed by Priority, for each end user onboarded. Represented in the Sila ecosystem by the Sila wallet.
- external bank account / external account: the end user's personal bank account at their own banking institution.
- wallet: the object within the Sila ecosystem that represents the ledger account existing at Priority
Endpoints:
- /kyc - creates a wallet and opens a remote ledger account
- /delete_wallet - deletes a wallet and closes a remote ledger account
- /register_wallet - creates a new wallet and opens an additional remote ledger account. Can't be called until KYC is passed.
- /get_wallet and /get_wallets - response includes remote ledger account and routing numbers
Priority Go-Live Process
Once you are ready from both a technical and compliance perspective, you are ready to start the go-live process, outlined below.
Go-Live Timeline
- We require at least a 48 business hour notice prior to getting on a call for Step 1 - we have preliminary work to do to prep for a successful call.
- It can take up to a week to go fully live after that initial call, largely due to the need to pass the first entity through KYC. For example, if documents need to be uploaded to pass KYC this can extend time to full go-live.
1. Schedule a kickoff call with us
Please make sure at least one person that will hold the App Owner role will be on the call. This is critical for granting Production access you will need to complete to go fully live with both KYC/KYB and transacting.
- Give us a 48 business hour notice in order to do preliminary prep and setup.
- On the call:
- We will review a Go-Live Playbook we'll create and share with you.
- You will receive Production console access.
- You will be invited to your Production app.
- Your Production app will be enabled for Priority KYC and KYB.
- This is critical for the rest of the process, but also means you can start onboarding end users at this point. You can begin registering and passing new users through KYC and KYB, but will not be able to transact until you are fully live.
2. Register and KYC your company entity
The next step is to create a business entity representing your company and pass through KYC.
- Create the entity and all necessary beneficial owners with your company information, and pass through KYB.
- NOTE: If you are only using Sila for KYC and individual entities, we can create a business entity for you.
3. Fund the Priority Reserve
- We will create your Priority Reserve and link it to the business entity from the above step.
- We'll then send you account details for funding.
4. Go live!
- Once your Reserve has been funded, we will turn on transacting and any other necessary features.
- Please continue to reach out to us in your Slack channel! We are here to continue to support you.
Basic Flow
Individual entity
HAPPY PATH
- Create entity with /register
- /kyc kicks off KYC process and opens remote ledger account
- Pass KYC
- Link external bank accounts
- Transact
UNHAPPY PATH
- Create entity with /register
- /kyc kicks off KYC process and opens remote ledger account
- Does not pass KYC - use /get_verifications/<verification_uuid> to determine doc to upload
- Upload doc with /documents
- Entity passes or fails KYC. If entity passes, continue to 6 and 7.
- Link external bank accounts
- Transact
Business entity
HAPPY PATH
- Create business entity and all individual entities to be added as business members
- Link all business members to business entity
- Do NOT call /kyc on the individual members
- Members must be linked prior to calling /kyc on the business entity
- /kyc on the business entity kicks off KYC process and opens remote ledger accounts for business and all members.
- Pass KYC
- Certify any linked beneficial owners and the business
- Link external bank accounts
- Transact
UNHAPPY PATH
- Create business entity and all individual entities to be added as business members
- Link all business members to business entity
- Do NOT call /kyc on the individual members
- Members must be linked prior to calling /kyc on the business entity
- /kyc on the business entity kicks off KYC process and opens remote ledger accounts for business and all members, except members that hold only the administrator role.
- Member or business does not pass KYC - use /get_verifications/<verification_uuid> to determine doc to upload
- Entity/entities pass or fail KYC. If entity/entities pass, continue to 6, 7, and 8.
- Certify any linked beneficial owners and the business
- Link external bank accounts
- Transact
New Receipt Language Requirement
Priority Bank requires the below receipt language be made visible to end users when they submit transactions. If you currently display a confirmation modal or screen after a user submits a transaction, please add the below to it. If not, please begin doing so with the below information included.
Please note the "managed by {client}" in the first sentence - you are free to add your own company name here for {client}.
Transaction ID: {unique ID}
Dear {client_name},
Finxera, Inc. is the payment processor for your {transaction description - e.g., "bill payments," "transactions," "remittance transactions," etc.} managed by {client}. We have made the below payment from your account, in accordance with your instructions.
Payment to: {recipient}
Total to Recipient: {principal payment} USD
Transaction Fee: {fee amount} USD
Total Transfer: {total amount} USD
Date: {date}
CONTACT US
You can reach out to us at [email protected] or call customer support at (800) 475-0811.RIGHT TO REFUND
You, the customer, are entitled to a refund of the money to be transmitted as a result of this agreement if Finxera does not forward the money received from you within 10 days of the date of its receipt, or does not give instructions committing an equivalent amount of money to the person designated by you within 10 days of the receipt of the funds from you unless otherwise instructed by you.If your instructions as to when the moneys shall be forwarded or transmitted are not complied with and the money has not yet been forwarded or transmitted, you have a right to a refund of your money.
If you want a refund, you must mail or deliver your written request to Finxera at 2975 Regent Blvd, Suite 100, Lockbox Services 208677, Irving, TX 75063. If you do not receive your refund, you may be entitled to your money back, plus a penalty of up to $1,000 and attorney’s, fees pursuant to Section 2102 of the California Financial Code. *
* This paragraph only applies to California residents.
For Texas Residents:
If you have a complaint, first contact Finxera at (800) 475-0811. If you still have an unresolved complaint regarding the company’s money transmission activity, please direct your complaint to: Texas Department of Banking, 2601 North Lamar Boulevard, Austin, Texas 78705, 1-877-276-5554 (toll free), www.dob.texas.gov.For New York Residents:
If you have a complaint, first contact Finxera at (800) 475-0811. If you still have an unresolved complaint regarding the company’s money transmission activity, please direct your complaint to: New York State Department of Financial Services, Consumer Assistance Unit, One Commerce Plaza, Albany York, NY 12257, 1-800-342-3736, www.dfs.ny.gov.You have a right to dispute errors in your transaction. If you think there is an error, contact us within 180 days at (800) 475-0811 or at 2975 Regent Blvd, Suite 100, Lockbox Services 208677, Irving, TX 75063. You can also contact us for a written explanation of your rights.
Finxera, Inc. is a licensed provider of money transfer services (NMLS # 1168701) and is located at 2001 Westside Parkway, Suite 155, Alpharetta, GA 30004.
See www.finxera.com/licensing for additional disclosures.
Endpoint Flow
Existing /register doc linked above has been updated for Priority specifications.
- Does not open remote ledger account / create wallet object in Sila ecosystem. See /kyc.
- All data required to run KYC is now required for a successful /register call. Please refer to the Request Attributes table on the /register doc. Description column includes "Required to pass KYC" note.
- Required for individuals:
- Full legal name
- U.S. Social Security Number (Full 9-digit SSN; ITIN not currently accepted)
- Date of birth
- A valid street address (PO Boxes not accepted)
- An email address with a valid domain
- Phone number
- Required for businesses:
- Legal business name
- Doing Business As (can be legal name if there is not DBA)
- Business website
- Business EIN
- Date of incorporation
- Business address
- Business email address with a valid domain
- Business phone number
- Registration state (2 letter US state abbreviation)
- Required for individuals:
Use Unique SSNs and EINs
In Sandbox, you will see errors and unexpected behavior if you register multiple users with the same SSN or EIN.
In Production, end users can register once per app - so end users can be registered with multiple customers, but not more than once per customer.
KYB Registration
Docs updated with Priority specs
- This overview page of the KYB system, and differences with KYC
- /link_business_member
- /unlink_business_member
Supported Business Types
Please note Priority does not support linking the business types
trust
orunincorproated_association
.You will receive an error trying to link a business of this type.
All other business types returned by /get_business_type are valid.
Existing doc linked above has been updated for Priority specifications.
- If
id_document
was not provided during /register use /add/id_document to add it to an individual entity needing to be linked as a BO or CO to a business.
Existing doc linked above has been updated for Priority specifications.
Use this endpoint to update existing registration information.
Existing doc linked above has been updated for Priority specifications.
Use this endpoint to link individuals to businesses and assign them a role.
Docs updated with Priority specs
- This overview doc of the Advanced KYC system.
- /kyc
- /get_verifications
- /get_verifications/<verification_uuid>
- Creates the remote ledger account
- Please note as well if you are using an app that uses JWT authentication that the remote ledger account will be frozen until KYC is passed. If you are using ECDSA authentication, the payment instrument will not be frozen, but you will not be able to transact with it until KYC is passed.
- Do not call /kyc again on a verification record that is in
documents_required
orreview
.
Advanced KYC
Advanced KYC:
- You will not see the
remote_ledger_account_id
in the /kyc response. Instead, it will be returned with the kyc_status webhook when KYC is passed. You can also call /get_wallets or /get_payment_methods to retrieve it.- Additional line to kyc_status webhook will look like:
"wallet_id": "wallet_uuid_string"
- Additional line to kyc_status webhook will look like:
- Note that you will not be able to transact with the new remote ledger account until KYC is passed. If you are using an app utilizing JWT authentication, the payment instrument will be frozen until KYC is passed.
Advanced KYC response sample
{
"reference": "<your unique id>",
"sila_reference_id": "sila_assigned_id",
"message": "user submitted for KYC review.",
"external_request": true,
"success": true,
"verification_uuid": "482d405f-2dc4-4cbc-9f37-13e0dfa8be5a",
"verification_uuid_by_entity": {
"user_handle": "verification_uuid"
}
"status": "SUCCESS",
"response_time_ms": "171"
}
Classic KYC (legacy)
Classic KYC: accounts: { <entity_handle>: <remote_ledger_account_id> }
field will be empty unless there is a Priority verification existing.
- Note that you will not be able to transact with the new remote ledger account until KYC is passed. If you are using an app utilizing JWT authentication, the payment instrument will be frozen until KYC is passed.
Classic KYC response sample
{
"reference": "<your unique id>",
"sila_reference_id": "sila_assigned_id",
"message": "user submitted for KYC review.",
"external_request": true,
"success": true,
"verification_uuid": "482d405f-2dc4-4cbc-9f37-13e0dfa8be5a",
"accounts": {
"user_handle": "remote_ledger_acccount_uuid"
},
"verification_uuid_by_entity": {
"user_handle": "verification_uuid"
}
"status": "SUCCESS",
"response_time_ms": "171"
}
Existing doc linked above has been updated with Priority specifications.
Do not display the returned
tags
andreasons
to your end users
Handling
documents_required
IN SANDBOX
- Provide
block
as the first and last name for individual entities or entity name for business entities
- Triggers the end user failing KYC. You may first get a
documents_required
status, but will end infailed
- Provide generic test names for the first and last name for individual entities or entity name for business entities
- Triggers the entity to move directly to
passed
- There is currently no way to trigger a
documents_required
status and upload documentation to move that status topassed
or any other statusIN PRODUCTION
- If a verification record goes to
documents_required
and documents are not uploaded within 30 days, that verification record will automatically fail. If you find an end user in this scenario, please upload docs and reach out to let us know so that we can assist.- Updating entity PII first is no longer a requirement, and if you are using Advanced KYC you will no longer receive a webhook specifying
entity_data
as the action needed.
- Note as well /resume_verification is no longer relevant with the Priority KYC system.
- If the doc is incomplete in some way, such as missing a signature, you will be prompted to upload the doc again.
- If the doc provided does not provide enough further verification to pass KYC, you will be prompted to upload a different doc.
- Priority estimates an approximately 24 hour turnaround time for reviewing uploaded docs.
- There is NOT a limit on the number of times the same or different docs can be uploaded for a single verification record. However, only one verification is allowed. You will receive an error if you re-request KYC for an entity that already has a verification record.
Advanced KYC - /get_verification/<verification_uuid>
- no
tags
reasons
will be a dict of human-readable explanations."user_handle": [ "list of reason strings" ]\
Please use our KYC status webhooks instead of polling this endpoint to check that end users have passed KYC
Classic KYC - /check_kyc (legacy)
tags
andreasons
fields in the response will be from Priority:tags
will contain something likeADDRESS_VALIDATION
orNAME_VALIDATION
reasons
will be human-readable explanation of the risk code returned intags
Documents related pages that have been updated for Priority specifications
- /documents (linked above)
- /document_types
- /get_document
- /list_documents
Test in Sandbox
While the full documents_required flow is not yet supported in the Sandbox environment, we STRONGLY recommend testing this endpoint and making sure you can upload a doc before going live in Production.
This is one of our more complicated endpoints, and will be important immediately after going live if docs are required to pass your initial business entity through KYC. We cannot set up your Priority reserve without your initial entities passing through KYC, and we cannot turn on transacting for you without that Priority reserve set up and funded.
- The
verification_uuid
field in the request is now required. This value is returned by /kyc and /get_verifications. - When using the
tags
andreasons
fields returned by /get_verifications/<verification_uuid> to determine the type of document that should be uploaded when further verification is needed, note that only the below list of documents is accepted - Priority estimates an approximately 24 hour turnaround time for reviewing uploaded docs.
- Only DL and State ID's require front and back images.
Existing doc linked above has been updated for Priority specifications.
Use this endpoint to link an external bank account to an entity.
DO NOT RE-USE PROCESSOR TOKENS
Processor tokens are meant for one, single use for linking one, single bank account. You should never be re-using processor tokens, regardless of what environment you are in.
Existing doc linked above has been updated for Priority specifications.
Existing doc linked above has been updated for Priority specifications.
Single endpoint for all transaction types and processing types.
External Origination Transactions
With Priority, Sila now supports funds being pushed into a Priority ledger account from an external bank account that has not been linked in the Sila environment via Plaid or MX. The end user can use the account and routing numbers of their Priority ledger account to do so.
Identifying source and destination
SOURCE
Please be aware that since these transactions are initiated outside of Sila's environment, we do not have a way to identify the source. The source will always be
Priority External Originator
.DESTINATION
The only way currently to identify the destination of an external origination transaction is to use the UUID from the Transaction Status Update webhook to find more information. We are currently doing work to include
destination_id
in the webhook payload.
- These transactions are created with their own unique transaction UUID's just like all other transaction types.
- The origination / source_id for these will be a payment instrument UUID belonging to a
Priority External Originator
. This UUID does not change per transaction - you can expect the UUID in Production to always be the same for these transactions. - Sandbox does not yet support creating these types of payments, but a few transactions can be created manually by request.
- These transactions are also supported by the Transaction Status Update webhook. You'll see a new boolean field:
externally_originated
.
Wires
See /transact doc for more details.
We currently only support pushing funds from a remote ledger account to an external bank account via wire.
We are exploring the possibility of supporting incoming wires with Priority.
Testing ACHNow, RTP, and Prod in Sandbox
A specific routing number is required to successfully transact with RTP and FedNow in Sandbox, so these accounts will need to be linked manually rather than with Plaid or MX.
Please find our manual account linking documentation here. You will need to use routing number 122105155
in the request.
Manually linked accounts are only necessary for RTP and FedNow transactions in Sandbox, and can only be used in Production with explicit permission from Sila
Statements
Existing statements documentation has been updated for Priority specifications. Please start with this overview page.
Opens an additional remote ledger account. Can't be called until KYC has been passed.
New error that will be thrown if this endpoint is called before an end user has passed KYC:
Status Code | Success Attribute | Description |
---|---|---|
403 | false | Handle <user_handle> has not completed verification |
New response data returned:
remote_account_details
object including:account_number
- remote ledger account numberrouting_number
- remote ledger account routing numberwire_account_number
wire_routing_number
{
"success": true,
"reference": "<your unique id>",
"sila_reference_id": "sila_assigned_id",
"wallet": {
"wallet_id": "wallet_uuid",
"payment_instrument_id": "wallet_uuid",
"nickname": "nickname",
"default": true,
"wallet_address": null,
"network": null,
"statements_enabled": true
},
"is_whitelisted": true,
"sila_balance": 5000,
"sila_available_balance": 5000,
"sila_pending_balance": 0,
"status": "SUCCESS",
"response_time_ms": "49",
"sila_reference_id": "req_jei3jf7"
"remote_account_details": {
"account_number": <account number of the remote account>,
"routing_number": <routing number of the remote account>,
"wire_account_number": <wire account number>
"wire_routing_number": <wire routing number>
}
}
New response data returned:
remote_account_details
object including:account_number
- remote ledger account numberrouting_number
- remote ledger account routing numberwire_account_number
wire_routing_number
{
"success": true,
"status": "SUCCESS",
"response_time_ms": "171",
"reference": "<your unique id>",
"sila_reference_id": "sila_assigned_id",
"wallets": [
{
"wallet_id": "e8ea2d24-02d8-43e3-a216-6ac1d36f2016",
"nickname": "",
"frozen": False,
"default": True,
"remote_account_details": {
"account_number": <account number of the remote account>,
"routing_number": <routing number of the remote account>,
"wire_account_number": <wire account number>
"wire_routing_number": <wire routing number>
}
}
],
"page": 1,
"returned_count": 1,
"total_count": 1,
"total_page_count": 1
}
Existing doc linked above has been updated for Priority specifications.
Updated 7 days ago