---
swagger: "2.0"
info:
  description: Generates and validate OTP through CitiMFA
  version: "1.0"
  title: XLG-SEC-P-BanamexOtpAuthentication
  x-ibm-name: api-77b82
basePath: /api
tags:
- name: OTP
  description: OTP Operations
schemes:
- https
paths:
  /v1/x-global/security/tele-marketing/otp/generate:
    post:
      tags:
      - OTP Telemarketing
      summary: Generate and send Telemarketing OTP to Customer's phone number via
        SMS to complete or authorize a transaction.
      description: This API allows to generate the one time password and delivers
        to the customer in order to do a confirmation in Telemarketing flow. One time
        password is 11 digits of length that are delivered to the customer, 3 of those
        are returned in the response to client application.
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: uuid
        in: header
        description: A 128 bit universally unique identifier (UUID) that you generate
          for every request and is used for tracking. It is recommended to use the
          output from Java UUID class or an equivalent.
        required: true
        type: string
        default: a7d1e304-83a9-4413-af97-62615e57eae66807840
      - name: Content-Type
        in: header
        description: Content-Types that are acceptable for the response. Currently
          we support application/json
        required: true
        type: string
        default: application/json
      - name: Accept-Language
        in: header
        description: HTTP Accept-Language header
        required: true
        type: string
        default: en-US
      - name: countryCode
        in: header
        description: 2 character ISO country code
        required: true
        type: string
        default: MX
      - name: businessCode
        in: header
        description: 3 character business code
        required: true
        type: string
        default: GCB
      - name: channelId
        in: header
        description: channel ID used by the user
        required: true
        type: string
        default: IVR
      - name: client_id
        in: header
        description: The client ID  you received during application registration in
          the developer portal
        required: true
        type: string
        default: iX4xW5lG0gD6cX3uI5qN3pF6yK5nY2kB0eY5tB3xQ4rD4fD2xO
      - name: Authorization
        in: header
        description: Authorization code generated in previous OAuth invocation
        required: true
        type: string
        default: iX4xW5lG0gD6cX3uI5qN3pF6yK5nY2kB0eY5tB3xQ4rD4fD2xO
      - in: body
        name: TelemarketingOTPRequest
        description: 'OTP request with required details to generate and send OTP to
          customer, custom messsage special characters allowed: ? ! # $ % & * + -
          / ^ _ { } @ [ ] ~ ( ), characters that needs to send in unicode format:
          < > ¿ ¡ ñ á é í ó ú ü, minimum message lenght: 1 character, maximum length
          per delivered message is 140 characters'
        required: true
        schema:
          $ref: '#/definitions/TelemarketingOTPRequest'
      responses:
        200:
          description: OTP sent successfully
          schema:
            $ref: '#/definitions/TelemarketingOTPResponse'
        400:
          description: (BAD REQUEST) - Request was not processed <table><tr><td>Type</td><td>Code</td><td>Details</td></tr><tr><td>invalid</td><td>invalidRequest</td><td>Missing
            or invalid Parameters</td></tr><tr><td>error</td><td>smsDeliveryFailed</td><td>SMS
            delivery failed</td></tr></table>
          schema:
            $ref: '#/definitions/ErrorResponse'
        401:
          description: (UNAUTHORIZED) - Request was not processed <table><tr><td>Type</td><td>Code</td><td>Details</td></tr><tr><td>error</td><td>unAuthorized</td><td>Unauthorized
            access to this resource</td></tr></table>
          schema:
            $ref: '#/definitions/ErrorResponse'
        403:
          description: (FORBIDDEN) - Unauthorized to perform the requested operation
            on resource <table><tr><td>Type</td><td>Code</td><td>Details</td><td>More
            Info</td></tr><tr><td>invalid</td><td>accessNotConfigured</td><td>The
            request operation is not configured to access this resource</td><td>Channel/Country/Business
            provided in the request is not supported currently</td></tr></table>
          schema:
            $ref: '#/definitions/ErrorResponse'
        500:
          description: (INTERNAL SERVER ERROR) - API Server Error <table><tr><td>Type</td><td>Code</td><td>Details</td></tr><tr><td>error</td><td>backendError</td><td>Failed
            during a call to backend service</td> </tr> <tr><tr><td>fatal</td><td>serverUnavailable</td><td>The
            request failed due to an internal error/server unavailability</td></tr></table>
          schema:
            $ref: '#/definitions/ErrorResponse'
  /v1/x-global/security/tele-marketing/otp/validate:
    post:
      tags:
      - OTP Telemarketing
      summary: This API validates telemarketing OTP token submitted by Customer.
      description: Validate 11 digit One Time Password, validating 3 digits stored
        in session and 8 digits remaining against CitiMFA validation service. A successful
        validation of the OTP means the customers have completed or authorize a transaction
        in behalf of them.
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: uuid
        in: header
        description: A 128 bit universally unique identifier (UUID) that you generate
          for every request and is used for tracking. It is recommended to use the
          output from Java UUID class or an equivalent.
        required: true
        type: string
        default: a7d1e304-83a9-4413-af97-62615e57eae66807840
      - name: sid
        in: header
        description: Session is generated and returned on the first API call as response
          header, which needs to be resent on succesive calls of same session
        required: true
        type: string
      - name: Content-Type
        in: header
        description: Content-Types that are acceptable for the response. Currently
          we support application/json
        required: true
        type: string
        default: application/json
      - name: Accept-Language
        in: header
        description: HTTP Accept-Language header
        required: true
        type: string
        default: en-US
      - name: countryCode
        in: header
        description: 2 character ISO country code
        required: true
        type: string
        default: MX
      - name: businessCode
        in: header
        description: 3 character business code
        required: true
        type: string
        default: GCB
      - name: channelId
        in: header
        description: channel ID used by the user
        required: true
        type: string
        default: IVR
      - name: client_id
        in: header
        description: The client ID  you received during application registration in
          the developer portal
        required: true
        type: string
        default: iX4xW5lG0gD6cX3uI5qN3pF6yK5nY2kB0eY5tB3xQ4rD4fD2xO
      - name: Authorization
        in: header
        description: Authorization code generated in previous OAuth invocation
        required: true
        type: string
        default: iX4xW5lG0gD6cX3uI5qN3pF6yK5nY2kB0eY5tB3xQ4rD4fD2xO
      - in: body
        name: ValidateOTPRequest
        description: Otp request with the required details to validate otp token.
        required: true
        schema:
          $ref: '#/definitions/ValidateTelemarketingOTPRequest'
      responses:
        200:
          description: OTP Successfully validated
        400:
          description: (BAD REQUEST) - Request was not processed <table><tr><td>Type</td><td>Code</td><td>Details</td></tr><tr><td>invalid</td><td>invalidRequest</td><td>Missing
            or invalid Parameters</td></tr><tr><td>error</td><td>OTP Token Invalid</td><td>OTP
            Token Invalid</td></tr><tr><td>error</td><td>OTP Token Expired</td><td>OTP
            Token Expired</td></tr></table>
          schema:
            $ref: '#/definitions/ErrorResponse'
        401:
          description: (UNAUTHORIZED) - Request was not processed <table><tr><td>Type</td><td>Code</td><td>Details</td></tr><tr><td>error</td><td>unAuthorized</td><td>Unauthorized
            access to this resource</td></tr></table>
          schema:
            $ref: '#/definitions/ErrorResponse'
        403:
          description: (FORBIDDEN) - Unauthorized to perform the requested operation
            on resource <table><tr><td>Type</td><td>Code</td><td>Details</td><td>More
            Info</td></tr><tr><td>invalid</td><td>accessNotConfigured</td><td>The
            request operation is not configured to access this resource</td><td>Channel/Country/Business
            provided in the request is not supported currently</td></tr></table>
          schema:
            $ref: '#/definitions/ErrorResponse'
        500:
          description: (INTERNAL SERVER ERROR) - API Server Error <table><tr><td>Type</td><td>Code</td><td>Details</td></tr><tr><td>error</td><td>backendError</td><td>Failed
            during a call to backend service</td> </tr><tr><td>fatal</td><td>serverUnavailable</td><td>The
            request failed due to an internal error/server unavailability</td></tr></table>
          schema:
            $ref: '#/definitions/ErrorResponse'
definitions:
  TelemarketingOTPRequest:
    type: object
    required:
    - customerId
    - messagePrefix
    - phoneNumber
    properties:
      customerId:
        type: string
        example: test_1234
        description: Login User ID
      phoneNumber:
        type: string
        example: "1111214678"
        description: The phone number of the user for which OTP needs to be delivered
      messagePrefix:
        type: string
        example: Citi Identification Code Service
        description: The string representing Prefix message
      messageSuffix:
        type: string
        example: Reply HELP for help STOP to cancel
        description: The string representing Postfix message
  ValidateTelemarketingOTPRequest:
    type: object
    required:
    - customerId
    - oneTimePasswordToken
    properties:
      customerId:
        type: string
        example: test_1234
        description: Login User ID
      oneTimePasswordToken:
        type: string
        example: A1B2C3D4E5F
        description: Alphanumeric One time password.
        minLength: 11
        maxLength: 11
  TelemarketingOTPResponse:
    type: object
    properties:
      oneTimePasswordToken:
        type: string
        example: ABC
        description: Prefix OTP is part of delivered customer token which needs to
          be kept at app side along with SID for validation, remaining digits are
          generated and send by CitiMFA.
        maxLength: 3
  ErrorResponse:
    required:
    - code
    - details
    - location
    - moreInfo
    - timestamp
    - type
    properties:
      type:
        type: string
        description: Invalid - Request did not confirm to the specification and was
          unprocessed and rejected. Please fix the value and try again
        enum:
        - error
        - warn
        - invalid
        - fatal
      code:
        type: string
        description: Error code which qualifies the error
      details:
        type: string
        description: Human readable explanation specific to the occurrence of the
          problem
      location:
        type: string
        description: The name of the field that resulted in the error
      moreInfo:
        type: string
        description: URI to human readable documentation of the error
      timestamp:
        type: string
        description: Timestamp of the error
x-ibm-configuration:
  enforced: true
  testable: true
  phase: realized
securityDefinitions:
  OAuth2 Application Flow:
    type: oauth2
    description: ""
    flow: application
    scopes:
      /api/v1: ""
    tokenUrl: https://api.banamex.com/mx-gcgapi/api/v1/oauth/token
  Client ID:
    type: apiKey
    description: ""
    in: header
    name: X-IBM-Client-Id
security:
- OAuth2 Application Flow:
  - /api/v1
  Client ID: []
x-ibm-endpoints:
- endpointUrl: https://api.banamex.com/mx-gcgapi
  type:
  - production
  - development
...