Instant Settlement (BETA)

Sila’s Instant Settlement feature allows customers at a Grow II or higher tier 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 Sale's 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 you application.

What is a Customer Reserve Wallets (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 Sila from your CRW until there are no unsettled transactions for your app.

Usage

Issue Sila

To create an Instant Settlement transaction, use the /issue_sila endpoint with "processing_type": "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",
            "sila_amount": 1000,
            "status": "pending",
            "usd_status": "pending",
            "token_status": "queued",
            "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",
            "sila_amount": 100,
            "status": "success",
            "usd_status": "success",
            "token_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",
            "sila_amount": 420,
            "status": "failed",
            "usd_status": "failed",
            "token_status": "queued",
            "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",
                    "sila_amount": 420,
                    "status": "success",
                    "usd_status": "queued",
                    "token_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 /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"
}

Understanding Parent-Child relationship in Issue Sila transactions

To facilitate an Instant Settlement transaction, we create two types of transactions:

  • Parent: Issue transaction that is initiated by the end user.
  • Child: Transfer transaction that facilitates instant settlement of funds and returns.

These two transactions are created and updated in the following scenarios:

Happy Path

  1. Initiate Issue transaction with processing_type: “INSTANT_SETTLEMENT”. This is denoted as the parent transaction with following information:
  • id: 1
  • source: End-user Bank Account
  • destination: End-user Wallet
  • status : Success (as soon as the funds reach the destination wallet)
  1. Initiate transfer from SFW to end-user wallet with processing type instant settlement. This transaction is denoted as a child transaction with following details:
  • source: SFW
  • destination: End-user Wallet
  • parent_transaction_id: 1
  • status: Success
    To establish the relation, parent_transaction_id is passed to child transaction

SFW(Sila Funding Wallet): A funding wallet used to facilitate Instant Settlement transactions.

The child transaction is completed immediately, while the parent transaction is
completed within 1-2 business days(depending upon ACH completion).

Visibility of transactions in /get_transactions:

  • Only Parent Transaction is visible with get_transactions

Standard Return

In a standard return, the steps 1-3, mentioned above in the happy path scenarios are executed and an ACH return is encountered within two working days.

In this case, the parent transaction details look like the following:

  • id: 1
  • source: End-user Bank Account
  • destination: End-user Wallet
  • status: ACH return

Once a return is encountered, we initiate another child transaction for its handling to
transfer the transaction amount from CRW to SFW. The child transaction has the
following details:

  • source: CRW
  • destination: SFW
  • parent_transaction_id: 1

We will have two child transactions for one for happy path and another for delayed
return.

Visibility of transaction in /get_transactions:

  • Parent transaction and return transaction nested as child transaction are visible

Delayed Return

In case of delayed return the steps 1-3, mentioned above in the happy path scenarios
are executed and ACH return is encountered after two working days.

In this case, the parent transaction details look like the following:

  • id: 1
  • source: End-user Bank Account
  • destination: End-user Wallet
  • status: ACH return

After Parent is marked successful Initiate another child transaction for handling returns to Burn sila from CRW. The child transaction has the following details:

  • source: CRW (burn tokens)
  • destination: SFW (do not credit)
  • parent_transaction_id: 1
    We will have two child transactions for one for happy path and another for delayed
    return.

Visibility of transaction in /get_transactions:

  • Parent transaction and return transaction nested as child transaction are visible.

Error Message

Description

Troubleshooting

Error Status Code

INSTANT_SETTLEMENT_NOT_ENABLED

Instant Settlement is disabled for the application being used.

To learn more about Instant Settlement, please see the docs or contact your Sila Sales Account Executive.

403

TRANSACTION_AMOUNT_HIGHER_THAN_MINIMUM_CRW_BALANCE

The transaction amount issued is more than minimum Reserve Wallet balance.

403

INSUFFICIENT_RESERVE_WALLET_BALANCE

Application Reserve Wallet does not have sufficient balance.

Please /issue or transfer funds into your reserve wallet in order to or contact support for further assistance.

403

How to set up Instant Settlement in your application

  1. Contact your Sila Sale's 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. Contact Sila support via Slack and provide the following:

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

  • For SANDBOX: app_handle, user_handle and the Wallet ID
  • For PRODUCTION: Company Legal Name, app_handle, user_handle and the Wallet ID
  1. Establishing CRW Thresholds
  • For SANDBOX: TBD
  • For PRODUCTION: Sila's BankOps team will establish a Warning Threshold and Minimum Threshold for your CRW based on volume and risk.
  1. 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.
  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.

  1. Fund your CRW
  • For SANDBOX: fund your CRW wallet with the applicable threshold funds
  • For PRODUCTION: fund your CRW wallet with the threshold funds outlined by Sila's BankOps team
  1. Once the funds settle...You're all set!

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.


Did this page help you?