Wallets

On the Flowbrite platform, wallets contain the funds held for each client in each currency.

Overview

Clients can have up to one wallet per currency. They can be used in the following ways:

To accept payments via collection accounts or funds via linked funding accounts.
To convert funds between wallets of different currencies using conversions.
To withdraw funds or send money to a beneficiary using payments.

Collection Accounts

Collection accounts are external banking details issued by Flowbrite that enable clients to accept payments into a wallet. They can be used to receive funds from various sources, such as bank transfers from themselves or clients, or settlements from card processors.

Collection accounts with local routing details are available in the following currencies:

GBP (British Pound)
EUR (Euro)
USD (US Dollar)
CAD (Canadian Dollar)

All other currencies are accepted via an international multi-currency collection account located in the UK using BIC and IBAN details.

Linked Funding Accounts

Linked funding accounts are bank accounts held by a client at another institution that have been linked to a wallet to allow funds to be automatically moved from that account into the wallet. This is useful for clients who want to automate funding their wallets.

Linked funding accounts can be used to fund wallets in the following currencies:

USD (US Dollar) using ACH Pull

Create a Wallet

POST/v1/wallets

Create a currency wallet with attached collection accounts for the authenticated client. This endpoint requires the X-IDEMPOTENCY-KEY header.

Please refer to the Idempotency Guide for more information.

Request Body

Name
ccyCode
Type
string
Required
Type
Description
The 3-letter ISO currency code for the wallet to create.

Request

POST

/v1/wallets

  curl -X POST https://api.flowbrite.io/v1/wallets \
  -H "X-API-KEY: {api_key}" \
  -H "X-IDEMPOTENCY-KEY: {idempotency_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "ccyCode": "EUR"
  }'

Responses

200 - OK

400 - Bad Request

Response Body

Name
data
Type
object
Type
Description
Show data properties

Example Responses

{
  "data": {
    "id": "wal_X01JTK7M2302PHR2GPKN0SRQYB2",
    "client": {
      "id": "cli_D01JTK7H3SZEEP3KVHA1ZFFRYDD",
      "name": "George Goodchild"
    },
    "ccyCode": "EUR",
    "balance": {
      "ccyCode": "EUR",
      "value": 0.00
    },
    "pendingBalance": {
      "ccyCode": "EUR",
      "value": 0.00
    },
    "isFavourite": false,
    "collectionAccounts": [],
    "linkedFundingAccounts": []
  }
}

View a Wallet

GET/v1/wallets/{idOrCcyCode}

Retrieve a wallet along with its collection accounts and linked funding accounts. The {idOrCcyCode} path parameter accepts either a wallet ID (e.g. wal_...) or a 3-letter ISO currency code (e.g. GBP).

Path Parameters

Name
idOrCcyCode
Type
string
Required
Type
Description
The unique ID of the wallet, or a 3-letter ISO currency code.

Request

GET

/v1/wallets/{idOrCcyCode}

  curl -G https://api.flowbrite.io/v1/wallets/{idOrCcyCode} \
  -H "X-API-KEY: {api_key}"

Responses

200 - OK

400 - Bad Request

404 - Not Found

Response Body

Name
data
Type
object
Type
Description
Show data properties

Example Responses

{
  "data": {
    "id": "wal_D01JTK7M1N8PVQJS387BB6RD885",
    "client": {
      "id": "cli_D01JTK7H3SZEEP3KVHA1ZFFRYDD",
      "name": "George Goodchild"
    },
    "ccyCode": "GBP",
    "balance": {
      "ccyCode": "GBP",
      "value": 123.45
    },
    "pendingBalance": {
      "ccyCode": "GBP",
      "value": 25.00
    },
    "isFavourite": true,
    "collectionAccounts": [
      {
        "id": "ca_D01JTK7P3WS787Q6H5C47PM2N66",
        "ccyCode": "GBP",
        "accountNumber": "01234567",
        "accountNumberType": "ACCOUNT_NUMBER",
        "accountHolderName": "George Goodchild",
        "bankName": "The Currency Cloud Limited",
        "bankAddress": [
          "12 Steward Street",
          "The Steward Building",
          "London",
          "E1 6FQ",
          "GB"
        ],
        "bankCountryCode": "GB",
        "paymentType": "REGULAR",
        "routingCode": "041404",
        "routingCodeType": "SORT_CODE"
      },
      {
        "id": "ca_D01JTK7P3X1YBGZWSV0V0SZJHDR",
        "ccyCode": "GBP",
        "accountNumber": "GB36TCCL12345678901234",
        "accountNumberType": "IBAN",
        "accountHolderName": "George Goodchild",
        "bankName": "The Currency Cloud Limited",
        "bankAddress": [
          "12 Steward Street",
          "The Steward Building",
          "London",
          "E1 6FQ",
          "GB"
        ],
        "bankCountryCode": "GB",
        "paymentType": "PRIORITY",
        "routingCode": "TCCLGB3L",
        "routingCodeType": "BIC_SWIFT"
      }
    ],
    "linkedFundingAccounts": []
  }
}

Search Wallets

GET/v1/wallets

Search for any wallets that match the specified criteria.

Please refer to the Search Guide for information on how to construct queries.

Wallet objects returned from this endpoint do not include full collection account or linked funding account details.

Search Parameters

It is possible to search for wallets by the following fields. Please refer to the data object definition in the Response Body below for details on each field.

Show search fields

Request

GET

/v1/wallets

  curl -G https://api.flowbrite.io/v1/wallets \
  -H "X-API-KEY: {api_key}" \
  -d 'q=balance.value>="0"' \
  -d "sortBy=ccyCode:ASC" \
  -d "offset=0" \
  -d "limit=10"

Responses

200 - OK

400 - Bad Request

Response Body

Name
data
Type
object[]
This is an array
Type
Description
Show data properties
Name
meta
Type
object
Type
Description
Metadata about the wallet search results.
Show meta properties

Example Responses

{
  "data": [
    {
      "id": "wal_D01JTK7M1N8PVQJS387BB6RD885",
      "ccyCode": "GBP",
      "balance": {
        "ccyCode": "GBP",
        "value": 123.56
      },
      "pendingBalance": {
        "ccyCode": "GBP",
        "value": 0.00
      },
      "isFavourite": true,
      "collectionAccounts": []
    },
    {
      "id": "wal_D01JTK7M1PYPY45W4JHG0R5EY2N",
      "ccyCode": "USD",
      "balance": {
        "ccyCode": "USD",
        "value": 678.9
      },
      "pendingBalance": {
        "ccyCode": "USD",
        "value": 15.25
      },
      "isFavourite": false,
      "collectionAccounts": []
    },
    {
      "id": "wal_D01JTK7M2302PHR2GPKN0SRQYB2",
      "ccyCode": "CHF",
      "balance": {
        "ccyCode": "CHF",
        "value": 456.78
      },
      "pendingBalance": {
        "ccyCode": "CHF",
        "value": 0.00
      },
      "isFavourite": false,
      "collectionAccounts": []
    }
  ],
  "meta": {
    "query": "[None]",
    "sortBy": ["ccyCode:ASC"],
    "offset": 0,
    "limit": 10,
    "count": 3,
    "totalCount": 3,
    "timestamp": "2025-06-05T09:27:19.4135893Z"
  }
}

Update Wallet Settings

PUT/v1/wallets/{id}/settings

Update settings for a wallet. This endpoint requires the X-IDEMPOTENCY-KEY header.

Please refer to the Idempotency Guide for more information.

Path Parameters

Name
id
Type
string
Required
Type
Description
The unique ID of the wallet.

Request Body

Name
isFavourite
Type
boolean
Type
Description
Whether the wallet should be marked as a favourite.

Request

PUT

/v1/wallets/{id}/settings

  curl -X PUT https://api.flowbrite.io/v1/wallets/{id}/settings \
  -H "X-API-KEY: {api_key}" \
  -H "X-IDEMPOTENCY-KEY: {idempotency_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "isFavourite": true
  }'

Responses

200 - OK

400 - Bad Request

404 - Not Found

Response Body

Name
data
Type
object
Type
Description
Show data properties

Example Responses

{
  "data": {
    "id": "wal_D01JTK7M1N8PVQJS387BB6RD885",
    "client": {
      "id": "cli_D01JTK7H3SZEEP3KVHA1ZFFRYDD",
      "name": "George Goodchild"
    },
    "ccyCode": "GBP",
    "balance": {
      "ccyCode": "GBP",
      "value": 123.45
    },
    "pendingBalance": {
      "ccyCode": "GBP",
      "value": 25.00
    },
    "isFavourite": true,
    "collectionAccounts": [],
    "linkedFundingAccounts": []
  }
}