Funding Accounts

How do I fund an account with fiat?

Learn how to create a transfer on the Cybrid Platform to fund a customer account with fiat currency.

Choosing your funding method

There's three different ways to fund an account with fiat currency:

  1. Funding transfer from a customer's Plaid connected bank account
  2. Book transfer from the bank-level fiat account
  3. Wire transfer to the fiat account

Method #1 - Funding from Plaid connected account

Creating the quote and transfer

Funding an account involves creating a quote, via the POST /api/quotes endpoint, then executing a transfer against that quote via the POST /api/transfers endpoint. If you head over to the /api/quotes endpoint, the process would look similar below.

Create a funding quote by executing a POST on /api/quotes:

{
  "product_type": "funding",
  "customer_guid": "your-customer-guid",
  "asset": "USD",
  "side": "deposit",
  "receive_amount": 10000
}

❗️

Important: Be careful when entering the receive_amount, as it is in the base units of the currency. In the above example, the base unit of USD is cents, so the value above of 10,000, equates to 10,000 cents, or $100.00 USD. You can always call the /api/assets endpoint to get the number of base decimals in a currency.

In our example the asset is USD, and you'll set the side to deposit, and the receive_amount to the desired amount. One you've executed the call and have your quote GUID, you can proceed to the transfers API.

You'll want to keep the customer's external_bank_account_guid handy in order to create a transfer. You can retrieve the GUID for an external account by calling the GET /api/external_bank_accounts endpoint, with the bank GUID and customer GUID.

Create a transfer by executing a POST on /api/transfers endpoint with a transfer_type of funding, and the quote GUID and external_bank_account GUID. It will look like this:

❗️

Important: If you're using the Plaid Connect method for connecting end-customer bank accounts to the Cybrid Platform, you'll be limited to $100.00 funding transfers in the Sandbox environment. You can, however, do an unlimited number of $100.00 fundings.

{
  "quote_guid": "your-quote-guid",
  "transfer_type": "funding",
  "external_bank_account_guid": "your-account-string",
  "expected_error": "pending"
}

Monitoring for the transfer to be complete

After successfully creating a transfer, you will need to monitor for the transfer to be completed. Fiat transfers typically take T+1 (1 business day) to complete. This means if you request a transfer at 4pm on a Monday, it could be up to 4pm on Tuesday before the transfer has completed. This is due to the EFT or ACH processing time incurred as the money is moved between banks.

You can monitor for the transfer state by querying the GET /api/transfers/{transfer_guid} endpoint with the GUID you received from the POST call. Shortly after the transfer is created the state will be pending, but will eventually change to completed when we successfully confirm the correct amount of money has been transferred to the customers fiat account on the Cybrid Platform.

Method #2 - Funding via book transfer

Funding via a book transfer is similar to funding from a Plaid connected account, however the settlement time is significantly reduced as the funds are being settled on the internal Cybrid ledger.

Creating the quote and transfer

Funding an account via book transfer involves creating a quote, via the POST /api/quotes endpoint, then executing a transfer against that quote via the POST /api/transfers endpoint. If you head over to the /api/quotes endpoint, the process would look similar below.

Create a book transfer quote by executing a POST on /api/quotes:

{
  "product_type": "book_transfer",
  "customer_guid": "your-customer-guid",
  "asset": "USD",
  "side": "deposit",
  "receive_amount": 10000
}

In our example the asset is USD, and you'll set the side to deposit, and the receive_amount to the desired amount. One you've executed the call and have your quote GUID, you can proceed to the transfers API.

You'll want to keep the customer's external_bank_account_guid handy in order to create a transfer. You can retrieve the GUID for an external account by calling the GET /api/external_bank_accounts endpoint, with the bank GUID and customer GUID.

Create a transfer by executing a POST on /api/transfers endpoint with a transfer_type of funding, and the quote GUID and external_bank_account GUID. It will look like this:

{
"quote_guid": "your-quote-guid",
"transfer_type": "funding",
"external_bank_account_guid": "your-account-string",
"expected_error": "pending"
}

Method #3 - Funding via wire transfer

Receiving a wire transfer to the Cybrid Platform requires a fiat account as well as a deposit bank account. The deposit bank account provides the routing details for wire transfers, and the funds are reconciled to the linked fiat account.

When a wire transfer is complete, the platform_balance in the fiat account will reflect the wire transfer amount. Funds are never held in the deposit bank account, only in the fiat account.

Funding via a wire transfer requires the following steps:

  • The Cybrid team enables routable deposit bank accounts at your bank-level.
    • You may already have this feature is enabled at your bank-level for bank/customer routable deposit bank accounts.
    • If you haven't already, submit a request to the Cybrid team.
  • Create a fiat account.
    • You may already have a fiat account created at your bank-level.
    • If you haven't already, see steps below.
  • Create a deposit bank account.
  • Provide the deposit bank account counterparty details to the Cybrid team.
  • The Cybrid team configures the deposit bank account with the counterparty details.
  • Wire funds to the deposit bank account.

Create a fiat account

To create a USD fiat account at your bank-level, use the POST /api/accounts endpoint.

The following is an example of a request for the POST /api/accounts endpoint:

{
  "type": "fiat",
  "customer_guid": "<insert customer_guid>",
  "asset": "USD",
  "name": "<insert a descriptive account name>"
}

The is the response schema from the above request:

{
  "type": "string",
  "guid": "string",
  "created_at": "2024-06-07T15:17:37.355Z",
  "updated_at": "2024-06-07T15:17:37.355Z",
  "asset": "string",
  "name": "string",
  "bank_guid": "string",
  "customer_guid": "string",
  "platform_balance": 0,
  "platform_available": 0,
  "state": "string",
  "labels": [
    "string"
  ]
}

You'll use the guid from the response above when creating the deposit bank account.

Create a deposit bank account

To create a routable deposit bank account, use the POST /api/deposit_bank_accounts endpoint.

The following is an example of a request for the POST /api/deposit_bank_accounts endpoint:

{
  "account_guid": "<insert account_guid>",
  "customer_guid": "<insert customer_guid>"
}

The following is the response schema from the above request:

{
  "guid": "string",
  "bank_guid": "string",
  "customer_guid": "string",
  "account_guid": "string",
  "created_at": "2024-06-07T15:17:37.355Z",
  "updated_at": "2024-06-07T15:17:37.355Z",
  "asset": "string",
  "state": "string",
  "unique_memo_id": "string",
  "counterparty_name": "string",
  "counterparty_address": {
    "street": "string",
    "street2": "string",
    "city": "string",
    "subdivision": "string",
    "postal_code": "string",
    "country_code": "string"
  },
  "account_details": [
    {
      "account_number": "string"
    }
  ],
  "routing_details": [
    {
      "routing_number_type": "string",
      "routing_number": "string"
    }
  ],
  "labels": [
    "string"
  ]
}

Provide deposit bank account counterparty details to the Cybrid team

You'll notice that the counterparty_name and counterparty_address returned in this response are placeholder data.

You'll need to provide the guid from the response above, as well as the following deposit bank account counterparty details to the Cybrid team in your partner channel:

  • Counterparty name
  • Counterparty address:
    • Street
    • Street2
    • City
    • Subdivision (i.e. state/province)
    • Postal code/zip code
    • Country code
  • Counterparty email
  • Counterparty phone

The Cybrid team configures the deposit bank account with the counterparty details

After providing the deposit bank account guid and counterparty details to Cybrid team in your partner channel, the Cybrid team will confirm when the configuration of your deposit bank account is complete.

Once the Cybrid team has confirmed the configuration is complete, you may then initiate a wire transfer to this deposit bank account.

Wire funds to the deposit bank account

To initiate a wire transfer to the deposit bank account, retrieve the routing details for this deposit bank account using GET /api/deposit_bank_accounts/{deposit_bank_account_guid} endpoint.

This wire transfer funding will create a new funding deposit transfer on the Cybrid Platform. This funding deposit transfer will progress through the typical sequence of states (i.e. pending, completed, failed).

As with all transfers, you can use the GET /api/transfers/{transfer_guid} endpoint to retrieve the details of the transfer. For wire transfers, you'll see "payment_rail":"wire" in the GET response above.

Updated about 1 month ago