API Overview

This page describes general guidelines for interacting with our Banking API. It focuses on environment configuration, authentication, and global patterns that our API adheres to.

Endpoints

Environment	Endpoint
Sandbox	https://api.test.figurepay.com/
Production	https://api.figurepay.com/

API Version

The Figure Pay Banking API uses calendar-based versioning using the ISO-8601 date standard format (YYYY-MM-DD).

For example, if we release a new version of the API on January 1, 2023, this new version would be called 2023-01-01.

You can choose which version of the API to use by specifying the version using the X-FigurePay-Api-Version header on a request-by-request basis.

API Breaking Changes

A new version of the API will be released when we introduce changes that are not backwards compatible with the current, latest version.

Below are some examples of when a new version is released but are not limited to:

• Removing an endpoint or field
• Changing the name or type of a field
• Changing the path of an endpoint

API consumers should expect that enums are an open set of values and may contain new values at any time. It is highly encouraged that API consumers are able to handle unknown new enum values in their implementation.

API Deprecation & Removal

As we release new versions of the API, older versions will be deprecated and removed at a specific time. When a version is deprecated, API responses will include the Deprecation and Sunset headers.

The Deprecation and Sunset header values are HTTP dates that represents the date of deprecation and date of removal respectively. When a version is removed, requests to that version will respond back with HTTP response code 410 (Gone).

It is recommended that API consumers monitor these headers to be alerted of when a version is deprecated and removed.

Data Types

Timestamps

Most resources carry a created_dt and updated_dt timestamp in addition to any other timestamps relevant to them.

Timestamps are formatted as an RFC-3339 string. Most timestamps are in UTC (including a Z suffix) but time offset can be directly inferred from the value and should not necessarily be assumed.

Amounts

The only currency currently supported by Figure Pay is USD.

All fields representing an amount of currency, from an account balance to a transaction amount are represented as USD Pennies. Amounts are transmitted as an integer JSON numbers and not fractional decimal numbers. For example, if an account has a balance of $100 USD then a response from a balance inquiry would contain amount_coins: 10000.

The amount field is expected to be supplied with the amount in coins. The amount field will contain the unit in the name e.g. amount_coins.

Balance fields will include the unit in the name e.g. balance_coins: 10000 and balance_usd: 100.

Pagination

Endpoints that return a list of items are typically paginated. Paginated endpoints employ a cursor-based pagination strategy by accepting a next_cursor and limit field as part of the request, in addition to any resource-specific filters.

Request Parameters

next_cursor optional, exclusive (refers to the last item in the previous response)

limit optional, default is 100, max is 250

Idempotency

id optional, ensures that any retried API calls don't submit multiple requests successfully

Response Payload

next_cursor to supply in subsequent paginated requests

limit what was supplied in the request or the default that was used

data array containing the actual response elements, in order

{
  "data": [...],
  "limit": 100,
  "next_cursor": "2022-01-01T00:00:00.000000-00:00"
}

Error Responses

Our Banking API returns standard HTTP status codes.

Your client will receive a 4xx HTTP code if our API believes the error originated from the request itself e.g. a 400 Bad Request if the response is malformed or a 404 Not Found if we were unable to located the requested resource.

Your client will receive a 5xx HTTP status code if there's an issue with our API e.g. a 503 Service Unavailable if we're experience system downtime.

Additionally, we provide a JSON response body which provides context for the errors experienced during your request.

400 Bad Request

{
    "errors": [
      { "error": "'name' must not be empty." },
      { "error": "'amount' must be greater than 0." }
    ]
}