API Documentation

Instant Settlement

Suggest Edits

Sila’s Instant Settlement feature allows customers to make ACH funds immediately available to end users. Return costs are remedied via funds held in a Customer Reserve Wallet (CRW).

  • Instant Settlement instantly funds wallets. When the ACH transaction has settled, funds are settled directly to Sila.
  • You will be notified of all transaction events via transaction webhooks.
  • There is setup required to access this functionality (both in Sandbox and Production).
  • End-user bank accounts that generate returns will be programmatically restricted from using Instant Settlement again until you re-enable your customers via API.

📘

How to Enable Instant Settlement

  1. Contact your Sila Sales Account Executive to ensure you are in the right payment tier and have Instant Settlement included in your MSA.

See link here for how to get Instant Settlement set up in your application.

What is a Customer Reserve Wallet (CRW)?

CRWs are just wallets. These Wallets are solely a vehicle to remedy returns for Instant Settlement transactions. During the course of business, your end users may be generating ACH returns. When they do, Sila will recoup this amount from your CRW and draw down on that reserve. Because of this special purpose, there is some unique functionality to be aware of:

CRWs have a Warning Threshold: No one likes a surprise. When your CRW has breeched the Warning Threshold, you will start getting messages in API responses to Instant Settlement requests. This is your cue to top up your CRW.
CRWs have a Minimum Threshold: When your CRW breeches the Minimum Threshold, Instant Settlement will cease to work. We recommend building in logic to receive these errors and not offer Instant Settlement to your End Users until you top up.
Transactions: You can always issue or transfer into your CRW. However, you cannot transfer out or redeem funds from your CRW until there are no unsettled transactions for your app.

Transaction Diagram


Usage

Issue Sila

To create an Instant Settlement transaction, use the /issuesila endpoint with **"processingtype": "INSTANT_SETTLEMENT" **

Sample request body: 

{
"header": {
    "app_handle": "{{app_handle}}",
    "user_handle": "{{user_handle}}"
          },
"amount": 1000,
"account_name": "{{bank_account_name}}",
"processing_type": "INSTANT_SETTLEMENT"
}

Sample response body:

Note:

  • A new response parameter "Warning" is added, which will display a warning message whenever Customer Reserve Wallet balance is below warning balance threshold.
{
    "success": true,
    "message": "Transaction submitted to processing queue.",
    "reference": "5667443f-f9fd-4d3c-99c9-7843e7290912",
    "transaction_id": "fb304f03-4341-443d-9392-76234e811357",
    "descriptor": "",
    "warning": null,
    "status": "SUCCESS"
}

Get Transactions

Use "processing_type": "INSTANT_SETTLEMENT" to filter the Instant Settlement transactions with the /get_transactions API.

Sample request body: 

{
"header": {
    "app_handle": "{{app_handle}}",
    "user_handle": "{{user_handle}}"
          },
"search_filters": {
    "processing_type": "INSTANT_SETTLEMENT",
    "transaction_types": [
                          "issue"
                          ],
    "page": 1,
    "per_page": 20
    }
}

Sample response body:

Pending Instant Settlement transaction:

{
    "success": true,
    "transactions": [
        {
            "user_handle": "test_user",
            "reference_id": "5667443f-f9fd-4d1c-99c9-7843e7290912",
            "transaction_id": "fb304f03-4341-443d-9488-76234e811357",
            "transaction_hash": "",
            "transaction_type": "issue",
            "amount": 1000,
            "status": "pending",
            "created": "2022-01-10T14:27:28.570406+00:00",
            "last_update": "2022-01-10T14:27:29.084043+00:00",
            "created_epoch": 1641824848,
            "last_update_epoch": 1641824849,
            "descriptor": "",
            "descriptor_ach": "",
            "ach_name": "",
            "child_transactions": [],
            "sila_ledger_type": "Internal",
            "handle_address": "0xDAcF0c418c933A9sdb929a49B34C7a4fD6ec5342",
            "ledger_account_id": "8a770aee-7299-44ew-8faa-cefd2804fd93",
            "bank_account_name": "testbank",
            "processing_type": "INSTANT_SETTLEMENT",
            "submitted": "2022-01-10T14:28:09.722032+00:00",
            "submitted_epoch": 1641824889,
            "trace_number": "067216773163899",
            "addenda": "9e4f13e1-0e4e-4923-a549-f6cb71e0527a"
        },
    ],
    "page": 1,
    "returned_count": 1,
    "total_count": 1,
    "pagination": {
        "returned_count": 1,
        "total_count": 1,
        "current_page": 1,
        "total_pages": 1
    },
    "status": "SUCCESS",
    "reference": "2c16c8a1-9dc1-4ada8-bce2-1881693fc987"
}

Successful Instant Settlement transaction: 

{
    "success": true,
    "transactions": [
        {
            "user_handle": "test-user",
            "reference_id": "1d421252-dedd-4175-a0e2-2e45c4dce3e1",
            "transaction_id": "08792923-19c0-415a-b013-790324d22d4d",
            "transaction_hash": "",
            "transaction_type": "issue",
            "amount": 100,
            "status": "success",
            "created": "2022-01-14T06:06:26.674258+00:00",
            "last_update": "2022-01-14T06:38:31.137433+00:00",
            "created_epoch": 1642140386,
            "last_update_epoch": 1642142311,
            "descriptor": "",
            "descriptor_ach": "",
            "ach_name": "",
            "child_transactions": [],
            "sila_ledger_type": "Internal",
            "handle_address": "0xF8ea3da805d9Ac83181B00d0EdFeddD4aD91E757",
            "ledger_account_id": "590be7da-b683-4511-85ee-5112d6003e52",
            "bank_account_name": "test bank account",
            "processing_type": "INSTANT_SETTLEMENT",
            "submitted": "2022-01-14T06:37:00.206201+00:00",
            "submitted_epoch": 1642142220,
            "trace_number": "049211613157098",
            "addenda": "b1b545f6-6b0e-437e-8825-33813523ad41"
        },
    ],
    "page": 1,
    "returned_count": 1,
    "total_count": 1,
    "pagination": {
        "returned_count": 1,
        "total_count": 1,
        "current_page": 1,
        "total_pages": 1
    },
    "status": "SUCCESS",
    "reference": "2c16c8a1-9dc1-4ada8-bce2-1881693fc987"
}

Return received with Instant Settlement:*

{
    "success": true,
    "transactions": [
        {
            "user_handle": "test-user",
            "reference_id": "e4dd58ce-a2b5-4c65-a234-1cda4a1a8421",
            "transaction_id": "c6f6e3bc-1566-4c10-952d-ac72c2180866",
            "transaction_hash": "",
            "transaction_type": "issue",
            "amount": 420,
            "status": "failed",
            "created": "2022-01-11T08:55:14.290247+00:00",
            "last_update": "2022-01-11T08:58:23.790908+00:00",
            "created_epoch": 1641891314,
            "last_update_epoch": 1641891503,
            "descriptor": "",
            "descriptor_ach": "",
            "ach_name": "",
            "child_transactions": [
                {
                    "user_handle": "test-user",
                    "reference_id": "e4dd58ce-a2b5-4c65-a234-1cda4a1a8421",
                    "transaction_id": "f153f058-46c9-4983-b0cc-99c8a669bce0",
                    "transaction_hash": "",
                    "transaction_type": "transfer",
                    "amount": 420,
                    "status": "success",
                    "created": "2022-01-11T08:58:23.653895+00:00",
                    "last_update": "2022-01-11T08:58:39.679527+00:00",
                    "created_epoch": 1641891503,
                    "last_update_epoch": 1641891519,
                    "descriptor": "",
                    "descriptor_ach": "",
                    "ach_name": ""
                }
            ],
            "sila_ledger_type": "Internal",
            "handle_address": "0x4971CDa8a7c6E376a256990f3CD2Ce8299Ddd90B",
            "ledger_account_id": "e3093458-fd91-4421-acbb-a84235c8c90b",
            "bank_account_name": "cb_test_business",
            "processing_type": "INSTANT_SETTLEMENT",
            "submitted": "2022-01-11T08:57:07.924562+00:00",
            "submitted_epoch": 1641891427,
            "trace_number": "059514741696424",
            "addenda": "c6df1896-11fe-40f0-89e5-4ae72165b241",
            "error_code": "ACH_RETURN",
            "error_msg": "An ACH return was received for this transaction.",
            "return_code": "R01",
            "return_desc": "Insufficient funds"
        },
    ],
    "page": 1,
    "returned_count": 1,
    "total_count": 1,
    "pagination": {
        "returned_count": 1,
        "total_count": 1,
        "current_page": 1,
        "total_pages": 1
    },
    "status": "SUCCESS",
    "reference": "2c16c8a1-9dc1-4ada8-bce2-1881693fc987"
}

Cancel Transaction
Customers can cancel Instant Settlement transactions by using the _/cancel_transaction _endpoint. If a transaction is not processed (i.e not in a pending state), then the transaction will be canceled.

Sample request body: 

{
"header": {
    "app_handle": "{{app_handle}}",
    "user_handle": "{{user_handle}}"
          },
"transaction_id": "6bbc9e0f-0a4b-4aea-a82b-5c3d0a4e0729"
}

Sample response body: 

{
    "success": true,
    "message": "Transaction 38d0b104-bbe6-4748-8cee-9e96e8d2b1dd has been canceled.",
    "reference": "a44c7965-8b3e-4b61-b823-8a000720ce4f",
    "status": "SUCCESS"
}

How to set up Instant Settlement in your application

  1. Contact your Sila Sales Account Executive to ensure you are in the right payment tier and have Instant Settlement included in your MSA.

  2. Create a CRW for your Company

  • For SANDBOX: Create an individual user and wallet to use as your mock CRW.
  • For PRODUCTION: Follow steps 1 - 4 on the Company Wallet Setup Doc here to create your CRW.
  1. Linking an Account
    • For SANDBOX: link a mock Plaid account to your mock CRW.
    • For PRODUCTION: link your business account to your CRW as a funding source with /link_account.

      WARNING: you will freeze your account if you try to do this BEFORE we inform you that the Company Wallet has been converted to a CRW.

  2. Contact Sila support via Slack to get Establishing CRW Thresholds

  • For SANDBOX: pre-set default amount

    • CRW initial funding amount = 5000000 Sila ($50,000 USD) default sandbox limits
    • CRW min balance: 1000000 Sila ($10,000 USD) default sandbox limits
    • CRW warning threshold: 3000000 Sila ($30,000 USD) default sandbox limits

  • For PRODUCTION: Sila's BankOps team will establish the Initial Funding Amount, Warning Threshold, and Minimum Threshold for your CRW based on volume and risk.

  1. Fund your CRW

    • For SANDBOX: fund your CRW wallet with the applicable initial funding amount.
    • For PRODUCTION: fund your CRW wallet with the initial funding amount outlined by Sila's BankOps team.

  2. Once the funds settle, contact Sila support via Slack and provide the following:

    To get the wallet_id you need to use the /get_wallets endpoint 

    • For SANDBOX: app_handle, user_handle, and the Wallet ID
    • For PRODUCTION: Company Legal Name, app_handle, user_handle, and the Wallet ID

  3. Provision Application

  • For SANDBOX: Sila will provision your sandbox app with the applicable threshold and apply it to the mock CRW.
  • For PRODUCTION: Sila will convert your standard Company Wallet to a CRW and provision your production app with the threshold provided by Sila's BankOps team.

NOTE: Reminder for Onboarding customers, once you have been granted access to the Production ENV and Bank Ops has performed a Risk Analysis to set your CRW threshold these steps will need to be repeated for your Production App.

Updated 2 days ago