A book transfer, by default, will move money from one of your Column accounts to another instantaneously.

We also support staged, two part, transfers that place a hold on funds before they are moved. If you pass in the hold: true parameter to the book transfer, rather than immediately moving the funds, we will create a transfer in a "hold" state that must be cleared via the "Clear Book Transfer" endpoint. Transfers in a hold state can also be updated or cancelled.

Holding Balance

Funds in the "hold" state will show up in a "holding" balance on the sender account. These funds will NOT be available for any developer initiated transfers, including ACHs or Wires. However, incoming ACH Debits from other banks will see the holding balance as available to withdraw. We will not automatically create an ACH return for not-sufficient funds if the funds are in the holding balance. This may lead to overdrafts on your accounts.

Example: Card Auth, Capture, and Clearing

Lets say you want to support a Debit Card account and clearing workflow. The developer has already set up two Column accounts, one for the customers debit card bacc_customer, and one for the settlement account with the card network bacc_settlement.

The customer uses your debit card at a hotel, which results in a $100 auth, a $300 re-auth, and finally a $250 capture from the merchant over a couple days.

The customer swipes card, and the developer receives an auth for $100 and calls the create book transfer endpoint:

curl https://api.column.com/transfers/book \
  -X POST \
  -u :{test_api-key} \
  -d receiver_bank_account_id={bacc_settlement} \
  -d sender_bank_account_id={bacc_customer} \
  -d hold=true \
  -d amount=10000 \
  -d currency_code=USD \
  -d allow_overdraft=true \
  -d description="hotel payment"

This creates a transfer with id book_example1 with a status of hold. The same rules around sufficient funding and overdrafts that apply to book transfers, also apply to book transfers with holds, and any hold with non-sufficient funds will not be created.

After 2 nights at the hotel, the customer checks out, which results in a re-auth of $300 on the card. The developer makes a "PATCH" request to re-auth for a higher amount:

curl https://api.column.com/transfers/book/{book_example1} \
  -X PATCH \
  -u :{test_api-key} \
  -d amount=30000 \
  -d allow_overdraft=true

The book transfer hold is updated to $300.

Finally, the hotel realizes the customer had a discount, and at the end of the day does a merchant capture of $250 on the card. The developer calls the "Clear Book Transfer" endpoint.

curl https://api.column.com/transfers/book/{book_example1}/clear \
  -X POST \
  -u :{test_api-key} \
  -d amount=25000 \
  -d allow_overdraft=true

The transfer is now completed, and funds will appear in the receiver bank account. If, for some reason, the developer wanted to cancel the hold, they could call the endpoint at https://api.column.com/transfers/book/book_example1/cancel.