Wise bank-account-details API

openapi: 3.2.0
info:
  title: Wise Platform Bank Account Details 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: bank-account-details
  x-displayName: Bank Account Details
  description: 'Bank account details allow users to receive money into their Wise Multi-Currency Account. Each currency balance can have local bank details (for domestic payments) and international bank details (for SWIFT payments) where available.


    Bank account details can be retrieved for existing balances, or new details can be ordered for currencies where they''re available but not yet issued.

    '
paths:
  /v1/profiles/{profileId}/account-details-orders:
    post:
      tags:
      - bank-account-details
      summary: Create bank account details order
      operationId: bankAccountDetailsOrderCreate
      security:
      - UserToken: []
      - PersonalToken: []
      description: 'Creates an order which will issue account details. It should use the same currency as the balance previously created. Fulfilling all the requirements will complete the order, reaching status `DONE`.


        The possible values for a requirement status are:

        - `PENDING_USER`: The requirement has some pending action from the user.

        - `PENDING_TW`: The requirement has some pending action from Wise.

        - `DONE`: The requirement is completed.


        The more common requirements are:

        - `VERIFICATION`: The user needs to be fully verified before completing this requirement.

        - `TOP_UP`: A fee will be charged and must be paid through wise.com before completing this requirement.

        '
      parameters:
      - name: profileId
        in: path
        required: true
        schema:
          type: integer
          format: int64
          example: 12345678
        description: The ID of the profile to create the bank account details order for.
      - $ref: '#/components/parameters/X-External-Correlation-Id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - currency
              properties:
                currency:
                  type: string
                  description: Balance currency (ISO 4217 Alphabetic Code).
                  example: EUR
      responses:
        '200':
          description: Bank account details order created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    description: Order status.
                    enum:
                    - PENDING_USER
                    - PENDING_TW
                    - DONE
                    example: PENDING_USER
                  currency:
                    type: string
                    description: Currency code (ISO 4217 Alphabetic Code).
                    example: EUR
                  requirements:
                    type: array
                    description: List of requirements to fulfill the order.
                    items:
                      type: object
                      properties:
                        type:
                          type: string
                          description: Requirement type.
                          enum:
                          - VERIFICATION
                          - TOP_UP
                          example: VERIFICATION
                        status:
                          type: string
                          description: Requirement status.
                          enum:
                          - PENDING_USER
                          - PENDING_TW
                          - DONE
                          example: PENDING_USER
          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:
      - bank-account-details
      summary: List bank account detail orders (v1)
      operationId: bankAccountDetailsOrdersListV1
      deprecated: true
      security:
      - UserToken: []
      - PersonalToken: []
      description: 'Returns the bank account assignment requests for a profile and multi-currency account.


        {% admonition type="warning" %}

        This endpoint is deprecated. Please use the [v3 endpoint](/api-reference/bank-account-details/bankaccountdetailsorderslist) instead.

        {% /admonition %}

        '
      parameters:
      - name: profileId
        in: path
        required: true
        schema:
          type: integer
          format: int64
          example: 12345678
        description: The ID of the profile to list bank account detail orders for.
      - $ref: '#/components/parameters/X-External-Correlation-Id'
      responses:
        '200':
          description: A list of bank account detail orders.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    status:
                      type: string
                      description: Order status.
                      enum:
                      - PENDING_USER
                      - PENDING_TW
                      - DONE
                      example: PENDING_USER
                    currency:
                      type: string
                      description: Currency code (ISO 4217 Alphabetic Code).
                      example: EUR
                    requirements:
                      type: array
                      description: List of requirements for the order.
                      items:
                        type: object
                        properties:
                          type:
                            type: string
                            description: Requirement type.
                            enum:
                            - VERIFICATION
                            - TOP_UP
                            example: TOP_UP
                          status:
                            type: string
                            description: Requirement status.
                            enum:
                            - PENDING_USER
                            - PENDING_TW
                            - DONE
                            example: PENDING_USER
          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'
  /v3/profiles/{profileId}/bank-details:
    post:
      tags:
      - bank-account-details
      summary: Create multiple bank account details
      operationId: bankAccountDetailsBankDetailsCreate
      security:
      - UserToken: []
      description: 'Creates and assigns a pair of local account details and international account details (where available) that are linked to the target balance specified in the request.


        {% admonition type="warning" %}

        Please reach out to our Support Team for access to this endpoint.

        {% /admonition %}

        '
      parameters:
      - name: profileId
        in: path
        required: true
        schema:
          type: integer
          format: int64
          example: 12345678
        description: The ID of the profile to create bank account details for.
      - $ref: '#/components/parameters/X-External-Correlation-Id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - targetAccountId
              properties:
                targetAccountId:
                  type: integer
                  format: int64
                  description: ID of the currency balance to create account details on.
                  example: 123456
      responses:
        '200':
          description: Bank account details created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Account detail ID.
                    example: '2'
                  currency:
                    type: string
                    description: Account detail currency (ISO 4217 Alphabetic Code).
                    example: GBP
                  active:
                    type: boolean
                    description: Status of the account detail.
                    example: true
                  localDetails:
                    type: object
                    description: Local bank account details.
                    properties:
                      bankName:
                        type: string
                        description: Name of the bank.
                        example: Wise
                      bankAddress:
                        type: string
                        description: Address of the bank.
                        example: TEA BUILDING, FLOOR 6, SHOREDITCH HIGH STREET
                      sortCode:
                        type: string
                        description: Sort code of the bank.
                        example: '231370'
                      accountNumber:
                        type: string
                        description: Bank account number.
                        example: '00000001'
                      type:
                        type: string
                        description: Type of account detail.
                        example: UK_ACCOUNT
                  internationalDetails:
                    type:
                    - object
                    - 'null'
                    description: International bank account details. Only returned if SWIFT payments are supported for that currency.
                    properties:
                      bankName:
                        type: string
                        description: Name of the bank.
                        example: Wise
                      bankAddress:
                        type: string
                        description: Address of the bank.
                        example: TEA BUILDING, FLOOR 6, SHOREDITCH HIGH STREET
                      swiftCode:
                        type: string
                        description: Bank SWIFT code.
                        example: TRWIGB22XXX
                      iban:
                        type: string
                        description: IBAN.
                        example: GB123450000000001
                      type:
                        type: string
                        description: Type of account detail.
                        example: IBAN
          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}/account-details:
    get:
      tags:
      - bank-account-details
      summary: Retrieve bank account details
      operationId: bankAccountDetailsGet
      security:
      - UserToken: []
      - PersonalToken: []
      description: 'Returns a list with all the `AVAILABLE` and `ACTIVE` account details for the given profile, including examples. Account receive options can also include local and international details to receive money on the currency balance.


        Example bank account details are returned for any currency where bank account details have not been requested and issued. Examples will always include an `id` of `null`.

        '
      parameters:
      - name: profileId
        in: path
        required: true
        schema:
          type: integer
          format: int64
          example: 12345678
        description: The ID of the profile to retrieve bank account details for.
      - $ref: '#/components/parameters/X-External-Correlation-Id'
      responses:
        '200':
          description: A list of bank account details.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BankAccountDetails'
          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'
  /v3/profiles/{profileId}/account-details-orders:
    get:
      tags:
      - bank-account-details
      summary: List bank account detail orders
      operationId: bankAccountDetailsOrdersList
      security:
      - UserToken: []
      - PersonalToken: []
      description: 'Returns the bank account assignment requests for a profile and multi-currency account.


        The response includes bank-details orders in the following statuses: `PENDING_USER`, `PENDING_TW`, `REQUIREMENTS_FULFILLED`, `DONE`.

        '
      parameters:
      - name: profileId
        in: path
        required: true
        schema:
          type: integer
          format: int64
          example: 12345678
        description: The ID of the profile to list bank account detail orders for.
      - name: currency
        in: query
        required: true
        schema:
          type: string
          example: GBP
        description: Currency code (ISO 4217 Alphabetic Code).
      - $ref: '#/components/parameters/X-External-Correlation-Id'
      responses:
        '200':
          description: A list of bank account detail orders.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    status:
                      type: string
                      description: Order status.
                      enum:
                      - PENDING_USER
                      - PENDING_TW
                      - REQUIREMENTS_FULFILLED
                      - DONE
                      example: DONE
                    currency:
                      type: string
                      description: Currency code (ISO 4217 Alphabetic Code).
                      example: EUR
                    requirements:
                      type: array
                      description: List of requirements for the order.
                      items:
                        type: object
                        properties:
                          type:
                            type: string
                            description: Requirement type.
                            enum:
                            - VERIFICATION
                            - TOP_UP
                            example: TOP_UP
                          status:
                            type: string
                            description: Requirement status.
                            enum:
                            - PENDING_USER
                            - PENDING_TW
                            - DONE
                            example: DONE
          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}/account-details/payments/{paymentId}/returns:
    post:
      tags:
      - bank-account-details
      summary: Create payment return
      operationId: bankAccountDetailsReturnsCreate
      security:
      - UserToken: []
      description: 'Creates a return for a payment received to bank account details.


        When you create a return, you must provide the ID of the payment you wish to return as well as the ID of the profile that received the payment. In addition, you can provide a `reason` for the return in the request body. When returning SWIFT payments, `reason` is a required field.

        '
      parameters:
      - name: profileId
        in: path
        required: true
        schema:
          type: integer
          format: int64
          example: 12345678
        description: The ID of the profile that received the payment.
      - name: paymentId
        in: path
        required: true
        schema:
          type: integer
          format: int64
          example: 987654321
        description: The ID of the payment to return.
      - $ref: '#/components/parameters/X-External-Correlation-Id'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                reason:
                  type: string
                  description: 'Reason for the return. Required when returning SWIFT payments.

                    '
                  enum:
                  - INCORRECT_ACCOUNT_NUMBER
                  - CLOSED_ACCOUNT
                  - BLOCKED_ACCOUNT
                  - CANCELLATION_REQUEST
                  - REGULATORY
                  - CUSTOMER_REQUEST
                  example: CLOSED_ACCOUNT
      responses:
        '201':
          description: Payment return created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                    description: ID of the return created.
                    example: 4cc39f2b-3513-453d-8792-9ccc22e513c3
          headers:
            X-External-Correlation-Id:
              $ref: '#/components/headers/X-External-Correlation-Id'
            x-trace-id:
              $ref: '#/components/headers/x-trace-id'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                          description: Error code.
                          example: error.payment-return.invalid
                        message:
                          type: string
                          description: Error message.
                          example: A valid reason is required to return a Swift payment
                        arguments:
                          type: array
                          description: Additional context values related to the error.
                          items: {}
                          example:
                          - 987654321
                          - 123456789
                          - null
          headers:
            X-External-Correlation-Id:
              $ref: '#/components/headers/X-External-Correlation-Id'
            x-trace-id:
              $ref: '#/components/headers/x-trace-id'
        '404':
          description: Payment not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                          description: Error code.
                          example: error.payment.not-found
                        message:
                          type: string
                          description: Error message.
                          example: No payment found with id [123456789] for profile id [987654321]
                        arguments:
                          type: array
                          description: Additional context values related to the error.
                          items: {}
                          example:
                          - 987654321
                          - 123456789
                          - null
          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'
webhooks:
  account-details-payment#state-change:
    post:
      operationId: eventAccountDetailsPaymentStateChange
      summary: Account details payment state change
      description: 'Triggered every time a pay-in is made into the specified account details.

        See the [Webhooks guide](/guides/developer/webhooks) for setup instructions, signature verification, and best practices.


        Events may not be delivered in the order they occurred. Use `data.occurred_at` to reconcile the order.

        See the [Event Ordering](/guides/developer/webhooks/event-ordering) guide for details.


        * Event type: `account-details-payment#state-change`

        * Profile level subscriptions: Supported

        * Application level subscriptions: Supported

        '
      tags:
      - bank-account-details
      parameters:
      - $ref: '#/components/parameters/x-signature-sha256'
      - $ref: '#/components/parameters/x-delivery-id'
      - $ref: '#/components/parameters/x-test-notification'
      requestBody:
        content:
          application/json:
            schema:
              title: Account Details Payment State Change Event
              discriminator:
                propertyName: schema_version
                mapping:
                  4.0.0: '#/components/schemas/v4.0.0-3'
                  2.0.0: '#/components/schemas/v2.0.0-3'
              oneOf:
              - $ref: '#/components/schemas/v4.0.0-3'
              - $ref: '#/components/schemas/v2.0.0-3'
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
          description: Return any `2xx` status to acknowledge receipt of the event.
components:
  schemas:
    v4.0.0-3:
      title: Schema version 4.0.0
      type: object
      properties:
        schema_version:
          type: string
          description: Version of the event schema. Determined by the `schema_version` on your [webhook subscription](/api-reference/webhook).
          enum:
          - 4.0.0
          example: 4.0.0
        subscription_id:
          type: string
          format: uuid
          description: ID of the webhook subscription that triggered this event
          example: 36c3f762-560d-4f07-84f9-5d8a3cacabbb
        event_type:
          type: string
          description: Event type identifier
          example: account-details-payment#state-change
        sent_at:
          type: string
          format: date-time
          description: Timestamp when the event was sent
          example: '2024-01-01T12:34:56.123Z'
        data:
          type: object
          properties:
            resource:
              type: object
              properties:
                id:
                  type: integer
                  format: int64
                  description: Balance ID which is linked to the account detail
                  example: 12345
                profile_id:
                  type: integer
                  format: int64
                  description: ID of the profile that owns the payment
                  example: 1
                type:
                  type: string
                  description: Type of the resource
                  example: balance-account
            account_details_id:
              type: string
              description: Account detail ID where the pay-in was received
              example: '1'
            target_account_id:
              type: string
              description: Balance ID which is linked to the account detail
              example: '12345'
            transfer:
              type: object
              properties:
                id:
                  type: integer
                  format: int64
                  description: ID of the incoming transfer
                  example: 36454
                type:
                  type: string
                  description: Type of the transfer
                  example: credit
                amount:
                  type: number
                  format: decimal
                  description: Transfer amount
                  example: 120
                currency:
                  type: string
                  description: Currency code
                  example: EUR
            sender:
              type: object
              properties:
                name:
                  type: string
                  description: Sender name
                  example: Test Sender
                account_number:
                  type: string
                  description: Sender account number
                  example: '12345678'
                bank_code:
                  type: string
                  description: Sender bank code
                  example: TESTBANK
                address:
                  type: string
                  description: Sender address
                  example: Test Address
            current_state:
              type: string
              description: Current state of the payment
              enum:
              - PROCESSING
              - COMPLETED
              - CANCELLED
              - REFUNDED
              example: COMPLETED
            previous_state:
              type: string
              description: Previous state of the payment
              enum:
              - PROCESSING
              - COMPLETED
              - CANCELLED
              - REFUNDED
              example: PROCESSING
            occurred_at:
              type: string
              format: date-time
              description: Timestamp when the event occurred
              example: '2026-02-24T11:10:13.789Z'
    v2.0.0-3:
      title: Schema version 2.0.0
      type: object
      properties:
        schema_version:
          type: string
          description: Version of the event schema. Determined by the `schema_version` on your [webhook subscription](/api-reference/webhook).
          enum:
          - 2.0.0
          example: 2.0.0
        subscription_id:
          type: string
          format: uuid
          description: ID of the webhook subscription that triggered this event
          example: 36c3f762-560d-4f07-84f9-5d8a3cacabbb
        event_type:
          type: string
          description: Event type identifier
          example: account-details-payment#state-change
        sent_at:
          type: string
          format: date-time
          description: Timestamp when the event was sent
          example: '2024-01-01T12:34:56Z'
        data:
          type: object
          properties:
            resource:
              type: object
              properties:
                id:
                  type: integer
                  format: int64
                  description: Balance ID which is linked to the account detail
                  example: 12345
                profile_id:
                  type: integer
                  format: int64
                  description: ID of the profile that owns the payment
                  example: 1
                type:
                  type: string
                  description: Type of the resource
                  example: balance-account
            account_details_id:
              type: string
              description: Account detail ID where the pay-in was received
              example: '1'
            target_account_id:
              type: string
              description: Balance ID which is linked to the account detail
              example: '12345'
            transfer:
              type: object
              properties:
                id:
                  type: integer
                  format: int64
                  description: ID of the incoming transfer
                  example: 36454
                type:
                  type: string
                  description: Type of the transfer
                  example: credit
                amount:
                  type: number
                  format: decimal
                  description: Transfer amount
                  example: 120
                currency:
                  type: string
                  description: Currency code
                  example: EUR
            sender:
              type: object
              properties:
                name:
                  type: string
                  description: Sender name
                  example: Test Sender
                account_number:
                  type: string
                  description: Sender account number
                  example: '12345678'
                bank_code:
                  type: string
                  description: Sender bank code
                  example: TESTBANK
                address:
                  type: string
                  description: Sender address
                  example: Test Address
            current_state:
              type: string
              description: Current state of the payment
              enum:
              - PROCESSING
              - COMPLETED
              - CANCELLED
              - REFUNDED
              example: COMPLETED
            previous_state:
              type: string
              description: Previous state of the payment
              enum:
              - PROCESSING
              - COMPLETED
              - CANCELLED
              - REFUNDED
              example: PROCESSING
            occurred_at:
              type: string
              format: date-time
              description: Timestamp when the event occurred
              example: '2026-02-24T11:10:13Z'
    BankAccountDetails:
      type: object
      title: Bank Account Details
      x-tags:
      - bank-account-details
      description: Bank account details for receiving money into a Wise Multi-Currency Account.
      properties:
        id:
          type:
          - integer
          - 'null'
          format: int64
          description: Bank account details ID. Returns `null` for preview account details that have not yet been issued.
          example: 14000001
        currency:
          type: object
          description: Currency information for the bank account detai

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