openapi: 3.0.1
info:
  title: Sms Channel Service API Specification
  description: |
    This page describes how to integrate with the **SMS Channel Service** on a technical level.

    This service is a specialized downstream service, typically called by the central Notification Service. Its sole
    responsibility is to handle the formatting and dispatching of SMS notifications.

    -----

    ## REST Resources

    The SMS Channel Service provides a single resource for sending an **SMS notification**.

    ### The SMS Notification Resource

    An **SMS notification** request defines the content to be sent to a user's mobile device. It consists of:
    * **`reference`**: A unique ID for tracking this specific send request.
    * **`sender`**: The sender ID, which can be a brand name (e.g., "Banqup") or a short code.
    * **`phoneNumber`**: The recipient's mobile number, preferably in E.164 format.
    * **`message`**: The text content of the SMS.

    An example of an **SMS notification request** in JSON format:

    ```json
    {
      "reference": "tx_12345_abc",
      "sender": "Banqup",
      "phoneNumber": "+447123456789",
      "message": "Your verification code is 54321."
    }
    ```

    When this SMS is successfully queued for sending, the service returns a unique **notificationId**:

    ```json
    {
      "notificationId": "a1b2c3d4-e5f6-7890-1234-567890abcdef"
    }
    ```

    -----

    ## Sending an SMS

    To send a new SMS, you'll perform a **POST** request to the [**/core/sms/v1/smses
    **](../../../docs/communication/sms/send-sms) endpoint, providing the full SMS
    notification object in the request body.

    ```http
    POST /v1/notifications/sms
    Content-Type: application/json

    {
      "reference": "tx_12345_abc",
      "sender": "Banqup",
      "phoneNumber": "+447123456789",
      "message": "Your verification code is 54321."
    }
    ```

    A successful response (HTTP `202 Accepted`) will return the `notificationId` confirming the SMS has been
    accepted for delivery.

    -----

    ## Security

    Access to send SMS messages is controlled by the **`sms_send`** security scope. All requests to the SMS Channel API
    must be authenticated using an OAuth security scheme and include a token with the required scope.
  version: 2.1.22
servers:
- description: ''
  url: https://api.uat.btx.fr.banqup.com/core/sms
- description: ''
  url: https://api.uat.btx.eu.banqup.com/core/sms
paths: {}
components:
  schemas:
    SmsNotification:
      required:
      - message
      - reference
      - sender
      type: object
      properties:
        reference:
          minLength: 1
          type: string
          description: A unique reference for this notification request.
          example: tx_12345_abc
        sender:
          minLength: 1
          type: string
          description: The sender ID (e.g., a short code or brand name).
          example: Banqup
        phoneNumber:
          pattern: \+\d{1,3}\d{4,14}
          type: string
          description: The recipient's mobile phone number, preferably in E.164 format.
          example: '+447123456789'
        message:
          minLength: 1
          type: string
          description: The text content of the SMS message.
          example: Your verification code is 54321.
      description: Request body to send an SMS notification.
      example:
        reference: tx_12345_abc
        sender: Banqup
        phoneNumber: '+447123456789'
        message: Your verification code is 54321.
    SmsNotificationResponse:
      required:
      - notificationId
      type: object
      properties:
        notificationId:
          minLength: 1
          type: string
          description: The unique identifier assigned to the notification.
          format: uuid
          example: a1b2c3d4-e5f6-7890-1234-567890abcdef
      description: Response containing the unique identifier of the SMS notification.
      example:
        notificationId: a1b2c3d4-e5f6-7890-1234-567890abcdef
    ApiErrorProblemDetail:
      required:
      - error
      - requestId
      - timestamp
      type: object
      properties:
        status:
          type: integer
          format: int32
        error:
          type: string
        requestId:
          type: string
        timestamp:
          type: string
          format: date-time
        type:
          type: string
          format: uri
        title:
          type: string
        detail:
          type: string
        instance:
          type: string
          format: uri
        problems:
          type: array
          items:
            $ref: '#/components/schemas/NestedProblem'
        properties:
          type: object
          additionalProperties:
            type: object
    NestedProblem:
      required:
      - detail
      - error
      - title
      type: object
      properties:
        error:
          type: string
        title:
          type: string
        detail:
          type: string
        type:
          type: string
          format: uri
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.uat.btx.fr.banqup.com/oauth2/client_credential/gettoken
          scopes:
            info: Scopes are endpoint-specific, see each endpoint for required scope.
        authorizationCode:
          authorizationUrl: https://api.uat.btx.fr.banqup.com/oauth2/auth
          tokenUrl: https://api.uat.btx.fr.banqup.com/oauth2/token
          scopes:
            info: Scopes are endpoint-specific, see each endpoint for required scope.
