Balances

The Balance object provides the amount available on a given Wallet. Each time the balance of the Wallet is updated as a result of a Payin, Payout, or Card Transaction, Treezor sends a balance.update webhook.

There are different kinds of Balances to consider:

• Current Balance – The amount of money currently available on the wallet without considering pending operations.
• Authorizations – Refers to the pending operations amount.
• Authorized Balance – The simulated balance, which amount takes into account pending operations (i.e., authorizations amount is deducted from the balance). This is usually the balance exposed to end users.

In other words, Current Balance = Authorized Balance + Authorizations

You can fetch the Balances value using the /v1/balances request.

Example

Consider a current balance of €500.00 and an authorized payment of €100.00 (i.e., authorizations) that is not yet settled.

In this case, the values will be as follows:

• Current Balance – €500.00
• Authorized Balance – €400.00 (i.e., the balance minus the pending operation).
• Authorizations – €100.00

Balance of a specific Wallet

This checks the current Balance of the Wallet (how much money there is), making sure the funds have arrived. Note that the walletId is expected as a query parameter.

Endpoint: /v1/balances

CURL

curl -X GET '{baseUrl}/v1/balances?walletId={walletId}' \
	--header 'Authorization: Bearer {accessToken}'

Returns the Balance object, with both the Authorized Balance (authorizedBalance) and Balance (currentBalance).

JSON

{
    "balances": [
        {
            "walletId": 1317558,
            "currentBalance": 280,						// Actual Balance
            "authorizations": 0,						// Currently pending authorizations
            "authorizedBalance": 280,					// Balance, minus pending authorizations
            "currency": "EUR",							// Currency of the balance
            "calculationDate": "2022-03-01 15:52:40"	// When the Balance was last actualized
        }
    ]
}

Balances of all Wallets

You can retrieve the Balances of multiple Wallets related to the same User. In this case, you provide a userId instead of a walletId in the query parameters.

Endpoint: /v1/balances

CURL

curl -X GET '{baseUrl}/v1/balances?userId={userId}' \
	--header 'Authorization: Bearer {accessToken}'

Returns the list of Balance of each Wallet belonging to the User.

JSON

{
    "balances": [
        {
            "walletId": 3645800,
            "currentBalance": 4002.5,
            "authorizations": 0,
            "authorizedBalance": 4002.5,
            "currency": "EUR",
            "calculationDate": "2024-12-11 11:06:08"
        },
		{
            "walletId": 3645801,
            "currentBalance": 100,
            "authorizations": 50,
            "authorizedBalance": 50,
            "currency": "EUR",
            "calculationDate": "2024-12-11 11:06:08"
        },
		{
            "walletId": 3645802,
            "currentBalance": 302.5,
            "authorizations": 0,
            "authorizedBalance": 302.5,
            "currency": "EUR",
            "calculationDate": "2024-12-11 11:06:08"
        }
    ]
}

Check the balance history

This checks the evolution of the balance over time. Only the walletId is mandatory, it is expected in the URL. You can optionally restrict the search time frame using the dateFrom and dateTo parameters.

Endpoint: /core-connect/balances/{walletId}

CURL

curl -X GET '{baseUrl}/core-connect/balances/{walletId}?dateFrom=2021-11-01&dateTo=2022-10-01' \
	--header 'Authorization: Bearer {accessToken}'

JSON

{
	"2021-03-31T09:50:02+00:00": {
		"solde": 51.25,             // currentBalance
		"authorizedBalance": 51.25,
		"currency": "EUR"
	},
	"2021-02-04T13:20:02+00:00": {
		"solde": 170.00,            // currentBalance
		"authorizedBalance": 170.00,
		"currency": "EUR"
	},
	// [...] more items are hidden
}

Caution – Date expected format is YYYY-MM-DD

The time frame dates do not follow the standard format and are instead expected as YYYY-MM-DD.