Wise transfer API

openapi: 3.1.0
info:
  title: Wise Platform 3ds transfer 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: transfer
  x-displayName: Transfers
  description: 'A transfer is a payment order to a [recipient account](/api-reference/recipient) based on a [quote](/api-reference/quote).


    Once created, a transfer usually needs to be funded within fourteen days. Otherwise, it will be automatically cancelled.


    There are 2 types of transfer resources: standard transfer resource and originator transfer resource. Please see below for differences between the two.


    Standard Transfer {% #standard-transfer .title-3 .m-t-5 %}


    The standard transfer object is returned by the [create transfer](/api-reference/transfer/transfercreate), [get transfer](/api-reference/transfer/transferget), [list transfers](/api-reference/transfer/transferlist), and [cancel transfer](/api-reference/transfer/transfercancel) endpoints.


    Originator Transfer {% #originator-transfer .title-3 .m-t-5 %}


    The originator transfer object is returned by the [create third party transfer](/api-reference/transfer/transferthirdpartycreate) and [get third party transfer](/api-reference/transfer/transferthirdpartyget) endpoints. It includes an additional `originator` data block with details about the payment originator.

    '
paths:
  /v1/transfers:
    post:
      operationId: transferCreate
      summary: Create a transfer
      description: 'Create a transfer to a recipient account based on a quote.


        Some fields are conditionally required depending on the currency route and transfer amount. Always call the [transfer requirements](/api-reference/transfer/transferrequirementsvalidate) endpoint to determine which fields are needed, and submit values accordingly. These requirements may change over time.


        #### Avoiding duplicate transfers


        The `customerTransactionId` field is used to avoid duplicate transfer requests. If your initial call to create a transfer fails (error or timeout), retry the call using the same `customerTransactionId` value. Subsequent retry messages are treated as repeat messages and will not create duplicate transfers. Use a sensible retry limit, ideally with a back-off approach.


        #### Payment Approvals


        {% admonition type="warning" %}

        Business Payment Approvals created on your wise.com settings page are not compatible with creating transfers over the API.

        {% /admonition %}


        If you use personal tokens and do not use client credentials, and if your business account has payment approvals, your application will receive this error when attempting to create a transfer: `Quote cannot be accepted with this request due to missing approval.`


        Consider removing the payment rule if you are going to use the API to create transfers.

        '
      tags:
      - transfer
      security:
      - UserToken: []
      - PersonalToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - targetAccount
              - quoteUuid
              - customerTransactionId
              properties:
                sourceAccount:
                  type: integer
                  format: int64
                  description: Refund recipient account ID
                targetAccount:
                  type: integer
                  format: int64
                  description: Recipient account ID. You can create multiple transfers to same recipient account
                quoteUuid:
                  type: string
                  format: uuid
                  description: V2 quote ID. You can only create one transfer per one quote. You cannot use same quote ID to create multiple transfers
                customerTransactionId:
                  type: string
                  format: uuid
                  description: Required to perform idempotency check to avoid duplicate transfers in case of network failures or timeouts
                details:
                  type: object
                  properties:
                    reference:
                      type: string
                      description: Recipient will see this reference text in their bank statement. Maximum allowed characters depends on the currency route. See [Business Payments Tips](https://wise.com/help/articles/2932870/tips-for-paying-invoices) for a full list
                    transferPurpose:
                      type: string
                      description: Conditionally required. For example when target currency is THB. See [Transfer Requirements](/api-reference/transfer/transferrequirementsvalidate) for conditions
                    transferPurposeSubTransferPurpose:
                      type: string
                      description: Conditionally required. For example when target currency is CNY. See [Transfer Requirements](/api-reference/transfer/transferrequirementsvalidate) for conditions
                    transferPurposeInvoiceNumber:
                      type: string
                      description: Conditionally required. For example when target currency is INR. See [Transfer Requirements](/api-reference/transfer/transferrequirementsvalidate) for conditions
                    sourceOfFunds:
                      type: string
                      description: Conditionally required. For example when target currency is USD and transfer amount exceeds 80k. See [Transfer Requirements](/api-reference/transfer/transferrequirementsvalidate) for conditions
            examples:
              basic:
                summary: Basic transfer
                value:
                  targetAccount: 8692237
                  quoteUuid: 8fa9be20-ba43-4b15-abbb-9424e1481050
                  customerTransactionId: 54a6bc09-cef9-49a8-9041-f1f0c654cd88
                  details:
                    reference: Invoice 2026-001
              with-transfer-requirements:
                summary: With conditionally required fields
                value:
                  targetAccount: 8692237
                  quoteUuid: 8fa9be20-ba43-4b15-abbb-9424e1481050
                  customerTransactionId: 54a6bc09-cef9-49a8-9041-f1f0c654cd88
                  details:
                    reference: Invoice 2026-001
                    transferPurpose: verification.transfers.purpose.pay.bills
                    transferPurposeSubTransferPurpose: INTERPRETATION_SERVICE
                    sourceOfFunds: verification.source.of.funds.salary
      responses:
        '200':
          description: Transfer successfully created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/transfer'
          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'
      parameters:
      - $ref: '#/components/parameters/X-External-Correlation-Id'
    get:
      operationId: transferList
      summary: List transfers
      description: 'Get the list of transfers for a given user''s profile (defaults to user''s personal profile).


        You can add query parameters to specify user''s profile (personal or business), time period and/or payment status. For example, you can query all failed payments created since last week, or all completed payments created since yesterday.

        '
      tags:
      - transfer
      security:
      - UserToken: []
      - PersonalToken: []
      parameters:
      - name: profile
        in: query
        required: false
        description: User profile ID. If parameter is omitted, defaults to user's personal profile
        schema:
          type: integer
          format: int64
      - name: status
        in: query
        required: false
        description: Comma separated list of one or more status codes to filter transfers. See [Tracking Transfers](/guides/product/send-money/tracking-transfers) for complete list of statuses
        schema:
          type: string
      - name: sourceCurrency
        in: query
        required: false
        description: Source currency code
        schema:
          type: string
      - name: targetCurrency
        in: query
        required: false
        description: Target currency code
        schema:
          type: string
      - name: createdDateStart
        in: query
        required: false
        description: Starting date to filter transfers, inclusive of the provided date
        schema:
          type: string
          format: date-time
      - name: createdDateEnd
        in: query
        required: false
        description: Ending date to filter transfers, inclusive of the provided date
        schema:
          type: string
          format: date-time
      - name: limit
        in: query
        required: false
        description: Maximum number of records to be returned in response
        schema:
          type: integer
          format: int32
      - name: offset
        in: query
        required: false
        description: Starting record number
        schema:
          type: integer
          format: int32
      - $ref: '#/components/parameters/X-External-Correlation-Id'
      responses:
        '200':
          description: Returns an array of transfer objects, with or without an `originator` block depending on the type of each transfer.
          content:
            application/json:
              schema:
                type: array
                items:
                  oneOf:
                  - $ref: '#/components/schemas/transfer'
                  - $ref: '#/components/schemas/originator-transfer'
          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/transfers/{transferId}:
    get:
      operationId: transferGet
      summary: Get a transfer by ID
      description: 'Get transfer info by ID. To receive dynamic updates as the state of the transfer changes, see the [webhooks documentation](/guides/developer/webhooks).

        '
      tags:
      - transfer
      security:
      - UserToken: []
      - PersonalToken: []
      parameters:
      - name: transferId
        in: path
        required: true
        description: The transfer ID
        schema:
          type: integer
          format: int64
      - $ref: '#/components/parameters/X-External-Correlation-Id'
      responses:
        '200':
          description: Returns the transfer object, with or without an `originator` block depending on the type of transfer.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/transfer'
                - $ref: '#/components/schemas/originator-transfer'
          headers:
            X-External-Correlation-Id:
              $ref: '#/components/headers/X-External-Correlation-Id'
            x-trace-id:
              $ref: '#/components/headers/x-trace-id'
        '404':
          description: Transfer not found.
          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/transfers/{transferId}/cancel:
    put:
      operationId: transferCancel
      summary: Cancel a transfer
      description: 'Transfers may be cancelled up until the transfer has been processed and funds converted. Cancellation is final — it cannot be undone.


        {% admonition type="info" name="When can a transfer be cancelled?" %}

        A transfer can only be cancelled programmatically via the API if it meets **all** of the following criteria:


        - The transfer is not in `funds_converted` or later state.

        - There are no processing problems with the transfer.


        If the transfer does not meet these criteria, the API will return a **409 Conflict** error with the code `transfer.cancellation.not.allowed`.


        For more information about transfer states, see [Tracking Transfers](/guides/product/send-money/tracking-transfers#transfer-statuses).

        {% /admonition %}

        '
      tags:
      - transfer
      security:
      - UserToken: []
      - PersonalToken: []
      parameters:
      - name: transferId
        in: path
        required: true
        description: The transfer ID
        schema:
          type: integer
          format: int64
      - $ref: '#/components/parameters/X-External-Correlation-Id'
      responses:
        '200':
          description: Returns the cancelled transfer object, with or without an `originator` block depending on the type of transfer.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/transfer'
                - $ref: '#/components/schemas/originator-transfer'
          headers:
            X-External-Correlation-Id:
              $ref: '#/components/headers/X-External-Correlation-Id'
            x-trace-id:
              $ref: '#/components/headers/x-trace-id'
        '404':
          description: Transfer not found.
          headers:
            X-External-Correlation-Id:
              $ref: '#/components/headers/X-External-Correlation-Id'
            x-trace-id:
              $ref: '#/components/headers/x-trace-id'
        '409':
          description: Transfer cannot be cancelled because it is in a non-cancellable state or has other restrictions. The error response will include the code `transfer.cancellation.not.allowed`.
          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/transfer-requirements:
    post:
      operationId: transferRequirementsValidate
      summary: Validate transfer requirements
      description: 'Exposes transfer-specific requirements based on the sender, quote, and target recipient account. Requirements vary by currency route, transfer amount, and regulatory region.


        For example, the maximum allowed length of reference text varies — the US payment system (ACH) supports 10 characters only, but transfers within Mexico allow up to 100 characters. Similarly, depending on the chosen currencies and the amount to be transferred, Wise may require additional details such as source of funds or transfer purpose.


        We highly recommend verifying transfer requirements before submitting any transfer to avoid delays caused by missing details.


        {% admonition type="success" name="Integration guide" %}

        See the [Transfer Requirements guide](/guides/developer/api-guides/transfer-requirements) for step-by-step integration instructions and a list of common requirement fields.

        {% /admonition %}

        '
      tags:
      - transfer
      security:
      - UserToken: []
      - PersonalToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - targetAccount
              - quoteUuid
              properties:
                targetAccount:
                  type: integer
                  format: int64
                  description: Recipient account ID
                quoteUuid:
                  type: string
                  format: uuid
                  description: V2 quote ID
                customerTransactionId:
                  type: string
                  format: uuid
                  description: Unique identifier for the transfer request
                originatorLegalEntityType:
                  type: string
                  enum:
                  - PRIVATE
                  - BUSINESS
                  description: Type of sender. Required from March 2026 for Correspondent Send integrations
                details:
                  type: object
                  properties:
                    reference:
                      type: string
                    sourceOfFunds:
                      type: string
                    sourceOfFundsOther:
                      type: string
                    transferPurpose:
                      type: string
                    transferPurposeSubTransferPurpose:
                      type: string
                    transferPurposeInvoiceNumber:
                      type: string
                    transferNature:
                      type: string
            example:
              targetAccount: 8692237
              quoteUuid: 8fa9be20-ba43-4b15-abbb-9424e1481050
              originatorLegalEntityType: PRIVATE
              details:
                reference: Invoice 2026-001
                sourceOfFunds: verification.source.of.funds.salary
                transferPurpose: verification.transfers.purpose.pay.bills
      responses:
        '200':
          description: Returns a list of transfer requirement objects describing the dynamic form fields.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/transfer-requirement'
              example:
              - type: transfer
                fields:
                - name: Transfer reference
                  group:
                  - key: reference
                    name: Transfer reference
                    type: text
                    refreshRequirementsOnChange: false
                    required: false
                    displayFormat: null
                    example: null
                    minLength: null
                    maxLength: 10
                    validationRegexp: '[a-zA-Z0-9- ]*'
                    validationAsync: null
                    valuesAllowed: null
                - name: Transfer purpose
                  group:
                  - key: transferPurpose
                    name: Transfer purpose
                    type: select
                    refreshRequirementsOnChange: true
                    required: true
                    displayFormat: null
                    example: null
                    minLength: null
                    maxLength: null
                    validationRegexp: null
                    validationAsync: null
                    valuesAllowed:
                    - key: verification.transfers.purpose.purchase.property
                      name: Buying property abroad
                    - key: verification.transfers.purpose.pay.bills
                      name: Rent or other property expenses
                    - key: verification.transfers.purpose.mortgage
                      name: Mortgage payment
                    - key: verification.transfers.purpose.pay.tuition
                      name: Tuition fees or studying expenses
                    - key: verification.transfers.purpose.send.to.family
                      name: Sending money home to family
                    - key: verification.transfers.purpose.living.expenses
                      name: General monthly living expenses
                    - key: verification.transfers.purpose.other
                      name: Other
                  - key: transferPurposeSubTransferPurpose
                    name: Please select a specific reason for your transfer
                    type: select
                    refreshRequirementsOnChange: true
                    required: true
                    displayFormat: null
                    example: null
                    minLength: null
                    maxLength: null
                    validationRegexp: null
                    validationAsync: null
                    valuesAllowed:
                    - key: INTERPRETATION_SERVICE
                      name: Interpretation service
                    - key: TRANSLATION_SERVICE
                      name: Translation service
                    - key: HUMAN_RESOURCE_SERVICE
                      name: Human resource service
                    - key: SOFTWARE_DEVELOPMENT_SERVICE
                      name: Software development service
                - name: Source of funds
                  group:
                  - key: sourceOfFunds
                    name: Source of funds
                    type: select
                    refreshRequirementsOnChange: true
                    required: true
                    displayFormat: null
                    example: null
                    minLength: null
                    maxLength: null
                    validationRegexp: null
                    validationAsync: null
                    valuesAllowed:
                    - key: verification.source.of.funds.salary
                      name: Salary
                    - key: verification.source.of.funds.investment
                      name: Investments (stocks, properties, etc.)
                    - key: verification.source.of.funds.inheritance
                      name: Inheritance
                    - key: verification.source.of.funds.loan
                      name: Loan
                    - key: verification.source.of.funds.other
                      name: Other
          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'
      parameters:
      - $ref: '#/components/parameters/X-External-Correlation-Id'
  /v2/profiles/{profileId}/third-party-transfers:
    post:
      operationId: transferThirdPartyCreate
      summary: Create a third party transfer
      description: 'Create a transfer on behalf of a third party.


        When creating a third party transfer:

        - The `originator` datablock is **required**. This details the ultimate sender of funds in the transfer.

        - Depending on the legal entity type of the originator (`PRIVATE` or `BUSINESS`), the required fields vary.

        - `originalTransferId` field must be used. This is your own ID for the transfer.


        You need to save the transfer ID for tracking its status later via webhooks.


        #### Avoiding duplicate transfers


        The `originalTransferId` field is used to avoid duplicate transfer requests. If your initial call fails (error or timeout), retry the call using the same `originalTransferId` value. Subsequent retry messages are treated as repeat messages and will not create duplicate transfers.

        '
      tags:
      - transfer
      security:
      - UserToken: []
      parameters:
      - name: profileId
        in: path
        required: true
        description: The profile ID
        schema:
          type: integer
          format: int64
      - $ref: '#/components/parameters/X-External-Correlation-Id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
              - title: Private originator
                type: object
                required:
                - targetAccount
                - quote
                - originalTransferId
                - originator
                properties:
                  targetAccount:
                    type: integer
                    format: int64
                    description: Recipient account ID. You can create multiple transfers to same recipient account
                    example: 12345678
                  quote:
                    type: string
                    description: V2 quote ID. You can only create one transfer per one quote. You cannot use same quote ID to create multiple transfers
                    example: 8fa9be20-ba43-4b15-abbb-9424e1481050
                  originalTransferId:
                    type: string
                    description: Unique transfer ID in your system. Also used to perform idempotency check to avoid duplicate transfers. You can only submit one transfer with same originalTransferId
                    example: unique-transfer-id-in-your-system
                  details:
                    type: object
                    properties:
                      reference:
                        type: string
                        description: Recipient will see this reference text in their bank statement. Maximum allowed characters depends on the currency route. See [Business Payments Tips](https://wise.com/help/articles/2932870/tips-for-paying-invoices) for a full list
                        example: Ski trip
                  originator:
                    type: object
                    required:
                    - legalEntityType
                    - reference
                    - name
                    - dateOfBirth
                    - address
                    - accountDetails
                    description: Data block to capture payment originator details
                    properties:
                      legalEntityType:
                        type: string
                        enum:
                        - PRIVATE
                        description: Payment originator legal type
                        example: PRIVATE
                      reference:
                        type: string
                        description: Unique customer ID in your system. This allows Wise to uniquely identify each originator
                        example: CST-2991992
                      name:
                        type: object
                        required:
                        - givenName
                        - familyName
                        properties:
                          givenName:
                            type: string
                            description: Payment originator first name
                            example: John
                          middleNames:
                            type: array
                            items:
                              type: string
                            description: Payment originator middle name(s)
                            example:
                            - Ryan
                          familyName:
                            type: string
                            description: Payment originator family name
                            example: Godspeed
                          patronymicName:
                            type: string
                            description: Payment originator patronymic name
                      dateOfBirth:
                        type: string
                        format: date
                        description: Payment originator date of birth
                        example: '1977-07-01'
                      nationality:
                        type: string
                        description: Payment originator nationality. Required for certain routes (e.g. to `UGX`)
                      address:
                        type: object
                        required:
                        - firstLine
                        - city
                        - countryCode
                        properties:
                          firstLine:
                            type: string
                            description: Payment originator address first line
                            example: Salu tee 100, Apt 4B
                          city:
                            type: string
                            description: Payment originator address city
                            example: Tallinn
                          stateCode:
                            type: string
                            description: Payment originator address state code. Required if address country code in (US, CA, BR, AU)
                          countryCode:
                            type: string
                            description: Payment originator address country code ISO 3166-1 alpha-2
                            minLength: 2
                            maxLength: 2
                            example: EE
                          postCode:
                            type: string
                            description: Originator address zip code
                            example: '12112'
                      accountDetails:
                        type: string
                        description: Originator account number
              - title: Business originator
                type: object
                required:
                - targetAccount
                - quote
                - originalTransferId
                - originator
                properties:
                  targetAccount:
                    type: integer
                    format: int64
                    description: Recipient account ID. You can create multiple transfers to same recipient account
                    example: 12345678
                  quote:
                    type: string
                    description: V2 quote ID. You can only create one transfer per one quote. You cannot use same quote ID to create multiple transfers
                    example: 8fa9be20-ba43-4b15-abbb-9424e1481050
                  originalTransferId:
                    type: string
                    description: Unique transfer ID in your system. Also used to perform idempotency check to avoid duplicate transfers. You can only submit one transfer with same originalTransferId
                    example: unique-transfer-id-in-your-system
                  details:
                    type: object
                    properties:
                      reference:
                        type: string
                        description: Recipient will see this reference text in their bank statement. Maximum allowed characters depends on the currency route. See [Business Payments Tips](https://wise.com/help/articles/2932870/tips-for-paying-invoices) for a full list
                        example: Payment for invoice 22092
                  originator:
                    type: object
                    required:
                    - legalEntityType
                    - reference
                    - name
                    - businessRegistrationCode
                    - address
                    description: Data block to capture payment originator details
                    properties:
                      legalEntityType:
                        type: string
                        enum:
             

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