Book Transfer

A book transfer is an electronic funds transfer between two accounts at the same bank; such as transferring funds from a checking account to a savings account. While book transfers are the fastest and cheapest type of transfer, they are restricted to accounts held at the same bank.

This guide uses the following endpoints

• /account
• /book
• /webhook

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 have not yet created any bank accounts , this can be accomplished using the apply endpoint.
   • Alternately, a set of accounts are available for testing in the Developer Sandbox.
2. You are authorized to initiate payments between both the source and destination accounts that will be used in the book transfer.

1. Get the Account IDs

The first step in creating a book transfer is to obtain the IDs of the accounts you wish to transfer funds between. To accomplish this, make a GET request to the account endpoint.

curl -u $API_KEY_ID:$API_SECRET_KEY https://api.treasuryprime.com/account

This will return a list of of Account objects. In order to make a book transfer, you will need the account ID for both the sending and receiving accounts, which are stored 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

After obtaining the IDs of the accounts you wish to transfer funds between, you have all the necessary information to make a book transfer. To accomplish this, 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).

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"
        }'

If no errors are encountered, a Book Transfer object is returned. Note that the status of this request is currently set to "pending". To find out when the transfer is complete requires watching for status updates which will be covered next.

{
  "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 find out when the status of the book transfer has changed:

Manually Checking for Status Updates

The status for a book transfer can be checked by making a GET request to the book endpoint and passing in the id of the book transfer. This will return a Book Transfer object with the latest status.

curl -u $API_KEY_ID:$API_SECRET_KEY https://api.treasuryprime.com/book/:id

Note that the status has been changed 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

By registering a webhook to respond to the book.update event, you can be notified of changes in the status of the book transfer when they occur.

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"
        }'

Once the book.update webhook notification is received, follow the steps outlined above to obtain the latest status of the transfer, or simply make a GET request to the URL specified in the url property of the data object.

{
  "event": "book.update",
  "op": "update",
  "id": "book_1029384756",
  "url": "https://api.treasuryprime.com/book/book_1029384756"
}