API
Balance
A balance account: create, list, get or remove one, convert or move money between balances, and get total funds.
Operations
Every route this entity exposes. Each route links to its own reference on this page.
| Method | Route | SDK operation | Returns |
|---|---|---|---|
POST |
/profiles/{profileId}/balances/hold-limit-breach/{holdLimitBreachId} |
create |
Returns 204 No Content on success |
POST |
/profiles/{profileId}/balance-movements |
create |
Created - Movement completed successfully |
POST |
/profiles/{profileId}/balances |
create |
Created - Balance successfully created |
GET |
/profiles/{profileId}/balances |
list |
OK - Successfully retrieved balances |
GET |
/profiles/{profileId}/total-funds/{currency} |
load |
OK - Successfully retrieved total funds |
GET |
/profiles/{profileId}/balances/{balanceId} |
load |
OK - Successfully retrieved the balance |
DELETE |
/profiles/{profileId}/balances/{balanceId} |
remove |
No Content - Balance successfully removed |
Examples
One example per SDK, generated from the API model. The argument names are the parameters and fields of this entity, and the values are placeholders. The examples are not compiled or executed.
Golang
Construct client as shown in the Golang setup, then call the operations:
balances, err := client.Balance(nil).List(map[string]any{"profile_id": 1, "type": "example"}, nil)
if err != nil {
panic(err)
}
fmt.Println(balances)
balance, err := client.Balance(nil).Load(map[string]any{"currency": "example", "profile_id": 1}, nil)
if err != nil {
panic(err)
}
fmt.Println(balance)
created, err := client.Balance(nil).Create(map[string]any{"profile_id": 1, "currency": "example", "state": "example", "targetRecipientId": 1, "type": "example"}, nil)
if err != nil {
panic(err)
}
fmt.Println(created)
removed, err := client.Balance(nil).Remove(map[string]any{"id": 1, "profile_id": 1}, nil)
if err != nil {
panic(err)
}
fmt.Println(removed)
Lua
Construct client as shown in the Lua setup, then call the operations:
local balances, err = client:Balance():list({ profile_id = 1, type = "example" })
local balance, err = client:Balance():load({ currency = "example", profile_id = 1 })
local created, err = client:Balance():create({ profile_id = 1, currency = "example", state = "example", targetRecipientId = 1, type = "example" })
local removed, err = client:Balance():remove({ id = 1, profile_id = 1 })
PHP
Construct client as shown in the PHP setup, then call the operations:
$balances = $client->Balance()->list(["profile_id" => 1, "type" => "example"]);
$balance = $client->Balance()->load(["currency" => "example", "profile_id" => 1]);
$created = $client->Balance()->create(["profile_id" => 1, "currency" => "example", "state" => "example", "targetRecipientId" => 1, "type" => "example"]);
$client->Balance()->remove(["id" => 1, "profile_id" => 1]);
Python
Construct client as shown in the Python setup, then call the operations:
balances = client.Balance().list({"profile_id": 1, "type": "example"})
balance = client.Balance().load({"currency": "example", "profile_id": 1})
created = client.Balance().create({ "profile_id": 1, "currency": "example", "state": "example", "targetRecipientId": 1, "type": "example" })
client.Balance().remove({"id": 1, "profile_id": 1})
Ruby
Construct client as shown in the Ruby setup, then call the operations:
balances = client.Balance.list({ "profile_id" => 1, "type" => "example" })
balance = client.Balance.load({ "currency" => "example", "profile_id" => 1 })
created = client.Balance.create({ "profile_id" => 1, "currency" => "example", "state" => "example", "targetRecipientId" => 1, "type" => "example" })
client.Balance.remove({ "id" => 1, "profile_id" => 1 })
TypeScript
Construct client as shown in the TypeScript setup, then call the operations:
const balances = await client.Balance().list({ profile_id: 1, type: "example" })
const balance = await client.Balance().load({ currency: "example", profile_id: 1 })
const created = await client.Balance().create({ profile_id: 1, currency: "example", state: "example", targetRecipientId: 1, type: "example" })
await client.Balance().remove({ id: 1, profile_id: 1 })
Fields
| Field | Type | Required | Description |
|---|---|---|---|
amount |
object |
No | Available balance that can be used to fund transfers. |
cashAmount |
object |
No | Cash amount in the account. |
creationTime |
string |
No | Date when the balance was created. |
currency |
string |
No | Currency code (ISO 4217 Alphabetic Code). |
icon |
one,object,null |
No | Icon for the balance. |
id |
integer |
No | Balance ID. |
investmentState |
string |
No | Investment state of the balance. |
modificationTime |
string |
No | Date when the balance was last modified. |
name |
one,string,null |
No | Name of the balance. |
overdraft |
object |
No | Overdraft details for the account. |
reservedAmount |
object |
No | Amount reserved for transactions. |
state |
string |
Yes | Must be CLOSED. |
targetRecipientId |
integer |
Yes | ID of the recipient to receive the refund of the excess funds. |
totalAvailable |
object |
No | Total available balance, which is the sum of cash ledger balance and any approved overdraft limit. |
totalCash |
object |
No | Total cash balance across all balances, including group balances but excluding asset portfolios. |
totalWorth |
object |
No | Total worth of the account, including cash ledger balance and valuation of any asset portfolio if invested. |
type |
string |
No | Type of balance account. |
visible |
boolean |
No | Whether the balance is visible to the user. |
create
POST /profiles/{profileId}/balances/hold-limit-breach/{holdLimitBreachId}
Operation ID: holdLimitBreachClose.
Authentication: bearer token (UserToken) or bearer token (PersonalToken).
Parameters
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
profileId |
path |
integer (int64) |
Yes | The profile ID. |
holdLimitBreachId |
path |
integer (int64) |
Yes | The hold limit breach ID. |
X-External-Correlation-Id |
header |
string (uuid) |
No | Optional UUID for correlating requests across systems. If provided, Wise echoes it back in the response. Maximum 36 characters. Learn more. |
Request body
application/json
| Property | Type | Required | Description |
|---|---|---|---|
state |
string |
Yes | Must be CLOSED. This is the only supported value. |
targetRecipientId |
integer |
Yes | ID of the recipient to receive the refund of the excess funds. |
Responses
204: Returns 204 No Content on success
400: Invalid state used
application/json
| Property | Type | Required | Description |
|---|---|---|---|
errors |
array of object |
No | A list of specific validation failures. |
errors[].code |
string |
No | A specific code for the validation failure type. |
errors[].detail |
string |
No | A detailed description of the validation failure. |
errors[].ref |
string |
No | A reference to the field that failed validation. |
instance |
string |
No | The uri that triggered the error |
status |
string |
No | Bad request error |
title |
string |
No | Validation Error |
type |
string (uri-reference) |
No | Must be /errors/types/validation for this error type |
403: Caller attempts to close a holdLimitBreach that does not belong to them
application/json
| Property | Type | Required | Description |
|---|---|---|---|
code |
string |
No | Error code of the request |
detail |
string |
No | Detail of the error |
instance |
string |
No | The uri that triggered the error |
status |
string |
No | Forbidden error |
title |
string |
No | Forbidden |
type |
string (uri-reference) |
No | Must be /errors/types/access for this error type |
404: Caller attempts to close a holdLimitBreach that does not exist
application/json
| Property | Type | Required | Description |
|---|---|---|---|
code |
string |
No | Error code of the request |
detail |
string |
No | Detail of the error |
instance |
string |
No | The uri that triggered the error |
status |
string |
No | Validation error |
title |
string |
No | Validation Error |
type |
string (uri-reference) |
No | Must be /errors/types/validation for this error type |
429: Rate limit exceeded. Retry after the number of seconds specified in the Retry-After header
application/json
The response is object.
POST /profiles/{profileId}/balance-movements
Operation ID: balanceMovement.
Authentication: bearer token (UserToken) or bearer token (PersonalToken).
Parameters
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
profileId |
path |
integer (int64) |
Yes | The profile ID. |
X-idempotence-uuid |
header |
string (uuid) |
Yes | Unique identifier assigned by you. Used for idempotency check purposes. Should your call fail for technical reasons then you can use the same value again for making a retry call. |
X-External-Correlation-Id |
header |
string (uuid) |
No | Optional UUID for correlating requests across systems. If provided, Wise echoes it back in the response. Maximum 36 characters. Learn more. |
Request body
application/json
| Property | Type | Required | Description |
|---|---|---|---|
amount |
object |
No | Amount to move. Required for same-currency movements. Either amount or quoteId must be provided. |
amount.currency |
string |
No | Currency code (ISO 4217 Alphabetic Code). |
amount.value |
number |
No | Amount value. |
quoteId |
string (uuid) |
No | Quote ID. Required for cross-currency movements. Quote must be created with payOut: BALANCE. |
sourceBalanceId |
integer (int64) |
No | Source balance ID. Required when moving between balances (with targetBalanceId). |
targetBalanceId |
integer (int64) |
No | Target balance ID. Required when moving between balances (with sourceBalanceId). |
Responses
201: Created - Movement completed successfully
application/json
| Property | Type | Required | Description |
|---|---|---|---|
balancesAfter |
array of object |
No | Balance states after the movement. |
balancesAfter[].currency |
string |
No | Currency code. |
balancesAfter[].id |
integer (int64) |
No | Balance ID. |
balancesAfter[].value |
number |
No | Balance value after movement. |
creationTime |
string (date-time) |
No | When the movement was created. |
feeAmounts |
array of object |
No | Fee amounts charged for the movement. |
feeAmounts[].currency |
string |
No | |
feeAmounts[].value |
number |
No | |
id |
integer (int64) |
No | Movement transaction ID. |
rate |
number |
No | Exchange rate applied to the conversion. |
sourceAmount |
object |
No | Source amount of the movement. |
sourceAmount.currency |
string |
No | |
sourceAmount.value |
number |
No | |
state |
enum: PENDING, COMPLETED, CANCELLED, REVERSED |
No | State of the movement. |
steps |
array of object |
No | Steps involved in the movement. |
steps[].balancesAfter |
array of object |
No | |
steps[].balancesAfter[].currency |
string |
No | |
steps[].balancesAfter[].value |
number |
No | |
steps[].creationTime |
string (date-time) |
No | When the step was created. |
steps[].fee |
object |
No | |
steps[].fee.currency |
string |
No | |
steps[].fee.value |
number |
No | |
steps[].id |
integer (int64) |
No | Step ID. |
steps[].rate |
number |
No | Exchange rate applied. |
steps[].sourceAmount |
object |
No | |
steps[].sourceAmount.currency |
string |
No | |
steps[].sourceAmount.value |
number |
No | |
steps[].targetAmount |
object |
No | |
steps[].targetAmount.currency |
string |
No | |
steps[].targetAmount.value |
number |
No | |
steps[].type |
string |
No | Step type. |
targetAmount |
object |
No | Target amount of the movement. |
targetAmount.currency |
string |
No | |
targetAmount.value |
number |
No | |
type |
enum: DEPOSIT, WITHDRAWAL, CONVERSION |
No | Type of movement. |
429: Rate limit exceeded. Retry after the number of seconds specified in the Retry-After header
application/json
The response is object.
POST /profiles/{profileId}/balances
Operation ID: balanceCreate.
Authentication: bearer token (UserToken) or bearer token (PersonalToken).
Parameters
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
profileId |
path |
integer (int64) |
Yes | The profile ID. |
X-idempotence-uuid |
header |
string (uuid) |
Yes | Unique identifier assigned by you. Used for idempotency check purposes. Should your call fail for technical reasons then you can use the same value again for making a retry call. |
X-External-Correlation-Id |
header |
string (uuid) |
No | Optional UUID for correlating requests across systems. If provided, Wise echoes it back in the response. Maximum 36 characters. Learn more. |
Request body
application/json
| Property | Type | Required | Description |
|---|---|---|---|
currency |
string |
Yes | Currency code (ISO 4217 Alphabetic Code). |
name |
string |
No | Name of the balance. Required for SAVINGS type balances. |
type |
enum: STANDARD, SAVINGS |
Yes | Type of balance account. - STANDARD - Standard balance account. Only one per currency per profile. - SAVINGS - Savings balance (Jar). Multiple allowed per currency. |
Example request body:
{
"currency": "EUR",
"type": "STANDARD"
}
Responses
201: Created - Balance successfully created
application/json
| Property | Type | Required | Description |
|---|---|---|---|
amount |
object |
No | Available balance that can be used to fund transfers. |
amount.currency |
string |
No | Currency code (ISO 4217 Alphabetic Code). |
amount.value |
number |
No | Amount value. |
cashAmount |
object |
No | Cash amount in the account. |
cashAmount.currency |
string |
No | Currency code (ISO 4217 Alphabetic Code). |
cashAmount.value |
number |
No | Amount value. |
creationTime |
string (date-time) |
No | Date when the balance was created. |
currency |
string |
No | Currency code (ISO 4217 Alphabetic Code). |
icon |
object,null |
No | Icon for the balance. |
icon.type |
enum: EMOJI |
No | Icon type. |
icon.value |
string |
No | Icon value (for example, emoji character). |
id |
integer (int64) |
No | Balance ID. |
investmentState |
enum: NOT_INVESTED, INVESTED, INVESTING, DIVESTING, UNKNOWN |
No | Investment state of the balance. - NOT_INVESTED - Balance is not invested. - INVESTED - Balance is invested in assets. - INVESTING - Balance is being invested into assets. - DIVESTING - Balance is being divested from assets. - UNKNOWN - Investment state is unknown. |
modificationTime |
string (date-time) |
No | Date when the balance was last modified. |
name |
string,null |
No | Name of the balance. Required for SAVINGS balances. |
reservedAmount |
object |
No | Amount reserved for transactions. |
reservedAmount.currency |
string |
No | Currency code (ISO 4217 Alphabetic Code). |
reservedAmount.value |
number |
No | Amount value. |
totalWorth |
object |
No | Current total worth. |
totalWorth.currency |
string |
No | Currency code (ISO 4217 Alphabetic Code). |
totalWorth.value |
number |
No | Amount value. |
type |
enum: STANDARD, SAVINGS |
No | Type of balance account. - STANDARD - Standard balance account. Only one per currency per profile. - SAVINGS - Savings balance (Jar). Multiple allowed per currency. |
visible |
boolean |
No | Whether the balance is visible to the user. |
429: Rate limit exceeded. Retry after the number of seconds specified in the Retry-After header
application/json
The response is object.
list
GET /profiles/{profileId}/balances
Operation ID: balanceList.
Authentication: bearer token (UserToken) or bearer token (PersonalToken).
Parameters
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
profileId |
path |
integer (int64) |
Yes | The profile ID. |
types |
query |
string |
Yes | Comma-separated list of balance types to return. Acceptable values are STANDARD and SAVINGS. |
X-External-Correlation-Id |
header |
string (uuid) |
No | Optional UUID for correlating requests across systems. If provided, Wise echoes it back in the response. Maximum 36 characters. Learn more. |
Responses
200: OK - Successfully retrieved balances
application/json
| Property | Type | Required | Description |
|---|---|---|---|
[].amount |
object |
No | Available balance that can be used to fund transfers. |
[].amount.currency |
string |
No | Currency code (ISO 4217 Alphabetic Code). |
[].amount.value |
number |
No | Amount value. |
[].cashAmount |
object |
No | Cash amount in the account. |
[].cashAmount.currency |
string |
No | Currency code (ISO 4217 Alphabetic Code). |
[].cashAmount.value |
number |
No | Amount value. |
[].creationTime |
string (date-time) |
No | Date when the balance was created. |
[].currency |
string |
No | Currency code (ISO 4217 Alphabetic Code). |
[].icon |
object,null |
No | Icon for the balance. |
[].icon.type |
enum: EMOJI |
No | Icon type. |
[].icon.value |
string |
No | Icon value (for example, emoji character). |
[].id |
integer (int64) |
No | Balance ID. |
[].investmentState |
enum: NOT_INVESTED, INVESTED, INVESTING, DIVESTING, UNKNOWN |
No | Investment state of the balance. - NOT_INVESTED - Balance is not invested. - INVESTED - Balance is invested in assets. - INVESTING - Balance is being invested into assets. - DIVESTING - Balance is being divested from assets. - UNKNOWN - Investment state is unknown. |
[].modificationTime |
string (date-time) |
No | Date when the balance was last modified. |
[].name |
string,null |
No | Name of the balance. Required for SAVINGS balances. |
[].reservedAmount |
object |
No | Amount reserved for transactions. |
[].reservedAmount.currency |
string |
No | Currency code (ISO 4217 Alphabetic Code). |
[].reservedAmount.value |
number |
No | Amount value. |
[].totalWorth |
object |
No | Current total worth. |
[].totalWorth.currency |
string |
No | Currency code (ISO 4217 Alphabetic Code). |
[].totalWorth.value |
number |
No | Amount value. |
[].type |
enum: STANDARD, SAVINGS |
No | Type of balance account. - STANDARD - Standard balance account. Only one per currency per profile. - SAVINGS - Savings balance (Jar). Multiple allowed per currency. |
[].visible |
boolean |
No | Whether the balance is visible to the user. |
429: Rate limit exceeded. Retry after the number of seconds specified in the Retry-After header
application/json
The response is object.
load
GET /profiles/{profileId}/total-funds/{currency}
Operation ID: totalFunds.
Authentication: bearer token (UserToken) or bearer token (PersonalToken).
Parameters
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
profileId |
path |
integer (int64) |
Yes | The profile ID. |
currency |
path |
string |
Yes | Currency code (ISO 4217 Alphabetic Code). All values will be converted to this currency. |
X-External-Correlation-Id |
header |
string (uuid) |
No | Optional UUID for correlating requests across systems. If provided, Wise echoes it back in the response. Maximum 36 characters. Learn more. |
Responses
200: OK - Successfully retrieved total funds
application/json
| Property | Type | Required | Description |
|---|---|---|---|
overdraft |
object |
No | Overdraft details for the account. |
overdraft.available |
object |
No | Amount of overdraft currently available (limit minus used). |
overdraft.available.currency |
string |
No | Currency code (ISO 4217 Alphabetic Code). |
overdraft.available.value |
number |
No | Amount value. |
overdraft.availableByCurrency |
array of object |
No | Available overdraft amounts converted to each currency the customer has a balance in. |
overdraft.availableByCurrency[].currency |
string |
No | Currency code (ISO 4217 Alphabetic Code). |
overdraft.availableByCurrency[].value |
number |
No | Amount value. |
overdraft.limit |
object |
No | Maximum overdraft available through an overdraft program. Zero if no approved overdraft. |
overdraft.limit.currency |
string |
No | Currency code (ISO 4217 Alphabetic Code). |
overdraft.limit.value |
number |
No | Amount value. |
overdraft.used |
object |
No | Portion of the approved overdraft limit currently being utilized. |
overdraft.used.currency |
string |
No | Currency code (ISO 4217 Alphabetic Code). |
overdraft.used.value |
number |
No | Amount value. |
totalAvailable |
object |
No | Total available balance, which is the sum of cash ledger balance and any approved overdraft limit. |
totalAvailable.currency |
string |
No | Currency code (ISO 4217 Alphabetic Code). |
totalAvailable.value |
number |
No | Amount value. |
totalCash |
object |
No | Total cash balance across all balances, including group balances but excluding asset portfolios. |
totalCash.currency |
string |
No | Currency code (ISO 4217 Alphabetic Code). |
totalCash.value |
number |
No | Amount value. |
totalWorth |
object |
No | Total worth of the account, including cash ledger balance and valuation of any asset portfolio if invested. |
totalWorth.currency |
string |
No | Currency code (ISO 4217 Alphabetic Code). |
totalWorth.value |
number |
No | Amount value. |
429: Rate limit exceeded. Retry after the number of seconds specified in the Retry-After header
application/json
The response is object.
GET /profiles/{profileId}/balances/{balanceId}
Operation ID: balanceGet.
Authentication: bearer token (UserToken) or bearer token (PersonalToken).
Parameters
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
profileId |
path |
integer (int64) |
Yes | The profile ID. |
balanceId |
path |
integer (int64) |
Yes | The balance ID. |
X-External-Correlation-Id |
header |
string (uuid) |
No | Optional UUID for correlating requests across systems. If provided, Wise echoes it back in the response. Maximum 36 characters. Learn more. |
Responses
200: OK - Successfully retrieved the balance
application/json
| Property | Type | Required | Description |
|---|---|---|---|
amount |
object |
No | Available balance that can be used to fund transfers. |
amount.currency |
string |
No | Currency code (ISO 4217 Alphabetic Code). |
amount.value |
number |
No | Amount value. |
cashAmount |
object |
No | Cash amount in the account. |
cashAmount.currency |
string |
No | Currency code (ISO 4217 Alphabetic Code). |
cashAmount.value |
number |
No | Amount value. |
creationTime |
string (date-time) |
No | Date when the balance was created. |
currency |
string |
No | Currency code (ISO 4217 Alphabetic Code). |
icon |
object,null |
No | Icon for the balance. |
icon.type |
enum: EMOJI |
No | Icon type. |
icon.value |
string |
No | Icon value (for example, emoji character). |
id |
integer (int64) |
No | Balance ID. |
investmentState |
enum: NOT_INVESTED, INVESTED, INVESTING, DIVESTING, UNKNOWN |
No | Investment state of the balance. - NOT_INVESTED - Balance is not invested. - INVESTED - Balance is invested in assets. - INVESTING - Balance is being invested into assets. - DIVESTING - Balance is being divested from assets. - UNKNOWN - Investment state is unknown. |
modificationTime |
string (date-time) |
No | Date when the balance was last modified. |
name |
string,null |
No | Name of the balance. Required for SAVINGS balances. |
reservedAmount |
object |
No | Amount reserved for transactions. |
reservedAmount.currency |
string |
No | Currency code (ISO 4217 Alphabetic Code). |
reservedAmount.value |
number |
No | Amount value. |
totalWorth |
object |
No | Current total worth. |
totalWorth.currency |
string |
No | Currency code (ISO 4217 Alphabetic Code). |
totalWorth.value |
number |
No | Amount value. |
type |
enum: STANDARD, SAVINGS |
No | Type of balance account. - STANDARD - Standard balance account. Only one per currency per profile. - SAVINGS - Savings balance (Jar). Multiple allowed per currency. |
visible |
boolean |
No | Whether the balance is visible to the user. |
429: Rate limit exceeded. Retry after the number of seconds specified in the Retry-After header
application/json
The response is object.
remove
DELETE /profiles/{profileId}/balances/{balanceId}
Operation ID: balanceDelete.
Authentication: bearer token (UserToken) or bearer token (PersonalToken).
Parameters
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
profileId |
path |
integer (int64) |
Yes | The profile ID. |
balanceId |
path |
integer (int64) |
Yes | The balance ID. |
X-External-Correlation-Id |
header |
string (uuid) |
No | Optional UUID for correlating requests across systems. If provided, Wise echoes it back in the response. Maximum 36 characters. Learn more. |
Responses
204: No Content - Balance successfully removed
429: Rate limit exceeded. Retry after the number of seconds specified in the Retry-After header
application/json
The response is object.