Fund via Book Transfer

This guide walks you through funding a customer's fiat account using a book transfer from the bank's fiat account.

⚠️

Sandbox only

Book transfers are only available in the sandbox environment for testing purposes.

Prerequisites

Before you begin, ensure you have:

• a customer already created and verified;
• a fiat account created for the customer; and,
• a bank-level fiat account with sufficient balance.

Overview

The book transfer process involves three main steps:

1. Create a book_transfer quote
2. Execute a transfer with transfer_type set to book
3. Monitor the transfer until it reaches the completed state

Step 1: Create a book_transfer quote

Create a quote via POST /api/quotes:

{
  "product_type": "book_transfer",
  "customer_guid": "customer_guid",
  "asset": "USD",
  "side": "deposit",
  "receive_amount": 10000
}

Set receive_amount to the desired amount. Once you have the quote guid, proceed to the transfers API.

ℹ️

Side display

Book transfers are always recorded as deposit at the API and raw data level. However, in the Cybrid portal or custom UIs, the transaction side may appear as withdrawal or deposit depending on the viewer's perspective (e.g., customer vs. bank). This is a display convention and not a data inconsistency. To always show deposit, display the API's side value directly in your frontend logic.

Step 2: Execute the transfer

Create a transfer via POST /api/transfers:

{
  "quote_guid": "quote_guid",
  "transfer_type": "book",
  "source_account_guid": "bank_fiat_account_guid",
  "destination_account_guid": "customer_fiat_account_guid",
  "source_participants": [
    {
      "type": "bank",
      "guid": "bank_guid",
      "amount": 10000
    }
  ],
  "destination_participants": [
    {
      "type": "customer",
      "guid": "customer_guid",
      "amount": 10000
    }
  ]
}

ℹ️

Sandbox testing

The expected_state field is only available in sandbox to force specific transfer outcomes. Add "expected_state": "pending" to the transfer request body to test state handling.

Step 3: Monitor the transfer

Although book transfers settle almost instantly, all transfers are asynchronous. Monitor the transfer state to confirm it reaches completed before using the funds.

Monitor transfer state by querying GET /api/transfers/{transfer_guid}, or register for webhooks to receive automatic notifications on state changes.