This guide uses the following endpoints
To create a book transfer you will need to
Assumptions
- You have access to at least two open accounts at the same bank.
- If you haven’t created any bank accounts yet, refer to the Opening an Account guide to get started.
- If you’re testing in the Developer Sandbox, accounts are automatically available when you create your sandbox environment.
- You have authorization to initiate payments between both the source and destination accounts that will be used in the book transfer.
How to Create a Book Transfer
1. Get the Account IDs
First, obtain the account IDs for the accounts you want to transfer funds between. Make aGET
request to the account
endpoint to retrieve this information.
id
property of each account object.
2. Create a New Book Transfer
Once you have the source and destination Account IDs, make aPOST
request to the book
endpoint, passing the amount
of the transfer, as well as the from_account_id
and the to_account_id
(representing the funding account and the receiving account respectively).
- The
amount
property expects the numeric value representing the amount of money to be transferred in dollars, with two-decimal precision (ex: 100.00). - While only the
amount
,from_account_id
, andto_account_id
fields are required, you can also include optional information. Use thedescription
field to add a human-readable explanation and theuserdata
field to store additional structured data like related payment references.
3. Get Status Updates
There are two ways to monitor book transfer status changes:Manually Checking for Status Updates
To check a book transfer’s current status, send aGET
request to the book
endpoint with the transfer’s id
. The response will contain the Book Transfer object with its current status.
status
has changed from “pending” to “sent”.
Listening For Status Updates with Webhooks
Register a webhook for thebook.update
event to receive automatic notifications whenever the status of a book transfer changes.
book.update
webhook notification, you can retrieve the current transfer status in two ways: either follow the steps described above to manually check the status, or make a GET
request to the URL provided in the notification’s url
property.