Priority Integration

❗️

THIS PAGE IS ACTIVELY BEING UPDATED

Code and functionality is just about finalized, but small changes may still be coming.

Refresh or reload the page in order to see updates.

KEEP A CLOSE EYE ON THIS PAGE FOR UPDATES AS YOU BUILD OUT YOUR OWN INTEGRATION

📘

Terminology Note

• remote ledger account: a ledger account opened up at Priority, managed by Priority, for each end user onboarded.
• external bank account / external account: the end user's personal bank account at their own banking institution.

For Priority customers, the use of Sila wallet in our documentation and APIs refers to the remote ledger account at Priority.

In the typical Sila behavior, each end user has a Sila wallet associated with them. Funds move between external bank accounts into and out of the Sila ecosystem through these wallets.

For Priority customers, there is a remote ledger account with its own account and routing number opened up on behalf of each end user.

• /request_kyc or /kyc - opens a remote ledger account
• /delete_wallet - closes a remote ledger account
• /register_wallet - 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

👍

What happens if KYC is requested on an end user but they have not passed yet at the time of the migration?

You can expect these verification records to process like normal. The migration should not affect existing records.

However, if you get a documents_required status, make sure to include the verification_uuid in the /documents call to make sure the correct record is updated.

Once the migration is complete, please start including verification_uuid for all /documents requests whether KYC was kicked off before or after the migration.

Basic Flow

Individual entity

HAPPY PATH

1. Create entity with /register
2. /request_kyc or /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. /request_kyc or /kyc kicks off KYC process and opens remote ledger account
3. Does not pass KYC - use /check_kyc or /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 /request_kyc or /kyc on the individual members
   2. Members must be linked prior to calling /request_kyc or /kyc on the business entity
3. /request_kyc or /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. Pass KYC
5. Link external bank accounts
6. 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 /request_kyc or /kyc on the individual members
   2. Members must be linked prior to calling /request_kyc or /kyc on the business entity
3. /request_kyc or /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 /check_kyc or /get_verifications/<verification_uuid> to determine doc to upload
5. Entity/entities pass or fail KYC. If entity/entities pass, continue to 6 and 7.
6. Link external bank accounts
7. Transact

🚧

Additional changes to the basic KYC/KYB flow

• There is no longer a requirement to allow end user to update their PII before moving on to uploading documentation. With Priority, if further verification is required, you will immediately receive a documents_required status.
• Advanced KYC specific:
  • You no longer need to call the /resume_verification endpoint. Uploading a doc with /documents will restart the verification process on its own.
  • You will still need the kyc_action webhook to know when the status has changed to documents_required. You can disregard the action_needed field.
  • You will need to create a new KYC Flow in the console after migrating in Prod or after Priority is turned on in Sandbox.

Summary of Changes Needed

• No new endpoints or webhooks
• New receipt language to display to end users upon their successful submission of a transaction
• Advanced KYC users will need to create a new KYC Flow in the console
• Endpoints where coding changes are necessary:
  • /register - all registration data that is required to start KYC process is required to call /register successfully. Additional data for registering a business or business members
  • /link_business_member - new restrictions for successfully linking members
  • /request_kyc and /kyc -
    • creates remote ledger account
    • response includes remote ledger account and verification UUID data
    • new kyc_level values added and is required
  • /documents -
    • small change to response data
    • formerly optional request value now required: verification_uuid
  • /transact (if using wires) - new route value
    • NOTE: we currently do not support bank account > remote ledger account wires. Wires will need to be remote ledger account > bank account.
  • /register_wallet -
    • Opens an additional remote ledger account to the initial one that is created when calling /request_kyc or /kyc.
    • Must be called after KYC has been passed. The /register endpoint will not create a Sila wallet
    • New error if /register_wallet is called before end user passes KYC
  • new response data returned for -
    • /get_wallet
    • /get_wallets
    • get_accounts

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.

Code Changes and Full Endpoint Flow

Endpoints with coding changes required are marked with an asterisk (*).

/register *

• 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.
• doing_business_as is required for business entities for Priority (see below business registration data code block), even though it is listed as optional on /register doc.
• Will not open remote ledger account / create wallet object in Sila ecosystem. See /request_kyc and /kyc.

🚧

Use Unique SSNs

Even in Sandbox, make sure you are registering users with unique SSNs, or KYC verification will not proceed as expected.

KYB Registration *

• New business registration data: additional data for entity code block
  • This data is NOT needed for business members.

},
  "entity": {
    "entity_name": "Example User",
    "business_type": "corporation",
    "naics_code": 721,
    "doing_business_as": "dba name", // required
    "type": "business", // required
    "registration_date": YYYY-MM-DD, // required
    "registration_state": "OR" // required
  },

• New business member registration data: Business members are required to include an ID number. Please add the additional id_document code block in the request.
  • This block is NOT for registering business entities. Business members only.

!! You do NOT need to upload an actual document. Just provide the appropriate data in this id_document block during /register.

NOTE: Supply EITHER doc_country OR doc_state, not both.

"id_document": {
       "doc_type": "id_passport", // required
       "doc_id": "123456789", // required
       "doc_country": "US", // required for passport or green card
       "doc_state": "OR" // required for state ID or driver's license
 }

/update/ *

• No coding changes unless updating a business or business member.
• Endpoint can be used to update additional entity or id_document data outlined in /register section above.

/link_business_member *

• Do NOT call /request_kyc or /kyc on business members. Link them to the business first, and then /request_kyc or /kyc on the business entity.
• New requirements to successfully link a business member (id_document).
• Handling for new possible errors is the only change here. Use this endpoint to link business members to the business prior to calling KYC on the business.

/request_kyc or /kyc *

• Creates the remote ledger account
  • Remote ledger account is created from the a successful call to /request_kyc or /kyc, and is not based on the outcome of the KYC verification record.
  • 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 /request_kyc or /kyc again on a verification record that is in documents_required or review.

📘

Handling documents_required

IN SANDBOX

• To trigger a documents_required status in Sandbox, provide block as the first and last name for individual entities or the entity name for business entities.
• Once you upload a doc, the status should change to documents_received
• To trigger a passed status: please set name = mock doc passed in the /documents request

IN PRODUCTION

• Skip updating entity PII first. This is no longer a requirement, and we are still working on making it an option with Priority.
• 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.

Request

• New kyc_level value specific to Priority customers is now required.
  • KYC-PRIORITY - individual entity
  • KYB-PRIORITY - business entity

  Full request sample

  {
    "header": {
      "created": 1234567890, 
      "app_handle": "app_handle", //required
      "user_handle":"user_handle", //required
      "version": "0.2", 
      "reference": "<your unique id>"
    }, 
    "message": "header_msg",
    "kyc_level": "KYC-PRIORITY" //required
  }
  

Response

New response data:

• New field for both Classic and Advanced KYC response: verification_uuid_by_entity: { <entity_handle> : <verification_uuid> }

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

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

/check_kyc or /get_verifications/<verification_uuid>

Classic KYC - /check_kyc

• 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

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 Status webhook
• Advanced KYC Status webhook

/documents *

• The verification_uuid field in the request is now required. This value is returned by /request_kyc, /kyc, /check_kyc, and /get_verifications.
• When using the tags and reasons fields returned by /check_kyc or /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.
• Please see /document_types for all supported doc_types

• Articles of Incorporation
• Certificate of Formation
• Credit Card Statement
• Divorce Decree
• Driver's License
• Driver's Permit
• EIN Verification Letter
• Mortgage Agreement
• US Passport
• Social Security Card
• State ID
• SS4
• IRS Tax Return
• 1040 Tax Return
• 1095 Tax Statement
• 1099
• W9
• Utility Bill

TAG TO DOC_TYPE MAPPING

/link_account

• No code changes. Use this endpoint to link external bank accounts after the end user has passed KYC.

Linking the same bank account to the same entity more than once is restricted.

/transact *

• We recommend using /transact rather than /issue_sila, /transfer_sila, and /redeem_sila, but these three can still be used. /transact is only required to be used for wires and ACHNow.
• RTP and FedNow transactions not currently supported
• New route value available for wires: wire
  • NOTE: We currently only support wiring funds from a remote ledger account to an external bank account (push). We DO NOT support sending a wire from an external bank account to a remote ledger account (pull).

"route": "wire"

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

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

New response data:

• wire_routing_number - the wire routing number of the end user's personal bank account.
  • NOTE: this currently only works for newly linked external

[
  {
    "account_number": "*1234", 
    "routing_number": "123456789", 
    "wire_routing_number": "<wire routing number>",
    "account_name": "default",
    "account_type": "CHECKING",
    "active": true,
    "account_status": "active",
    "account_link_status": "processor_token",
    "match_score": 0.825,
    "account_owner_name": "Test User",
    "entity_name": "Test User",
    "web_debit_verified":true,
    "provider_name": "PLAID",
    "payment_instrument_uuid": "<uuid string>",
    "capabilities": {
      "aba_routing_number": "123456780",
      "fednow": {
          "credit_enabled": false,
          "debit_enabled": false
      },
      "rtp": {
          "credit_enabled": false,
          "debit_enabled": false
      }
    }
  }
]