Wise Sca Otp API

openapi: 3.2.0
info:
  title: Wise Platform Sca Otp API
  version: ''
  description: The Wise Platform API is a REST-based interface that enables programmatic access to Wise's payment infrastructure.
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.
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 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.'
      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 for more information.

        2. Trigger SMS Challenge 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 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.'
      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 for more information.

        2. Trigger WhatsApp Challenge 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 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.'
      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 for more information.

        2. Trigger Voice Challenge 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:
  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
  headers:
    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
    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
  schemas:
    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
    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.
  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
  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