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). More on that later.

  • 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

  • Contact your Sila Sale's Account Executive to ensure you are in the right payment tier and have Instant Settlement included in your MSA.
  • Create a Wallet for your Company

    Follow steps 1 - 4 on the Company Wallet Setup Doc here

  • Contact Sila customer service to provide the company wallet info and the Wallet ID

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

  • Sila's BankOps team will establish a Warning Threshold and Minimum Threshold for your CRW based on volume and risk.
  • Sila will convert your standard Company Wallet to a CRW and provision your app (both Sandbox and Production) with the threshold provided by Sila's BankOps team.
  • Link your business account to your CRW as a funding source.
  • Fund your CRW and once the funds settle...
  • You're all set!

What about Customer Reserve Wallets?

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"
Note when using a virtual account as the destination and processing_type = "INSTANT_SETTLEMENT", this is currently is not supported. The destination for this processing type must be the wallet.

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 : Pending (after ACH success transaction is set to success)
  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.

Did this page help you?