Wise balance API

openapi: 3.1.0
info:
  title: Wise Platform 3ds balance API
  version: ''
  description: "The Wise Platform API is a REST-based interface that enables programmatic access to Wise's payment infrastructure. All endpoints return JSON-formatted responses and use standard HTTP methods and status codes.\n{% admonition type=\"success\" name=\"New to wise?\" %}\n  We strongly recommend first reading our **[Getting Started Guide](/guides/developer/index.md)** to help you set up credentials and make your first call.\n{% /admonition %}\n\nBefore you begin {% .title-2 .m-t-5 %}\n\nTo use this API reference effectively, you should have:\n\n- Received Valid [API credentials from Wise](/guides/developer/auth-and-security/index.md) (Client ID and Client Secret)\n- Understand OAuth 2.0 authentication\n- Be familiar with RESTful API concepts\n\nCore API resources {% .title-2 .m-t-5 .m-b-0 %}\n\n| Resource | Purpose |\n|----------|---------|\n| **[Quote](/api-reference/quote)** | Exchange rate and fee calculations |\n| **[Recipient](/api-reference/recipient)** | Beneficiary account management |\n| **[Transfer](/api-reference/transfer)** | Payment creation and execution |\n| **[Balance](/api-reference/balance)** | Multi-currency account operations |\n| **[Profile](/api-reference/profile)** | Account ownership details |\n| **[Rate](/api-reference/rate)** | Current and historical exchange rates |\n\n**Not sure which workflow to build?**<br>\nStart with our [Integration Guides](/guides/product/send-money/use-cases/index.md) for step-by-step implementation examples.{% .m-t-3 .m-b-5 %}\n"
servers:
- url: https://api.wise.com
  description: Production Environment
- url: https://api.wise-sandbox.com
  description: Sandbox Environment
tags:
- name: balance
  x-displayName: Balances
  description: 'Create and manage balance accounts within a multi-currency account.


    Each profile can hold multiple balance accounts in different currencies. A `STANDARD` balance is limited to one per currency, while `SAVINGS` balances (Jars) allow multiple in the same currency. Creating the first balance for a profile automatically creates the multi-currency account.


    Balances include an `investmentState` field. Only balances with `NOT_INVESTED` can be operated on via the API. Invested balances should be shown but not actionable.


    For a complete guide on multi-currency accounts, see [Multi-Currency Accounts](/guides/product/accounts).

    '
paths:
  /v4/profiles/{profileId}/balances:
    post:
      tags:
      - balance
      summary: Create a Balance Account
      operationId: balanceCreate
      description: 'Opens a balance within the specified profile, in the currency and type specified in the request.


        For `STANDARD` balances, only one can be created per currency. For `SAVINGS` balances, multiple in the same currency can be opened.


        When creating a `SAVINGS` type balance, a `name` is required.

        '
      security:
      - UserToken: []
      - PersonalToken: []
      parameters:
      - name: profileId
        in: path
        required: true
        schema:
          type: integer
          format: int64
        description: The profile ID.
      - name: X-idempotence-uuid
        in: header
        required: true
        schema:
          type: string
          format: uuid
        description: 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.
      - $ref: '#/components/parameters/X-External-Correlation-Id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body for creating a balance account.
              required:
              - currency
              - type
              properties:
                currency:
                  type: string
                  description: Currency code (ISO 4217 Alphabetic Code).
                  example: EUR
                type:
                  $ref: '#/components/schemas/BalanceType'
                name:
                  type: string
                  description: Name of the balance. Required for SAVINGS type balances.
            example:
              currency: EUR
              type: STANDARD
      responses:
        '201':
          description: Created - Balance successfully created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Balance'
          headers:
            X-External-Correlation-Id:
              $ref: '#/components/headers/X-External-Correlation-Id'
            x-trace-id:
              $ref: '#/components/headers/x-trace-id'
        '429':
          $ref: '#/components/responses/429'
    get:
      tags:
      - balance
      summary: List Balances for a Profile
      operationId: balanceList
      description: 'Retrieves the user''s multi-currency account balance accounts. Returns all balance accounts the profile has in the types specified.


        The `types` parameter must include at least one type. To return more than one type, comma-separate the values.

        '
      security:
      - UserToken: []
      - PersonalToken: []
      parameters:
      - name: profileId
        in: path
        required: true
        schema:
          type: integer
          format: int64
        description: The profile ID.
      - name: types
        in: query
        required: true
        schema:
          type: string
        description: Comma-separated list of balance types to return. Acceptable values are `STANDARD` and `SAVINGS`.
        example: STANDARD
      - $ref: '#/components/parameters/X-External-Correlation-Id'
      responses:
        '200':
          description: OK - Successfully retrieved balances.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Balance'
          headers:
            X-External-Correlation-Id:
              $ref: '#/components/headers/X-External-Correlation-Id'
            x-trace-id:
              $ref: '#/components/headers/x-trace-id'
        '429':
          $ref: '#/components/responses/429'
  /v4/profiles/{profileId}/balances/{balanceId}:
    get:
      tags:
      - balance
      summary: Retrieve a Balance by ID
      operationId: balanceGet
      description: Returns a balance based on the specified balance ID.
      security:
      - UserToken: []
      - PersonalToken: []
      parameters:
      - name: profileId
        in: path
        required: true
        schema:
          type: integer
          format: int64
        description: The profile ID.
      - name: balanceId
        in: path
        required: true
        schema:
          type: integer
          format: int64
        description: The balance ID.
      - $ref: '#/components/parameters/X-External-Correlation-Id'
      responses:
        '200':
          description: OK - Successfully retrieved the balance.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Balance'
          headers:
            X-External-Correlation-Id:
              $ref: '#/components/headers/X-External-Correlation-Id'
            x-trace-id:
              $ref: '#/components/headers/x-trace-id'
        '429':
          $ref: '#/components/responses/429'
    delete:
      tags:
      - balance
      summary: Remove a Balance Account
      operationId: balanceDelete
      description: 'Closes a balance account for the user''s profile.


        Balance accounts must have a zero balance to be closed. Bank account details for the balance will also be deactivated and may not be restored.

        '
      security:
      - UserToken: []
      - PersonalToken: []
      parameters:
      - name: profileId
        in: path
        required: true
        schema:
          type: integer
          format: int64
        description: The profile ID.
      - name: balanceId
        in: path
        required: true
        schema:
          type: integer
          format: int64
        description: The balance ID.
      - $ref: '#/components/parameters/X-External-Correlation-Id'
      responses:
        '204':
          description: No Content - Balance successfully removed.
          headers:
            X-External-Correlation-Id:
              $ref: '#/components/headers/X-External-Correlation-Id'
            x-trace-id:
              $ref: '#/components/headers/x-trace-id'
        '429':
          $ref: '#/components/responses/429'
  /v2/profiles/{profileId}/balance-movements:
    post:
      tags:
      - balance
      summary: Convert or Move Money Between Balances
      operationId: balanceMovement
      description: '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: []
      - PersonalToken: []
      parameters:
      - name: profileId
        in: path
        required: true
        schema:
          type: integer
          format: int64
        description: The profile ID.
      - name: X-idempotence-uuid
        in: header
        required: true
        schema:
          type: string
          format: uuid
        description: 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.
      - $ref: '#/components/parameters/X-External-Correlation-Id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body for balance movements (conversion or transfer).
              properties:
                quoteId:
                  type: string
                  format: uuid
                  description: 'Quote ID. Required for cross-currency movements. Quote must be created with `payOut: BALANCE`.'
                sourceBalanceId:
                  type: integer
                  format: int64
                  description: Source balance ID. Required when moving between balances (with targetBalanceId).
                targetBalanceId:
                  type: integer
                  format: int64
                  description: Target balance ID. Required when moving between balances (with sourceBalanceId).
                amount:
                  type: object
                  description: Amount to move. Required for same-currency movements. Either `amount` or `quoteId` must be provided.
                  properties:
                    value:
                      type: number
                      description: Amount value.
                    currency:
                      type: string
                      description: Currency code (ISO 4217 Alphabetic Code).
            examples:
              conversion:
                summary: Convert between currencies
                value:
                  quoteId: 00000000-0000-0000-0000-000000000000
              move:
                summary: Move within same currency
                value:
                  sourceBalanceId: 1
                  targetBalanceId: 2
                  amount:
                    value: 100
                    currency: EUR
      responses:
        '201':
          description: Created - Movement completed successfully.
          content:
            application/json:
              schema:
                type: object
                description: Response from a balance movement operation.
                properties:
                  id:
                    type: integer
                    format: int64
                    description: Movement transaction ID.
                    example: 30000001
                  type:
                    type: string
                    description: Type of movement.
                    enum:
                    - DEPOSIT
                    - WITHDRAWAL
                    - CONVERSION
                    example: CONVERSION
                  state:
                    type: string
                    description: State of the movement.
                    enum:
                    - PENDING
                    - COMPLETED
                    - CANCELLED
                    - REVERSED
                    example: COMPLETED
                  balancesAfter:
                    type: array
                    description: Balance states after the movement.
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          format: int64
                          description: Balance ID.
                          example: 1
                        value:
                          type: number
                          description: Balance value after movement.
                          example: 10000594.71
                        currency:
                          type: string
                          description: Currency code.
                          example: GBP
                  creationTime:
                    type: string
                    format: date-time
                    description: When the movement was created.
                    example: '2017-11-21T09:55:49.275Z'
                  sourceAmount:
                    type: object
                    description: Source amount of the movement.
                    properties:
                      value:
                        type: number
                        example: 113.48
                      currency:
                        type: string
                        example: EUR
                  targetAmount:
                    type: object
                    description: Target amount of the movement.
                    properties:
                      value:
                        type: number
                        example: 100
                      currency:
                        type: string
                        example: GBP
                  rate:
                    type: number
                    description: Exchange rate applied to the conversion.
                    example: 0.88558
                  feeAmounts:
                    type: array
                    description: Fee amounts charged for the movement.
                    items:
                      type: object
                      properties:
                        value:
                          type: number
                          example: 0.56
                        currency:
                          type: string
                          example: EUR
                  steps:
                    type: array
                    description: Steps involved in the movement.
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          format: int64
                          description: Step ID.
                          example: 369588
                        type:
                          type: string
                          description: Step type.
                          example: CONVERSION
                        creationTime:
                          type: string
                          format: date-time
                          description: When the step was created.
                          example: '2017-11-21T09:55:49.276Z'
                        balancesAfter:
                          type: array
                          items:
                            type: object
                            properties:
                              value:
                                type: number
                                example: 9998887.01
                              currency:
                                type: string
                                example: EUR
                        sourceAmount:
                          type: object
                          properties:
                            value:
                              type: number
                              example: 113.48
                            currency:
                              type: string
                              example: EUR
                        targetAmount:
                          type: object
                          properties:
                            value:
                              type: number
                              example: 100
                            currency:
                              type: string
                              example: GBP
                        fee:
                          type: object
                          properties:
                            value:
                              type: number
                              example: 0.56
                            currency:
                              type: string
                              example: EUR
                        rate:
                          type: number
                          description: Exchange rate applied.
                          example: 0.88558
          headers:
            X-External-Correlation-Id:
              $ref: '#/components/headers/X-External-Correlation-Id'
            x-trace-id:
              $ref: '#/components/headers/x-trace-id'
        '429':
          $ref: '#/components/responses/429'
  /v1/profiles/{profileId}/balance-capacity:
    get:
      tags:
      - balance
      summary: Retrieve Deposit Limits
      operationId: balanceCapacity
      description: 'Returns the deposit limit for a profile based on regulatory requirements.


        Useful for personal profiles located in countries that have hold limits. We advise calling this API before depositing money into an account if the profile is located in Singapore or Malaysia.

        '
      security:
      - UserToken: []
      - PersonalToken: []
      parameters:
      - name: profileId
        in: path
        required: true
        schema:
          type: integer
          format: int64
        description: The profile ID.
      - name: currency
        in: query
        required: true
        schema:
          type: string
        description: Currency code (ISO 4217 Alphabetic Code). The deposit limit will be returned in this currency.
        example: SGD
      - $ref: '#/components/parameters/X-External-Correlation-Id'
      responses:
        '200':
          description: OK - Successfully retrieved deposit limits.
          content:
            application/json:
              schema:
                type: object
                description: Deposit limit information for a profile.
                properties:
                  hasLimit:
                    type: boolean
                    description: True if there is a regulatory hold limit for the profile's country.
                    example: true
                  depositLimit:
                    type: object
                    description: Amount of money that can be added to the account.
                    properties:
                      amount:
                        type: number
                        description: Deposit limit amount.
                        example: 2000
                      currency:
                        type: string
                        description: Currency code (ISO 4217 Alphabetic Code).
                        example: SGD
          headers:
            X-External-Correlation-Id:
              $ref: '#/components/headers/X-External-Correlation-Id'
            x-trace-id:
              $ref: '#/components/headers/x-trace-id'
        '429':
          $ref: '#/components/responses/429'
  /v1/profiles/{profileId}/excess-money-account:
    post:
      tags:
      - balance
      summary: Add an Excess Money Account
      operationId: excessMoneyAccount
      description: 'If a balance goes over the regulatory hold limit, excess funds are automatically moved to another account at the end of the day.


        Use this endpoint to specify a recipient where excess money will be transferred.


        Primarily used for Singapore and Malaysia customers.

        '
      security:
      - UserToken: []
      - PersonalToken: []
      parameters:
      - name: profileId
        in: path
        required: true
        schema:
          type: integer
          format: int64
        description: The profile ID.
      - $ref: '#/components/parameters/X-External-Correlation-Id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body for configuring an excess money account.
              required:
              - recipientId
              properties:
                recipientId:
                  type: integer
                  format: int64
                  description: ID of the recipient for excess money transfers.
                  example: 148393305
      responses:
        '200':
          description: OK - Excess money account configured successfully.
          content:
            application/json:
              schema:
                type: object
                description: Response from configuring an excess money account.
                properties:
                  userProfileId:
                    type: integer
                    format: int64
                    description: ID of the profile.
                    example: 12321323
                  recipientId:
                    type: integer
                    format: int64
                    description: ID of the recipient for excess money transfers.
                    example: 148393305
          headers:
            X-External-Correlation-Id:
              $ref: '#/components/headers/X-External-Correlation-Id'
            x-trace-id:
              $ref: '#/components/headers/x-trace-id'
        '429':
          $ref: '#/components/responses/429'
  /v1/profiles/{profileId}/total-funds/{currency}:
    get:
      tags:
      - balance
      summary: Get Total Funds
      operationId: totalFunds
      description: 'Provides an overview of your account''s total valuation and available liquidity across all balances.


        Returns total worth, total available (including overdraft), total cash, and overdraft details.


        #### Example (Assuming GBP and USD has 1:1 exchange rate)


        | Scenario                                 | GBP balance | USD balance | Total Worth | Total Available | Overdraft Usage | Overdraft Limit |

        | ---------------------------------------- | ----------- | ----------- | ----------- | --------------- | --------------- | --------------- |

        | Positive account value with no overdraft | 2000        | 0           | 2000        | 2000            | 0               | 0               |

        | Positive account value with overdraft    | 2000        | -100        | 1900        | 2400            | 100             | 500             |

        | Negative account value with overdraft    | 0           | -100        | -100        | 400             | 100             | 500             |

        '
      security:
      - UserToken: []
      - PersonalToken: []
      parameters:
      - name: profileId
        in: path
        required: true
        schema:
          type: integer
          format: int64
        description: The profile ID.
      - name: currency
        in: path
        required: true
        schema:
          type: string
        description: Currency code (ISO 4217 Alphabetic Code). All values will be converted to this currency.
        example: EUR
      - $ref: '#/components/parameters/X-External-Correlation-Id'
      responses:
        '200':
          description: OK - Successfully retrieved total funds.
          content:
            application/json:
              schema:
                type: object
                description: Total funds overview for a profile.
                properties:
                  totalWorth:
                    type: object
                    description: Total worth of the account, including cash ledger balance and valuation of any asset portfolio if invested.
                    properties:
                      value:
                        type: number
                        description: Amount value.
                        example: 2000
                      currency:
                        type: string
                        description: Currency code (ISO 4217 Alphabetic Code).
                        example: EUR
                  totalAvailable:
                    type: object
                    description: Total available balance, which is the sum of cash ledger balance and any approved overdraft limit.
                    properties:
                      value:
                        type: number
                        description: Amount value.
                        example: 2500
                      currency:
                        type: string
                        description: Currency code (ISO 4217 Alphabetic Code).
                        example: EUR
                  totalCash:
                    type: object
                    description: Total cash balance across all balances, including group balances but excluding asset portfolios.
                    properties:
                      value:
                        type: number
                        description: Amount value.
                        example: 2000
                      currency:
                        type: string
                        description: Currency code (ISO 4217 Alphabetic Code).
                        example: EUR
                  overdraft:
                    type: object
                    description: Overdraft details for the account.
                    properties:
                      limit:
                        type: object
                        description: Maximum overdraft available through an overdraft program. Zero if no approved overdraft.
                        properties:
                          value:
                            type: number
                            description: Amount value.
                            example: 500
                          currency:
                            type: string
                            description: Currency code (ISO 4217 Alphabetic Code).
                            example: EUR
                      used:
                        type: object
                        description: Portion of the approved overdraft limit currently being utilized.
                        properties:
                          value:
                            type: number
                            description: Amount value.
                            example: 0
                          currency:
                            type: string
                            description: Currency code (ISO 4217 Alphabetic Code).
                            example: EUR
                      available:
                        type: object
                        description: Amount of overdraft currently available (limit minus used).
                        properties:
                          value:
                            type: number
                            description: Amount value.
                            example: 500
                          currency:
                            type: string
                            description: Currency code (ISO 4217 Alphabetic Code).
                            example: EUR
                      availableByCurrency:
                        type: array
                        description: Available overdraft amounts converted to each currency the customer has a balance in.
                        items:
                          type: object
                          properties:
                            value:
                              type: number
                              description: Amount value.
                              example: 500
                            currency:
                              type: string
                              description: Currency code (ISO 4217 Alphabetic Code).
                              example: EUR
          headers:
            X-External-Correlation-Id:
              $ref: '#/components/headers/X-External-Correlation-Id'
            x-trace-id:
              $ref: '#/components/headers/x-trace-id'
        '429':
          $ref: '#/components/responses/429'
  /v1/borderless-accounts:
    get:
      operationId: balanceGetV1
      summary: Get account balance (v1)
      deprecated: true
      description: '{% admonition type="warning" %}

        This endpoint is deprecated. Use the [v4 Balances endpoint](/api-reference/balance/balanceget) instead.

        {% /admonition %}


        Get available balances for all activated currencies in your multi-currency account.

        '
      tags:
      - balance
      security:
      - UserToken: []
      parameters:
      - name: profileId
        in: query
        required: true
        description: Your profile ID.
        schema:
          type: integer
          format: int64
        example: 33333333
      - $ref: '#/components/parameters/X-External-Correlation-Id'
      responses:
        '200':
          description: Array of borderless account objects with balances.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                      description: Multi-currency account ID.
                      example: 64
                    profileId:
                      type: integer
                      description: Personal or business profile ID.
                      example: 33333333
                    recipientId:
                      type: integer
                      description: Recipient ID you can use for a multi-currency account deposit.
                      example: 13828530
                    creationTime:
                      type: string
                      format: date-time
                      description: Date when multi-currency account was opened.
                      example: '2018-03-14T12:31:15.678Z'
                    modificationTime:
                      type: string
                      format: date-time
                      description: Date when multi-currency account setup was modified.
                      example: '2018-03-19T15:19:42.111Z'
                    active:
                      type: boolean
                      description: Is multi-currency account active or inactive.
                      example: true
                    eligible:
                      type: boolean
                      description: Ignore.
                      example: true
                    balances:
                      type: array
                      items:
                        type: object
                        properties:
                          balanceType:
                            type: string
                            description: Balance type.
                            example: AVAILABLE
                          currency:
                            type: string
                            description: Currency code.
                            example: GBP
                          amount:
                            type: object
                            properties:
                              value:
                                type: number
                                description: Available balance in specified currency.
                                example: 10999859
                 

# --- truncated at 32 KB (63 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/wise/refs/heads/main/openapi/wise-balance-api-openapi.yml