API Documentation

Priority Integration

An implementation guide for Priority customers.

Suggest Edits

❗️

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

  1. Create entity with /register
  2. /kyc kicks off KYC process and opens remote ledger account
  3. Pass KYC
  4. Link external bank accounts
  5. Transact

UNHAPPY PATH

  1. Create entity with /register
  2. /kyc kicks off KYC process and opens remote ledger account
  3. Does not pass KYC - use /get_verifications/<verification_uuid> to determine doc to upload
  4. Upload doc with /documents
  5. Entity passes or fails KYC. If entity passes, continue to 6 and 7.
  6. Link external bank accounts
  7. Transact

Business entity

HAPPY PATH

  1. Create business entity and all individual entities to be added as business members
  2. Link all business members to business entity
    1. Do NOT call /kyc on the individual members
    2. Members must be linked prior to calling /kyc on the business entity
  3. /kyc on the business entity kicks off KYC process and opens remote ledger accounts for business and all members.
  4. Pass KYC
  5. Certify any linked beneficial owners and the business
  6. Link external bank accounts
  7. Transact

UNHAPPY PATH

  1. Create business entity and all individual entities to be added as business members
  2. Link all business members to business entity
    1. Do NOT call /kyc on the individual members
    2. Members must be linked prior to calling /kyc on the business entity
  3. /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.
  4. Member or business does not pass KYC - use /get_verifications/<verification_uuid> to determine doc to upload
  5. Entity/entities pass or fail KYC. If entity/entities pass, continue to 6, 7, and 8.
  6. Certify any linked beneficial owners and the business
  7. Link external bank accounts
  8. 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

/register

👍

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)

🚧

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

📘

Supported Business Types

Please note Priority does not support linking the business types trust or unincorproated_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.

/add/

👍

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.

/update/

👍

Existing doc linked above has been updated for Priority specifications.

Use this endpoint to update existing registration information.

/link_business_member

👍

Existing doc linked above has been updated for Priority specifications.

Use this endpoint to link individuals to businesses and assign them a role.

/kyc

👍

Docs updated with Priority specs

  • 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 or review.

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"
  • 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" 
}

/get_verifications/<verification_uuid>

👍

Existing doc linked above has been updated with Priority specifications.

❗️

Do not display the returned tags and reasons 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 in failed
  • 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 to passed or any other status

IN 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 and reasons fields in the response will be from Priority:
    • tags will contain something like ADDRESS_VALIDATION or NAME_VALIDATION
    • reasons will be human-readable explanation of the risk code returned in tags

/documents

👍

Documents related pages that have been updated for Priority specifications

🚧

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 and reasons 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.

/link_account

👍

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.

Priority Transaction Processing Schedule

👍

Existing doc linked above has been updated for Priority specifications.

/transact

👍

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.

/register_wallet

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 CodeSuccess AttributeDescription
403falseHandle <user_handle> has not completed verification

/get_wallet

New response data returned:

  • remote_account_details object including:
    • account_number - remote ledger account number
    • routing_number - remote ledger account routing number
    • wire_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>

  }
}

/get_wallets

New response data returned:

  • remote_account_details object including:
    • account_number - remote ledger account number
    • routing_number - remote ledger account routing number
    • wire_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
}

/get_accounts

👍

Existing doc linked above has been updated for Priority specifications.

Updated 17 days ago