openapi: 3.1.0
info:
  title: Wise Platform 3ds sca-otp 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: sca-otp
  x-displayName: OTP
  description: 'For phone-based OTP (one-time password) authentication — where an OTP is a single-use 6-digit code sent to verify the identity of a user — Wise supports multiple delivery methods, including SMS, WhatsApp, and voice. Use Wise''s secure endpoint to [create](/api-reference/sca-otp/usersecurityphonenumbercreate) and register the end user''s phone number. Then, call the trigger endpoints ([SMS](/api-reference/sca-otp/ottsmstrigger), [WhatsApp](/api-reference/sca-otp/ottwhatsapptrigger), [Voice](/api-reference/sca-otp/ottvoicetrigger)) to send an OTP to the registered number. Finally, submit the OTP via the verify endpoints ([SMS](/api-reference/sca-otp/ottsmsverify), [WhatsApp](/api-reference/sca-otp/ottwhatsappverify), [Voice](/api-reference/sca-otp/ottvoiceverify)) to complete the authentication challenge.


    Please read the [SCA over API guide](/guides/developer/auth-and-security/sca-over-api) to understand how SCA integration works.

    '
paths:
  /v1/application/users/{userId}/phone-numbers:
    post:
      operationId: userSecurityPhoneNumberCreate
      summary: Create Phone Number
      description: 'Create a verified phone number for a user.


        {% admonition type="warning" %}

        This endpoint is restricted and requires both a client credentials token and additional access to use. Please speak with your implementation manager if you would like to use this API.

        {% /admonition %}

        '
      tags:
      - sca-otp
      security:
      - ClientCredentialsToken: []
      parameters:
      - name: userId
        in: path
        required: true
        description: User ID.
        schema:
          type: integer
          format: int64
      - $ref: '#/components/parameters/X-External-Correlation-Id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                phoneNumber:
                  type: string
                  description: A valid phone number in string.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/phone-number'
          headers:
            X-External-Correlation-Id:
              $ref: '#/components/headers/X-External-Correlation-Id'
            x-trace-id:
              $ref: '#/components/headers/x-trace-id'
        '422':
          description: The phone number is already associated with another account.
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                        message:
                          type: string
              example:
                errors:
                - code: phone.number.repeated
                  message: It's linked to an account with the email ****@wise.com
          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/one-time-token/sms/trigger:
    post:
      operationId: ottSmsTrigger
      summary: Trigger SMS Challenge
      description: 'To trigger a SMS challenge by sending SMS to user verified [phone number](/api-reference/user-security/usersecurityphonenumberlist) containing a 6 digit one time password (**OTP**).


        This **OTP** code can be used to clear a SMS challenge by using the [Verify SMS endpoint](/api-reference/sca-otp/ottsmsverify).

        '
      tags:
      - sca-otp
      security:
      - UserToken: []
      parameters:
      - name: One-Time-Token
        in: header
        required: true
        description: Text value of a OTT.
        schema:
          type: string
      - $ref: '#/components/parameters/X-External-Correlation-Id'
      responses:
        '200':
          description: Trigger result with obfuscated phone number.
          content:
            application/json:
              schema:
                type: object
                properties:
                  obfuscatedPhoneNo:
                    type: string
                    description: Obfuscated phone number that can be used as a hint for the end customer regarding which phone number the SMS was sent to.
                    example: '*********8888'
          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/one-time-token/sms/verify:
    post:
      operationId: ottSmsVerify
      summary: Verify SMS Challenge
      description: 'To clear a **SMS** challenge listed in a OTT.


        Notes:

        1. User is required to have a verified phone number. See [create phone number](/api-reference/sca-otp/usersecurityphonenumbercreate) for more information.

        2. [Trigger SMS Challenge](/api-reference/sca-otp/ottsmstrigger) is required to be called first.

        3. Since we won''t be sending real SMS on sandbox, the **OTP Code** will always be **111111**.

        '
      tags:
      - sca-otp
      security:
      - UserToken: []
      parameters:
      - name: One-Time-Token
        in: header
        required: true
        description: Text value of a OTT.
        schema:
          type: string
      - $ref: '#/components/parameters/X-External-Correlation-Id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                otpCode:
                  type: string
                  description: 6 digit OTP code in text format.
                  example: '111111'
      responses:
        '200':
          description: One time token status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ott-response'
              example:
                oneTimeTokenProperties:
                  oneTimeToken: 9f5f5812-2609-4e48-8418-b64437c0c7cd
                  challenges: []
                  validity: 3600
          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/one-time-token/whatsapp/trigger:
    post:
      operationId: ottWhatsappTrigger
      summary: Trigger WhatsApp Challenge
      description: 'To trigger a WhatsApp challenge by sending WhatsApp message to user verified [phone number](/api-reference/user-security/usersecurityphonenumberlist) containing a 6 digit one time password (**OTP**).


        This **OTP** code can be used to clear a WHATSAPP challenge by using the [Verify WhatsApp endpoint](/api-reference/sca-otp/ottwhatsappverify).

        '
      tags:
      - sca-otp
      security:
      - UserToken: []
      parameters:
      - name: One-Time-Token
        in: header
        required: true
        description: Text value of a OTT.
        schema:
          type: string
      - $ref: '#/components/parameters/X-External-Correlation-Id'
      responses:
        '200':
          description: Trigger result with obfuscated phone number.
          content:
            application/json:
              schema:
                type: object
                properties:
                  obfuscatedPhoneNo:
                    type: string
                    description: Obfuscated phone number that can be used as a hint for the end customer regarding which phone number the WhatsApp message was sent to.
                    example: '*********8888'
          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/one-time-token/whatsapp/verify:
    post:
      operationId: ottWhatsappVerify
      summary: Verify WhatsApp Challenge
      description: 'To clear a **WHATSAPP** challenge listed in a OTT.


        Notes:

        1. User is required to have a verified phone number. See [create phone number](/api-reference/sca-otp/usersecurityphonenumbercreate) for more information.

        2. [Trigger WhatsApp Challenge](/api-reference/sca-otp/ottwhatsapptrigger) is required to be called first.

        3. Since we won''t be sending real WhatsApp message on sandbox, the **OTP Code** will always be **111111**.

        '
      tags:
      - sca-otp
      security:
      - UserToken: []
      parameters:
      - name: One-Time-Token
        in: header
        required: true
        description: Text value of a OTT.
        schema:
          type: string
      - $ref: '#/components/parameters/X-External-Correlation-Id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                otpCode:
                  type: string
                  description: 6 digit OTP code in text format.
                  example: '111111'
      responses:
        '200':
          description: One time token status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ott-response'
              example:
                oneTimeTokenProperties:
                  oneTimeToken: 9f5f5812-2609-4e48-8418-b64437c0c7cd
                  challenges: []
                  validity: 3600
          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/one-time-token/voice/trigger:
    post:
      operationId: ottVoiceTrigger
      summary: Trigger Voice Challenge
      description: 'To trigger a Voice challenge by sending voice message to user verified [phone number](/api-reference/user-security/usersecurityphonenumberlist) containing a 6 digit one time password (**OTP**).


        This **OTP** code can be used to clear a VOICE challenge by using the [Verify Voice endpoint](/api-reference/sca-otp/ottvoiceverify).

        '
      tags:
      - sca-otp
      security:
      - UserToken: []
      parameters:
      - name: One-Time-Token
        in: header
        required: true
        description: Text value of a OTT.
        schema:
          type: string
      - $ref: '#/components/parameters/X-External-Correlation-Id'
      responses:
        '200':
          description: Trigger result with obfuscated phone number.
          content:
            application/json:
              schema:
                type: object
                properties:
                  obfuscatedPhoneNo:
                    type: string
                    description: Obfuscated phone number that can be used as a hint for the end customer regarding which phone number the voice message was sent to.
                    example: '*********8888'
          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/one-time-token/voice/verify:
    post:
      operationId: ottVoiceVerify
      summary: Verify Voice Challenge
      description: 'To clear a **VOICE** challenge listed in a OTT.


        Notes:

        1. User is required to have a verified phone number. See [create phone number](/api-reference/sca-otp/usersecurityphonenumbercreate) for more information.

        2. [Trigger Voice Challenge](/api-reference/sca-otp/ottvoicetrigger) is required to be called first.

        3. Since we won''t be sending real voice message on sandbox, the **OTP Code** will always be **111111**.

        '
      tags:
      - sca-otp
      security:
      - UserToken: []
      parameters:
      - name: One-Time-Token
        in: header
        required: true
        description: Text value of a OTT.
        schema:
          type: string
      - $ref: '#/components/parameters/X-External-Correlation-Id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                otpCode:
                  type: string
                  description: 6 digit OTP code in text format.
                  example: '111111'
      responses:
        '200':
          description: One time token status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ott-response'
              example:
                oneTimeTokenProperties:
                  oneTimeToken: 9f5f5812-2609-4e48-8418-b64437c0c7cd
                  challenges: []
                  validity: 3600
          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/application/users/{userId}/phone-numbers/{phoneNumberId}:
    delete:
      operationId: userSecurityPhoneNumberDelete
      summary: Delete Phone Number
      description: 'Delete a verified phone number for a user.


        {% admonition type="warning" %}

        This endpoint is restricted and requires both a client credentials token and additional access to use. Please speak with your implementation manager if you would like to use this API.

        {% /admonition %}

        '
      tags:
      - sca-otp
      security:
      - ClientCredentialsToken: []
      parameters:
      - name: userId
        in: path
        required: true
        description: User ID.
        schema:
          type: integer
          format: int64
      - name: phoneNumberId
        in: path
        required: true
        description: ID of a phone number.
        schema:
          type: integer
          format: int64
      - $ref: '#/components/parameters/X-External-Correlation-Id'
      responses:
        '204':
          description: No Content.
          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'
components:
  parameters:
    X-External-Correlation-Id:
      x-global: true
      name: X-External-Correlation-Id
      in: header
      required: false
      description: 'Optional UUID for correlating requests across systems. If provided, Wise echoes it back in the response. Maximum 36 characters. [Learn more](/guides/developer/headers/correlation-id).

        '
      schema:
        type: string
        format: uuid
        maxLength: 36
      example: f47ac10b-58cc-4372-a567-0e02b2c3d479
  schemas:
    ott-response:
      type: object
      properties:
        oneTimeTokenProperties:
          type: object
          description: Properties of the one time token.
          properties:
            oneTimeToken:
              type: string
              description: Unique identifier of a one time token.
            challenges:
              type: array
              description: Array of challenge objects.
              items:
                type: object
                description: Challenge object containing primary and alternative challenges.
                properties:
                  primaryChallenge:
                    type: object
                    description: Type of challenge user can do.
                    properties:
                      type:
                        type: string
                        description: Type of the challenge (PIN, FACE_MAP, SMS, WHATSAPP, VOICE, PARTNER_DEVICE_FINGERPRINT).
                      viewData:
                        type: object
                        description: An object that provides data required to present a challenge window. It can be messages, IDs, or other attributes.
                  alternatives:
                    type: array
                    description: Alternative challenges that user can do instead.
                    items:
                      type: object
                  required:
                    type: boolean
                    description: Required (or not) to pass the OTT.
                  passed:
                    type: boolean
                    description: Status of this challenge.
            validity:
              type: integer
              format: int64
              description: Seconds until the one time token becomes expired.
            actionType:
              type: string
              description: The action bound to the one time token. For example, `BALANCE__GET_STATEMENT` when we want to [retrieve a balance account statement](/api-reference/balance-statement/balancestatementget).
            userId:
              type: integer
              format: int64
              description: Creator of this one time token.
    phone-number:
      title: Phone Number
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: ID of the phone number.
          example: 1230944
        phoneNumber:
          type: string
          description: A text representation of phone number.
          example: '+6588888888'
        type:
          type: string
          description: 'Type of phone number when used in authentication.


            Only **PRIMARY** is supported at the moment.

            '
          example: PRIMARY
        verified:
          type: boolean
          description: Indicator if phone number is verified.
          example: true
        clientId:
          type: string
          description: Client ID of which this phone number belongs to.
          example: clientId
  headers:
    X-External-Correlation-Id:
      x-global: true
      description: Echoed back when `X-External-Correlation-Id` was included in the request. [Learn more](/guides/developer/headers/correlation-id).
      schema:
        type: string
        format: uuid
        maxLength: 36
      example: f47ac10b-58cc-4372-a567-0e02b2c3d479
    x-trace-id:
      x-global: true
      description: Unique trace identifier assigned by Wise. Useful when contacting support about a specific request.
      schema:
        type: string
      example: fba501b6d453b96789f52338f019341f
  responses:
    '429':
      x-global: true
      description: Rate limit exceeded. Retry after the number of seconds specified in the `Retry-After` header.
      headers:
        Retry-After:
          description: Number of seconds to wait before retrying the request.
          schema:
            type: integer
          example: 5
        X-Rate-Limited-By:
          description: Identifies the rate limiter that triggered the 429 response.
          schema:
            type: string
          example: wise-public-api
        X-External-Correlation-Id:
          $ref: '#/components/headers/X-External-Correlation-Id'
        x-trace-id:
          $ref: '#/components/headers/x-trace-id'
      content:
        application/json:
          schema:
            type: object
  securitySchemes:
    UserToken:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'User Access Token for making API calls on behalf of a Wise user.


        Can be obtained via two OAuth 2.0 flows:

        - **registration_code grant**: For partners creating users via API

        - **authorization_code grant**: For partners using Wise''s authorization page


        Access tokens are valid for 12 hours and can be refreshed using a refresh token.

        '
    PersonalToken:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Personal API Token for individual personal or small business users.

        Generated from Wise.com > Settings > Connect and manage apps > API tokens.

        Has limited API access compared to OAuth tokens (PSD2 restrictions apply for EU/UK users).

        '
    ClientCredentialsToken:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Application-level token for partner operations that don''t require a specific user context, such as bulk settlement and card spend controls.


        Obtained via `POST /oauth/token` with Basic Authentication (client-id:client-secret) and `grant_type=client_credentials`.


        Valid for 12 hours. No refresh token — fetch a new token when expired.


        See [create an OAuth token](/api-reference/oauth-token/oauthtokencreate) for details.

        '
    BasicAuth:
      type: http
      scheme: basic
      description: 'Basic Authentication using your Client ID and Client Secret as the username and password.


        Client credentials are provided by Wise when your partnership begins. See [Getting Started](/guides/developer) for details.

        '
x-tagGroups:
- name: Authentication
  tags:
  - oauth-token
- name: Enhanced Security
  tags:
  - jose
- name: Users
  tags:
  - user
  - claim-account
- name: Profiles
  tags:
  - profile
  - activity
  - address
- name: Verification
  tags:
  - kyc-review
  - verification
  - facetec
- name: Strong Customer Authentication
  tags:
  - sca-ott
  - sca-sessions
  - sca-pin
  - sca-facemaps
  - sca-device-fingerprints
  - sca-otp
  - user-security
- name: Balances
  tags:
  - balance
  - balance-statement
  - bank-account-details
  - multi-currency-account
- name: Cards
  tags:
  - card
  - card-sensitive-details
  - 3ds
  - card-kiosk-collection
  - card-order
  - card-transaction
  - spend-limits
  - spend-controls
  - digital-wallet
  - disputes
- name: Quotes
  tags:
  - quote
  - rate
  - comparison
- name: Recipients
  tags:
  - recipient
  - contact
- name: Transfers
  tags:
  - transfer
  - delivery-estimate
  - currencies
  - batch-group
- name: Funding
  tags:
  - payin-deposit-detail
  - direct-debit-account
  - bulk-settlement
  - payins
- name: Webhooks
  tags:
  - webhook
  - webhook-event
- name: Simulations
  tags:
  - simulation
- name: Partner Support
  tags:
  - case