---
swagger: "2.0"
info:
  x-ibm-name: otp-request-api
  title: OTP Request API
  version: 1.0.0
  description: This API allows the client to request for an OTP (One Time Password)
    to be generated and sent to the customer's registered mobile no. For validating
    the OTP entered by the customer on the client's mobile or web application,
    the OTP should be passed along with other parameters in the ValidateOTP operation.
    When the customer clicks on "Resend OTP" option on the App, the request
    should be sent to the RegenerateOTP operation.
  contact:
    name: API Developer
    email: apideveloper@rakbank.ae
  name: ""
schemes:
- https
host: testapi.rakbank.ae
basePath: /v1
consumes:
- application/json
produces:
- application/json
securityDefinitions:
  oauth:
    type: oauth2
    description: ""
    flow: application
    scopes:
      otp_request: To Request for a One-Time-Password
    tokenUrl: https://testapi.rakbank.ae/sb/api/v1/int_client_auth/token
  clientIdHeader:
    type: apiKey
    in: header
    name: X-IBM-Client-Id
security:
- clientIdHeader: []
  oauth:
  - otp_request
x-ibm-configuration:
  testable: true
  enforced: true
  phase: realized
paths:
  /otp_request/{req_reference_no}/generate_and_send:
    post:
      responses:
        200:
          description: 200 OK
          schema:
            $ref: '#/definitions/generate_otp_response'
        401:
          description: Unauthorized
          schema:
            $ref: '#/definitions/error_response'
        403:
          description: Forbidden
          schema:
            $ref: '#/definitions/error_response'
        422:
          description: Invalid Request/Unprocessable Entity
          schema:
            $ref: '#/definitions/error_response'
        500:
          description: Internal Server Error
          schema:
            $ref: '#/definitions/error_response'
      parameters:
      - name: generate_otp_request
        required: true
        in: body
        schema:
          $ref: '#/definitions/generate_otp_request'
        description: Request details to generate an OTP.
      - $ref: '#/parameters/MsgId'
      description: Request for an OTP to be generated and sent to customer's registered
        mobile number.
      summary: Generate OTP request
      operationId: GenerateOTP
    parameters:
    - $ref: '#/parameters/req_reference_no'
    - $ref: '#/parameters/MsgId'
  /otp_request/{req_reference_no}/regenerate_and_send:
    post:
      responses:
        200:
          description: 200 OK
          schema:
            $ref: '#/definitions/generate_otp_response'
        401:
          description: Unauthorized
          schema:
            $ref: '#/definitions/error_response'
        403:
          description: Forbidden
          schema:
            $ref: '#/definitions/error_response'
        422:
          description: Invalid Request/Unprocessable Entity
          schema:
            $ref: '#/definitions/error_response'
        500:
          description: Internal Server Error
          schema:
            $ref: '#/definitions/error_response'
      parameters:
      - name: generate_otp_request
        required: true
        in: body
        schema:
          $ref: '#/definitions/generate_otp_request'
        description: Request details to regenerate OTP.
      - $ref: '#/parameters/MsgId'
      description: Request for an OTP to be regenerated and sent to customer's registered
        mobile number.
      summary: Regenerate OTP request
      operationId: RegenerateOTP
    parameters:
    - $ref: '#/parameters/req_reference_no'
    - $ref: '#/parameters/MsgId'
  /otp_request/{req_reference_no}/validate:
    post:
      responses:
        204:
          description: No Content
        401:
          description: Unauthorized
          schema:
            $ref: '#/definitions/error_response'
        403:
          description: Forbidden
          schema:
            $ref: '#/definitions/error_response'
        422:
          description: Invalid Request/Unprocessable Entity
          schema:
            $ref: '#/definitions/error_response'
        500:
          description: Internal Server Error
          schema:
            $ref: '#/definitions/error_response'
      parameters:
      - name: generate_otp_request
        required: true
        in: body
        schema:
          $ref: '#/definitions/validate_otp_request'
        description: Request details to regenerate OTP.
      - $ref: '#/parameters/MsgId'
      description: This operation is used for validating the OTP entered by the customer
        on the client's mbile or web application. The OTP should be sent along with
        other details of the customer which must match the details that was sent while
        generating OTP.
      summary: Validate OTP request
      operationId: ValidateOTP
    parameters:
    - $ref: '#/parameters/MsgId'
    - $ref: '#/parameters/req_reference_no'
definitions:
  generate_otp_request:
    type: object
    description: This is request body for the OTP Generation Operation.
    properties:
      otp_type:
        type: string
        maxLength: 50
        description: This field will have the OTP Service name.
        enum:
        - DigInvestmentAccount
        - DigInvestmentCreditCard
      to:
        $ref: '#/definitions/to'
      otp_metadata:
        $ref: '#/definitions/otp_metadata'
    required:
    - otp_type
    - to
    - otp_metadata
  to:
    properties:
      customer_id_type:
        type: string
        enum:
        - CIF_ID
        description: Type of the Customer id of the customer to whom OTP needs to
          be sent. Allowed values - CIF_ID
        example: CIF_ID
      customer_id:
        type: string
        maxLength: 15
        minLength: 1
        pattern: ^\d+$
        example: 1234567
        description: Customer id of the customer, corresponding to the customer_id_type
          to whom OTP needs to be sent.
      customer_type:
        type: string
        maxLength: 1
        description: This field will have the Customer Type for which the OTP request
          is being generated. Validation for OTP generation are based on Customer
          Type. Customer Type  R - Retail, S - SME and C - Corporate
        default: R
        enum:
        - C
        - R
        - S
    additionalProperties: false
    required:
    - customer_id
    - customer_id_type
    - customer_type
    description: This will contain the details of the remitter
  otp_metadata:
    type: object
    description: This field will have information which will be used for OTP generation,
      validation and re-generation depending upon the OTP Type.
    properties:
      account_type:
        type: string
        description: This field should have the indicator for Customer's Creditcard
          No or Account No for which the OTP is being generated.
        enum:
        - C
        - A
        example: C
      account_id:
        type: string
        maxLength: 16
        pattern: ^\d+$
        example: 1234567890123
        description: This field should have the Customer's Account No. It is mandatory
          in generate, regenerate and validate OTP operations for Account/Debit Card
          Payment.
      value:
        $ref: '#/definitions/value'
        description: This field should have the Amount.
      masked_credit_card:
        type: string
        maxLength: 16
        pattern: ^\d{0,4}\*\*\*\*\*\*\*\*\d{0,4}$
        description: This field should have masked Credit Card No. It is mandatory
          in generate, regenerate and validate OTP operations for Credit Card. Except
          for first 4 and last 4 digits of the card, all other digits should be passed
          as '*'.
        example: 5123********3225
    required:
    - account_type
    - value
  value:
    properties:
      currency:
        type: string
        maxLength: 3
        enum:
        - AED
        - USD
        description: Currency
        example: AED
      amount:
        type: string
        pattern: ^\d{0,16}.\d{0,3}$
        description: 'Amount Value. Number (16,3). [ Mantissa (16), Decimal Precision
          (3), excluding dot]. Example: 50.05 AED'
        example: 50.050000
    additionalProperties: false
    required:
    - currency
    - amount
    description: Amount details
  generate_otp_response:
    type: object
    properties:
      otp_reference_no:
        type: string
        description: Reference number generated by bank for this request.
        maxLength: 256
      otp_generated_date:
        type: string
        format: date-time
        example: "2020-08-10T15:28:43.717Z"
        description: The OTP generated timestamp
      otp_expiry_date:
        type: string
        format: date-time
        example: "2020-08-10T15:38:43.717Z"
        description: The expiry date and time for the OTP.
  validate_otp_request:
    type: object
    description: This is request body for the OTP Generation Operation.
    properties:
      otp_type:
        type: string
        maxLength: 50
        description: This field will have the OTP Service name.
        enum:
        - DigInvestmentAccount
        - DigInvestmentCreditCard
      to:
        $ref: '#/definitions/to'
      otp_metadata:
        $ref: '#/definitions/otp_metadata'
      otp:
        type: string
        maxLength: 6
        description: This field should have the OTP value which was sent to the customer.
          This field will be used during OTP Validation
    required:
    - otp_type
    - to
    - otp
    - otp_metadata
  error_response:
    properties:
      status:
        type: string
        description: HTTP Status
        example: "422"
      response_code:
        type: string
        description: API specific error code
        example: "24001"
      property:
        type: string
      response_message:
        type: string
        description: brief type of the error
        example: Business Exception
      description:
        type: string
        description: detailed description of the error
        example: OTP expired
    additionalProperties: false
    required:
    - response_code
    - status
    - response_message
    description: Response in case of error
tags: []
parameters:
  MsgId:
    name: MsgId
    type: string
    maxLength: 50
    required: true
    in: header
    description: Unique Id sent by the client. Value should be a unique identifier
      of the request in UUID format
  req_reference_no:
    name: req_reference_no
    type: string
    required: true
    in: path
    maxLength: 30
    description: The transaction Reference No from the client.
x-ibm-endpoints:
- endpointUrl: https://sandboxapi.rakbank.ae/sb/api
  type:
  - production
  - development
...