Overview

These APIs are designed to be familiar and easy to work with. They are designed around the principles of REST, meaning that they use HTTP and rely on HTTP's built-in features. They use resource-oriented URLs and HTTP verbs, response codes, and authentication. Request and response bodies are encoded as JSON data.

Live and Test Environments

Treasury Prime API is available in two separate environments. There is a live (production) environment, and a test (sandbox) environment. Requests made to the sandbox environment will never hit banking networks,
meaning they can't affect your account balances and will never incur costs.

Production:    https://api.treasuryprime.com
Sandbox:       https://api.sandbox.treasuryprime.com

Your developer account will have different API keys for each environment. Each environment has its own URL endpoint to avoid any confusion.

Authentication

Your API key is used to authenticate each request. API keys are included in requests using HTTP Basic Auth. Provide your API key ID as the basic auth username value, and the API key value as the password.

Example Request

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

The API is served exclusively over HTTPS so all data stays safe and secure. Any requests made over plain HTTP will fail. Any requests made without authentication will also fail.

🚧

Your API keys are extremely sensitive.

Anyone who gains access to your keys will be able to impersonate you and could take money out of your bank accounts. Never expose your API keys in any publicly accessible areas, including GitHub, client-side code, or even a plain HTTP request. If you are ever in doubt that your API keys may have been exposed, contact us immediately!

Ledger & Core Direct Products

These pages document the Treasury Prime Ledger Product.

Treasury Prime offers two similar API products depending on the underlying core/ledger.

• Core Direct: Bank accounts are direct banking core accounts. These are the exact same accounts that are created if you walk into a branch to create a bank account.

• Treasury Prime Ledger: Bank accounts are held in the Treasury Prime ledger and all interaction with the account is done using this API.

The two products have slightly different behaviors and are documented separately.

Please note that Treasury Prime has real-time connections to the cores of each partner bank. Real-time access is essential to move money safely and all our of systems use these low level connections regardless of the product.

You may also view the Core Direct documentation.

Testing in Sandbox

Before going live you should get familiar with our APIs and test your integration in sandbox. First, you will need to create a sandbox account, and generate your API keys in the Developer Dashboard. Then you can do your testing as in command line or using our Postman Collection to speed up your initial exploration of our APIs.

See our Testing section to learn more about testing in our sandbox environment.

Health Check

A health check can be performed on the API calling the /ping endpoint.

Definition

GET https://api.treasuryprime.com/ping

Returns an HTTP status 200 if the API is available.

Example Request

$ curl -u "$API_KEY_ID:$API_KEY_VALUE" https://api.treasuryprime.com/ping

Example Response

{
    "api_version": "1",
    "version": "1.10.165-g284f828c",
    "time": "2020-12-08T06:27:07.204Z"
}

Idempotency

The API has support for idempotent requests. When you send a request with the idempotency key set, the server will ensure that the request will only be processed once, no matter how many times the request is sent or received. This is useful in preventing duplicate operations in the face of errors or network disruption.

The idempotency key itself may be any arbitrary string. Because the server identifies each unique request by a unique idempotency key, be sure to choose a string that will not be reused in subsequent requests. Choosing a large random string, such as a UUID, is a good idea.

To make a request idempotent, generate an idempotency key and send it in the X-Idempotency-Key header.

Example Request

$ curl https://api.treasuryprime.com/ach \
    -u "$API_KEY_ID:$API_KEY_VALUE" \
    -H "X-Idempotency-Key: $RANDOM_STRING" \
    -H 'Content-Type: application/json' \
    -d '{
          "account_id": "acct_123456",
          "amount": "100.00",
          "counterparty_id": "cp_098765",
          "direction": "credit",
          "sec_code": "ccd"
        }'

Request and Response Payloads

The payloads consumed and produced by the API are strictly JSON encoded data or HTTP query parameters. To reflect this, you must provide application/json in the Content-Type HTTP header for most POST and PUT calls.

Undocumented Fields

Treasury Prime follows the common practice of sometimes returning more JSON fields in the response than are shown in the documentation.

We do not recommend relying on the use of any undocumented fields that are returned in the API. These fields may be under deevelopment or may have restricted use cases that are subject to change.

Filtering

When listing all existing API objects, the returned list appears in reverse chronological order, with the most recently created accounts appearing first. Optional filtering parameters are described below.

Listing and filtering objects

An API may have filterable fields that can be used to refine the listing of all given objects. For example, to find all ACH objects where the status field is set to pending, the corresponding field and value can be filtered using a query string in parameter=value format.

Definition

GET <<API_ENDPOINT>>/$OBJECT_PATH

Returns a list of objects with the optional filtering parameters applied.

Example Request

$ curl https://api.treasuryprime.com/ach?status=pending" \
    -u $API_KEY_ID:$API_KEY_VALUE

Example Response

{
    "data": [
        {
            "account_id": "acct_123",
            "amount": "10.00",
            "counterparty_id": "cp_123",
            "created_at": "2018-10-30T23:57:11Z",
            "description": null,
            "direction": "credit",
            "effective_date": "2018-10-30T23:57:11Z",
            "id": "ach_1234567890",
            "sec_code": "ccd",
            "service": "standard",
            "status": "pending",
            "updated_at": "2018-10-30T23:57:11Z",
            "userdata": null
        },
        {
            "account_id": "acct_456",
            "amount": "1.00",
            "counterparty_id": "cp_456",
            "created_at": "2018-10-30T23:57:09Z",
            "description": null,
            "direction": "credit",
            "effective_date": "2018-10-30T23:57:09Z",
            "id": "ach_1234567891",
            "sec_code": "ccd",
            "service": "standard",
            "status": "pending",
            "updated_at": "2018-10-30T23:57:09Z",
            "userdata": null
        }
    ],
    "page_next": "https://api.treasuryprime.com/ach?page_cursor=acct_456"
}

Pagination

When listing all existing API objects, the returned list appears in reverse chronological order, with the most recently created accounts appearing first. Optional pagination parameters are described below.

Definition

GET https://api.treasuryprime.com/$OBJECT_PATH

Returns a list of objects with the optional pagination parameters applied.

Example Request

$ curl "https://api.treasuryprime.com/counterparty?page_size=2&page_cursor=cp_10" \
    -u $API_KEY_ID:$API_KEY_VALUE

Example Response

{
    "data": [
        {
          "ach": {
            "account_number": "64141601",
            "account_type": "checking",
            "routing_number": "021001208"
          },
          "created_at": "2018-10-30T22:30:09Z",
          "id": "cp_9",
          "name": "John Smith",
          "updated_at": "2018-10-30T22:30:09Z",
          "userdata": null,
          "wire": null
        },
        {
          "ach": {
            "account_number": "54545454",
            "account_type": "checking",
            "routing_number": "021001208"
          },
          "created_at": "2018-10-30T22:20:09Z",
          "id": "cp_8",
          "name": "Jane Doe",
          "updated_at": "2018-10-30T22:20:09Z",
          "userdata": null,
          "wire": null
        }
    ],
    "page_next": "https://api.treasuryprime.com/counterparty?page_cursor=cp_8"
}

User Data

All API resources have a field where you can attach arbitrary data. We refer to this arbitrary data as "user data," and you can access it via the userdata parameter.

User data is useful for storing additional, structured data along side an API object. For example, you may wish to store an ID or key that correlates an API object with a unique ID in your own application or database. User data is not used by Treasury Prime and won't be visible to your users (unless you expose it to them in your own application).

You may pass any arbitrary JSON object for userdata. The total size of the object, serialized, must be less than 1KB in size.

Errors

The API uses HTTP response codes to indicate the success or failure of a request. Codes in the 2xx range indicate success, codes in the 4xx range indicate an error in your request, and codes in the 5xx range indicate an error with Treasury Prime's servers or the backing bank systems. In particular, an HTTP 502 error most often indicates that the bank's core system is offline due to maintenance. Any asynchronous actions, such as book transfers, will be completed once the core system is back online. Please note that some API endpoints may return a 429 status code during times of high request volume, your application should be expected to implement some basic backoff and retry logic for this scenario. Some endpoints will return this status code as part of exceeding an account limit though, instances of this will be covered in those endpoints respectively.

In addition to the HTTP response code, most errors also include more detailed information about the problem in the response body. The detailed error message will be encoded in a JSON response under the error key.

Example Response

{
  "error": "Parameter 'amount' must be greater than '0'.
}