Skip to main content

​
This guide uses the following endpoints

​
To create a book transfer you will need to

  1. Get the account IDs
  2. Create a new book transfer
  3. Get status updates

​
Assumptions

  1. 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.
  2. 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 a GET request to the account endpoint to retrieve this information. 
curl -u $API_KEY_ID:$API_SECRET_KEY https://api.treasuryprime.com/account
This request returns a list of Account objects. You’ll need the Account ID for both the sending and receiving accounts, which you can find in the id property of each account object. 
{
  "data": [
    {
      "account_type": "savings",
      "bank_id": "bank_treasuryprime",
      "updated_at": "2021-02-01T16:32:34Z",
      "currency": null,
      "routing_number": "000000000",
      "account_number": "123000012345",
      "id": "acct_qda4pJZfpzn4fc",
      "created_at": "2021-01-13T15:05:14Z",
      "userdata": null
    },
    {
      "account_type": "checking",
      "bank_id": "bank_treasuryprime",
      "updated_at": "2021-02-01T16:32:34Z",
      "currency": null,
      "routing_number": "000000000",
      "account_number": "123000067890",
      "id": "acct_wVwR87rxhMRdwD",
      "created_at": "2021-01-13T15:05:13Z",
      "userdata": null
    }
  ],
  "total_estimated": 10
}

​
2. Create a New Book Transfer

Once you have the source and destination Account IDs, make a POST 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, and to_account_id fields are required, you can also include optional information. Use the description field to add a human-readable explanation and the userdata field to store additional structured data like related payment references.
curl -u $API_KEY_ID:$API_SECRET_KEY https://api.treasuryprime.com/book \\
    -H 'Content-Type: application/json' \\
    -d '{
          "amount": "100.00",
          "from_account_id": "acct_1234567890",
          "to_account_id": "acct_0987654321"
        }'
Upon successful execution, the system returns a Book Transfer object with a status of “pending”. To track when the transfer completes, you’ll need to monitor status updates as described in the next section. 
{
  "to_account_id": "acct_xjwj391iu6rv",
  "description": null,
  "amount": "100.00",
  "bankdata": null,
  "bank_id": "bank_treasuryprime",
  "from_account_id": "acct_7mw05q7wthaq",
  "updated_at": "2021-02-25T01:45:32Z",
  "status": "pending",
  "id": "book_5merj00eudnp",
  "error": null,
  "created_at": "2021-02-25T01:45:32Z",
  "userdata": null
}

​
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 a GET request to the book endpoint with the transfer’s id. The response will contain the Book Transfer object with its current status. 
curl -u $API_KEY_ID:$API_SECRET_KEY https://api.treasuryprime.com/book/:id
Note that the status has changed from “pending” to “sent”. 
{
  "to_account_id": "acct_xjwj391iu6rv",
  "description": null,
  "amount": "100.00",
  "bankdata": null,
  "bank_id": "bank_treasuryprime",
  "from_account_id": "acct_7mw05q7wthaq",
  "updated_at": "2020-05-29T20:57:03Z",
  "status": "sent",
  "id": "book_5merj00eudnp",
  "error": null,
  "created_at": "2020-05-29T20:57:03Z",
  "userdata": null
}

​
Listening For Status Updates with Webhooks

Register a webhook for the book.update event to receive automatic notifications whenever the status of a book transfer changes. 
curl https://api.treasuryprime.com/webhook \\
    -u "$API_KEY_ID:$API_SECRET_KEY" \\
    -H 'Content-Type: application/json' \\
    -d '{
           "event": "book.update",
           "url": "https://example.application.com/notify"
        }'
When you receive a 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. 
{
  "event": "book.update",
  "op": "update",
  "id": "book_1029384756",
  "url": "https://api.treasuryprime.com/book/book_1029384756"
}