Skip to content

Convert or Move Money Between Balances

Request

This endpoint allows conversion and movement of funds between balance accounts.

Convert across balance accounts: Convert funds between two STANDARD balance accounts in different currencies. Requires a quote created with "payOut": "BALANCE".

Move money between balances:

  • Add money to a same-currency jar (move from STANDARD to SAVINGS without conversion)
  • Add money to another-currency jar (convert money using a quote)
  • Withdraw money from a jar (move from SAVINGS to STANDARD without conversion)

Either amount or quoteId is required. Use quoteId for cross-currency movements.

Security
UserToken or PersonalToken
Path
profileIdinteger, (int64)required

The profile ID.

Headers
X-idempotence-uuidstring, (uuid)required

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-Idstring, (uuid), <= 36 characters

Optional UUID for correlating requests across systems. If provided, Wise echoes it back in the response. Maximum 36 characters. Learn more.

Example:f47ac10b-58cc-4372-a567-0e02b2c3d479
Bodyapplication/jsonrequired
quoteIdstring, (uuid)

Quote ID. Required for cross-currency movements. Quote must be created with payOut: BALANCE.

sourceBalanceIdinteger, (int64)

Source balance ID. Required when moving between balances (with targetBalanceId).

targetBalanceIdinteger, (int64)

Target balance ID. Required when moving between balances (with sourceBalanceId).

amountobject

Amount to move. Required for same-currency movements. Either amount or quoteId must be provided.

curl -i -X POST \
  'https://api.wise.com/2026Q3/profiles/{profileId}/balance-movements' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'X-External-Correlation-Id: f47ac10b-58cc-4372-a567-0e02b2c3d479' \
  -H 'X-idempotence-uuid: 497f6eca-6276-4993-bfeb-53cbbbba6f08' \
  -d '{
    "quoteId": "00000000-0000-0000-0000-000000000000"
  }'

Responses

Created - Movement completed successfully.

Headers
X-External-Correlation-Idstring, (uuid), <= 36 characters

Echoed back when X-External-Correlation-Id was included in the request. Learn more.

Example:"f47ac10b-58cc-4372-a567-0e02b2c3d479"
x-trace-idstring

Unique trace identifier assigned by Wise. Useful when contacting support about a specific request.

Example:"fba501b6d453b96789f52338f019341f"
Bodyapplication/json
idinteger, (int64)

Movement transaction ID.

Example:30000001
typestring

Type of movement.

Enum:"DEPOSIT""WITHDRAWAL""CONVERSION"
Example:"CONVERSION"
statestring

State of the movement.

Enum:"PENDING""COMPLETED""CANCELLED""REVERSED"
Example:"COMPLETED"
balancesAfterArray of objects

Balance states after the movement.

creationTimestring, (date-time)

When the movement was created.

Example:"2017-11-21T09:55:49.275Z"
sourceAmountobject

Source amount of the movement.

targetAmountobject

Target amount of the movement.

ratenumber

Exchange rate applied to the conversion.

Example:0.88558
feeAmountsArray of objects

Fee amounts charged for the movement.

stepsArray of objects

Steps involved in the movement.

Response
{
  "id": 30000001,
  "type": "CONVERSION",
  "state": "COMPLETED",
  "balancesAfter": [
    {
      "id": 1,
      "value": 10000594.71,
      "currency": "GBP"
    }
  ],
  "creationTime": "2017-11-21T09:55:49.275Z",
  "sourceAmount": {
    "value": 113.48,
    "currency": "EUR"
  },
  "targetAmount": {
    "value": 100,
    "currency": "GBP"
  },
  "rate": 0.88558,
  "feeAmounts": [
    {
      "value": 0.56,
      "currency": "EUR"
    }
  ],
  "steps": [
    {
      "id": 369588,
      "type": "CONVERSION",
      "creationTime": "2017-11-21T09:55:49.276Z",
      "balancesAfter": [ … ],
      "sourceAmount": { … },
      "targetAmount": { … },
      "fee": { … },
      "rate": 0.88558
    }
  ]
}