swagger: '2.0'
info:
  description: To facilitate the capability for customer to create/validate/change/reset Pin Information. 
  version: "v1.0"
  title: Customer PIN Management API

schemes:
  - https
host: api.mtn.com
basePath: /customerPinManagement/v1
consumes:
  - application/json;charset=utf-8
produces:
  - application/json;charset=utf-8

securityDefinitions:
  ApiKeyAuth:
    type: apiKey
    name: X-API-Key
    in: header
  OAuth2:
    type: oauth2
    flow: application
    tokenUrl: "https://api.mtn.com/v1/oauth/access_token/accesstoken?grant_type=client_credentials"

security:
  - ApiKeyAuth: []
  - OAuth2: []
    
paths:
  /customer/{customerId}/createPin:
    post:
      tags:
        - PIN
      summary: To create Pin customer will provide mandatory(customerId, secret, alternateNumber, securityQuestion, tncDetails,channel,transId) attributes. Also will provide emailID as optional input
      description: >- 
        create Pin Details, user must enter the MSISDN/Service Number of Customer, the PIN number, alternate mobile Number , Answer for the Security Question and valid channel id. Finally the user will enter the Unique Trans ID as per below format yyyymmddhhmmss<UniqueSequenceNumber> i.e 20200711123459103
      operationId: createCutomerPin
      parameters:
        - name: "transactionId"
          in: header
          description: 'Client generated Id to include for tracing requests.'
          type: string
          required: false
          x-example: '6f0bece6-7df3-4da4-af02-5e7f16e5e6fc'
        - name: customerId
          in: path
          required : true
          type: "string"
          description: "Customer id will be act as serviceNumber and it can Customer's msisdn, serviceId, accountId, or invoiceId."
        - name: countryCode
          in: header
          description: "Country ISO code. Must be ISO 3166-1 alpha-3 codes (It is a 3 character string)"
          required: false
          type: string
          enum:
            - NGA
            - UGA
            - ZAF
            - RWA
        - name: "secret"
          in: header
          description: 'PIN number to be set'
          type: string
          required: true
          x-example: '12345678910'   
        - name: "emailID"
          in: header
          description: 'Customer’s Email ID'
          type: string
          required: false
          x-example: 'sharma.anuj@tecnotree.com'   
        - name: "alternateNumber"
          in: header
          description: 'Customer alternate mobile Number'
          type: string
          required: false
          x-example: '12345678910'       
        - name: "securityQuestion"
          in: header
          description: 'What is your favourite Car?'
          type: string
          required: true
          x-example: 'User will enter the favourite car name' 
        - name: "securityAnswer"
          in: header
          description: 'give secured answer'
          type: string
          required: true
          x-example: 'BMW' 
        - name: "tncDetails"
          in: header
          description: 'Terms & Condition should be “1.0” or as configured for the channel'
          type: string
          required: true
          x-example: '1.0' 
        - name: "channel"
          in: header
          description: 'channel'
          type: string
          required: true
          x-example: '12345678910' 
         
          
      responses:
        '200':
          description: 'Success'
          schema:
            $ref: "#/definitions/CreatePinResponse"
        '400':
          description: "Bad Request"
          schema:
            $ref: "#/definitions/Error"
        '401':
          description: "Unauthorized"
          schema:
            $ref: "#/definitions/Error"
        '403':
          description: "Forbidden"
          schema:
            $ref: "#/definitions/Error"
        '404':
          description: "Customer not found"
          schema:
            $ref: "#/definitions/Error"
          examples:
            The services object/envelope will be null: >
              {
                "services": null
              }
        '405':
          description: "Method Not allowed"
          schema:
            $ref: "#/definitions/Error"
        '500':
          description: "Internal Server Error"
          schema:
            $ref: "#/definitions/Error"
            
  /customer/{customerId}/validatePin:
    get:
      tags:
        - PIN
      summary: To validate Pin  Details  user will enter (customerId, secret, channel, transId) Attributes
      description: >-
        To validate Pin Details, user must enter the MSISDN/Service Number of Customer, the PIN number, channel id. Finally the user will enter the Unique Trans ID as per below format yyyymmddhhmmss<UniqueSequenceNumber> i.e 20200711123459104
      operationId: validateCutomerPin
      parameters:
        - name: "transactionId"
          in: header
          description: 'Client generated Id to include for tracing requests.'
          type: string
          required: false
          x-example: '6f0bece6-7df3-4da4-af02-5e7f16e5e6fc'
        - name: customerId
          in: path
          required : true
          type: "string"
          description: "Customer id will be act as serviceNumber and it can Customer's msisdn, serviceId, accountId, or invoiceId."
        - name: countryCode
          in: header
          description: "Country ISO code. Must be ISO 3166-1 alpha-3 codes (It is a 3 character string)"
          required: false
          type: string
          enum:
            - NGA
            - UGA
            - ZAF
            - RWA
        - name: "secret"
          in: header
          description: 'PIN number to validate'
          type: string
          required: true
          x-example: '12345678910'       
        - name: "channel"
          in: header
          description: 'channel'
          type: string
          required: true
          x-example: '12345678910' 
      
          
      responses:
        '200':
          description: 'Success'
          schema:
            $ref: "#/definitions/ValidatePinResponse"
        '400':
          description: "Bad Request"
          schema:
            $ref: "#/definitions/Error"
        '401':
          description: "Unauthorized"
          schema:
            $ref: "#/definitions/Error"
        '403':
          description: "Forbidden"
          schema:
            $ref: "#/definitions/Error"
        '404':
          description: "Customer not found"
          schema:
            $ref: "#/definitions/Error"
          examples:
            The services object/envelope will be null: >
              {
                "services": null
              }
        '405':
          description: "Method Not allowed"
          schema:
            $ref: "#/definitions/Error"
        '500':
          description: "Internal Server Error"
          schema:
            $ref: "#/definitions/Error"

  
  /customer/{customerId}/changePin:
    put:
      tags:
        - PIN
      summary: To change Pin  Details user will enter (customerId, operationType, currentSecret, newSecret,channel,transId) Attributes
      description: >-
        To change Pin Details, user must enter the 'MSISDN/Service Number of Customer'. User has to enter the 'current Secret/PIN' and 'New Secret/PIN'. User will enter Security Answer selected during first time Secret/PIN Creation. Finally the user will enter the 'channel id' & 'Unique Trans ID as per below format yyyymmddhhmmss<UniqueSequenceNumber> i.e 20200711123459105
      operationId: changeCutomerPin
      parameters:
        - name: "transactionId"
          in: header
          description: 'Client generated Id to include for tracing requests.'
          type: string
          required: false
          x-example: '6f0bece6-7df3-4da4-af02-5e7f16e5e6fc'
        - name: customerId
          in: path
          required : true
          type: "string"
          description: "Customer id will be act as serviceNumber and it can Customer's msisdn, serviceId, accountId, or invoiceId."
        - name: countryCode
          in: header
          description: "Country ISO code. Must be ISO 3166-1 alpha-3 codes (It is a 3 character string)"
          required: false
          type: string
          enum:
            - NGA
            - UGA
            - ZAF
            - RWA
        - name: "currentSecret"
          in: header
          description: 'Customer’s Current Secret/PIN'
          type: string
          required: true
          x-example: '12345678910'   
        - name: "newSecret"
          in: header
          description: 'Customer’s New Secret/PIN'
          type: string
          required: true
          x-example: '12345678910'       
        - name: "securityAnswer"
          in: header
          description: 'give secured answer'
          type: string
          required: true
          x-example: 'BMW' 
        - name: "channel"
          in: header
          description: 'channel'
          type: string
          required: true
          x-example: '12345678910'
        - name: 'customerType'
          in: query
          description: "This can be an individual customer or a corporate customer. '0' refers to an individual customer and '1' refers to a corporate customer"
          type: integer
          required: false
          x-example: '0'
        - name: 'otp'
          in: header
          description: "OTP recieved by customer through sms or email"
          type: string
          required: false
          x-example: '0'
          
          
      responses:
        '200':
          description: 'Success'
          schema:
            $ref: "#/definitions/ChangePinResponse"
        '400':
          description: "Bad Request"
          schema:
            $ref: "#/definitions/Error"
        '401':
          description: "Unauthorized"
          schema:
            $ref: "#/definitions/Error"
        '403':
          description: "Forbidden"
          schema:
            $ref: "#/definitions/Error"
        '404':
          description: "Customer not found"
          schema:
            $ref: "#/definitions/Error"
          examples:
            The services object/envelope will be null: >
              {
                "services": null
              }
        '405':
          description: "Method Not allowed"
          schema:
            $ref: "#/definitions/Error"
        '500':
          description: "Internal Server Error"
          schema:
            $ref: "#/definitions/Error"

  /customer/{customerId}/resetPin:
    put:
      tags:
        - PIN
      summary: To reset Pin  Details user will enter (customerId, operationType, validateAnswers, motherName,dateOfBirth,stateOfOrigin,channel,transId) Attributes
      description: >- 
         To reset Pin Details, user must enter the 'MSISDN/Service Number of Customer'. User has to enter the Y-indicates validate security answer,
         N-indicates no validation for Validate Answers'. User will enter Mothers maiden name also will enter the Date of Birth in format YYYY-MM-DD and State of Origin code.
         Finally the user will enter the 'channel id' & 'Unique Trans ID as per below format yyyymmddhhmmss<UniqueSequenceNumber> i.e 20200711123459105
      operationId: resetCutomerPin
      parameters:
        - name: "transactionId"
          in: header
          description: 'Client generated Id to include for tracing requests.'
          type: string
          required: false
          x-example: '6f0bece6-7df3-4da4-af02-5e7f16e5e6fc'
        - name: customerId
          in: path
          required : true
          type: "string"
          description: "Customer id will be act as serviceNumber and it can Customer's msisdn, serviceId, accountId, or invoiceId."
        - name: countryCode
          in: header
          description: "Country ISO code. Must be ISO 3166-1 alpha-3 codes (It is a 3 character string)"
          required: false
          type: string
          enum:
            - NGA
            - UGA
            - ZAF
            - RWA 
        - name: "validateAnswers"
          in: header
          description: 'Y-indicates validate security answer, N-indicates no validation'
          type: string
          required: true
          x-example: 'Y'   
        - name: "motherName"
          in: query
          description: 'Mothers maiden name'
          type: string
          required: true
          x-example: 'abcd'       
        - name: "dateOfBirth"
          in: query
          description: 'Date of Birth in format YYYY-MM-DD'
          type: string
          required: true
          x-example: '2020-10-13' 
        - name: "stateOfOrigin"
          in: query
          description: 'State of Origin code'
          type: string
          required: true
          x-example: '+91'
        - name: "channel"
          in: header
          description: 'channel'
          type: string
          required: true
          x-example: '12345678910'                    
      responses:
        '200':
          description: 'Success'
          schema:
            $ref: "#/definitions/resetPinResponse"
        '400':
          description: "Bad Request"
          schema:
            $ref: "#/definitions/Error"
        '401':
          description: "Unauthorized"
          schema:
            $ref: "#/definitions/Error"
        '403':
          description: "Forbidden"
          schema:
            $ref: "#/definitions/Error"
        '404':
          description: "Customer not found"
          schema:
            $ref: "#/definitions/Error"
          examples:
            The services object/envelope will be null: >
              {
                "services": null
              }
        '405':
          description: "Method Not allowed"
          schema:
            $ref: "#/definitions/Error"
        '500':
          description: "Internal Server Error"
          schema:
            $ref: "#/definitions/Error"

  /customer/{customerId}/validateSecurityAnswer:
    get:
      tags:
        - PIN
      summary: To change Pin  Details user will enter (customerId, operationType, securityAnswer,channel,transId) Attributes
      description: >- 
       To change Pin Details, user must enter the 'MSISDN/Service Number of Customer'. User will enterSecurity Answer to be updated. Finally the user will enter the 'channel id' & 'Unique Trans ID as per below format yyyymmddhhmmss<UniqueSequenceNumber> i.e 20200711123459105
      operationId: validateSecurityCutomerPin
      parameters:
        - name: "transactionId"
          in: header
          description: 'Client generated Id to include for tracing requests.'
          type: string
          required: false
          x-example: '6f0bece6-7df3-4da4-af02-5e7f16e5e6fc'
        - name: customerId
          in: path
          required : true
          type: "string"
          description: "Customer id will be act as serviceNumber and it can Customer's msisdn, serviceId, accountId, or invoiceId."
        - name: countryCode
          in: header
          description: "Country ISO code. Must be ISO 3166-1 alpha-3 codes (It is a 3 character string)"
          required: false
          type: string
          enum:
            - NGA
            - UGA
            - ZAF
            - RWA     
        - name: "securityAnswer"
          in: header
          description: 'Security Answer to be updated'
          type: string
          required: true
          x-example: 'answer123' 
        - name: "channel"
          in: header
          description: 'channel'
          type: string
          required: true
          x-example: '12345678910' 
          
          
      responses:
        '200':
          description: 'Success'
          schema:
            $ref: "#/definitions/ValidateSecurityAnswerResponse"
        '400':
          description: "Bad Request"
          schema:
            $ref: "#/definitions/Error"
        '401':
          description: "Unauthorized"
          schema:
            $ref: "#/definitions/Error"
        '403':
          description: "Forbidden"
          schema:
            $ref: "#/definitions/Error"
        '404':
          description: "Customer not found"
          schema:
            $ref: "#/definitions/Error"
          examples:
            The services object/envelope will be null: >
              {
                "services": null
              }
        '405':
          description: "Method Not allowed"
          schema:
            $ref: "#/definitions/Error"
        '500':
          description: "Internal Server Error"
          schema:
            $ref: "#/definitions/Error" 
  /customer/{customerId}/chanageSecurityQnA:
    put:
      tags:
        - PIN
      summary: To change Pin  Details user will enter (customerId, operationType,securityQuestion,securityAnswer,channel) Attributes
      description: >-
        To change Pin Details, user must enter the 'MSISDN/Service Number of Customer'. User will enter Security Answer to be updated. Finally the user will enter the 'channel id'"
      operationId: chanageSecurityQnACutomerPin
      parameters:
        - name: "transactionId"
          in: header
          description: 'Client generated Id to include for tracing requests.'
          type: string
          required: false
          x-example: '6f0bece6-7df3-4da4-af02-5e7f16e5e6fc'
        - name: customerId
          in: path
          required : true
          type: "string"
          description: "Customer id will be act as serviceNumber and it can Customer's msisdn, serviceId, accountId, or invoiceId."
        - name: countryCode
          in: header
          description: "Country ISO code. Must be ISO 3166-1 alpha-3 codes (It is a 3 character string)"
          required: false
          type: string
          enum:
            - NGA
            - UGA
            - ZAF
            - RWA      
        - name: "securityQuestion"
          in: header
          description: 'What is your favourite Car?'
          type: string
          required: true
          x-example: 'User will enter the favourite car name' 
        - name: "securityAnswer"
          in: header
          description: 'give secured answer'
          type: string
          required: true
          x-example: 'BMW' 
        - name: "channel"
          in: header
          description: 'channel'
          type: string
          required: true
          x-example: '12345678910' 
          
          
      responses:
        '200':
          description: 'Success'
          schema:
            $ref: "#/definitions/ValidateSecurityAnswerResponse"
        '400':
          description: "Bad Request"
          schema:
            $ref: "#/definitions/Error"
        '401':
          description: "Unauthorized"
          schema:
            $ref: "#/definitions/Error"
        '403':
          description: "Forbidden"
          schema:
            $ref: "#/definitions/Error"
        '404':
          description: "Customer not found"
          schema:
            $ref: "#/definitions/Error"
          examples:
            The services object/envelope will be null: >
              {
                "services": null
              }
        '405':
          description: "Method Not allowed"
          schema:
            $ref: "#/definitions/Error"
        '500':
          description: "Internal Server Error"
          schema:
            $ref: "#/definitions/Error" 
  /customer/{customerId}/selfResetPin:
    post:
      tags:
        - PIN
      summary: Generate new user pin provided by the user
      description: >-
        This method is used to generate new pin , in case of existing pin is forgotten or  reset the default pin after first login. The generated pin will be user provided.
      operationId: createSelfPin
      parameters:
        - name: "customerType"
          in: query
          description: "This can be an individual customer or a corporate customer. '0' refers to an individual customer and '1' refers to a corporate customer"
          type: integer
          required: true
          enum:
            - 0
            - 1
          x-example: '0' 
        - name: customerId
          in: path
          required : true
          type: "string"
          description: "customerId can be serviceNumber (msisdn with country code), service id or email id . Service number will be passed as customerId if customerType is chosen as '0' , otherwise customerId will be passed as email id or service id " 
        - name: "otp"
          in: header
          description: 'OTP recieved by customer through sms or email'
          type: string
          required: true
          x-example: '12345678910'   
        - name: "newSecret"
          in: header
          description: 'Customer’s New Secret/PIN'
          type: string
          required: true
          x-example: '12345678910'       
        - name: "securityAnswer"
          in: header
          description: 'This should be passed as document number , like passport number/ national id etc, supplied at the time of registration or answer registered against the security question .'
          type: string
          required: true
          x-example: '12345678910' 
        - name: "transactionId"
          in: header
          description: 'Client generated Id to include for tracing requests.'
          type: string
          required: false
          x-example: '6f0bece6-7df3-4da4-af02-5e7f16e5e6fc'
        - name: countryCode
          in: header
          description: "Country ISO code. Must be ISO 3166-1 alpha-3 codes (It is a 3 character string)"
          required: false
          type: string
          enum:
            - NGA
            - UGA
            - ZAF
            - RWA 
        - name: "channel"
          in: header
          description: 'channel'
          type: string
          required: false
          x-example: '12345678910' 
          
          
      responses:
        '200':
          description: 'Success'
          schema:
            $ref: "#/definitions/ChangePinResponse"
        '400':
          description: "Bad Request"
          schema:
            $ref: "#/definitions/Error"
        '401':
          description: "Unauthorized"
          schema:
            $ref: "#/definitions/Error"
        '403':
          description: "Forbidden"
          schema:
            $ref: "#/definitions/Error"
        '404':
          description: "Customer not found"
          schema:
            $ref: "#/definitions/Error"
          examples:
            The services object/envelope will be null: >
              {
                "services": null
              }
        '405':
          description: "Method Not allowed"
          schema:
            $ref: "#/definitions/Error"
        '500':
          description: "Internal Server Error"
          schema:
            $ref: "#/definitions/Error"

definitions:

  ValidatePinResponse:
    type: object
    required:
      - name
    properties:
      statusCode:
        type: string
        example: "0000"
        description: "Success API code. '0000' in case of success"
      statusDescription:
        type: string
        example: "String" 
      transactionId:
        type: string
        example: "String"       
      data:
        type: object
        $ref: "#/definitions/ValidatePinResponseData" 
  ValidatePinResponseData:
    type: "object"
    title: "ValidatePinResponseData"
    properties:
      message:
        type: "string"        
        example: "Subscriber secret authenticated successfully"
        description: "API Success Message. i.e. Subscriber secret authenticated successfully"   
      forcePasswordChange:
        type: string
        example: "false"
        description: "true/false"
      securityQuestionAvailable:
        type: string
        example: "true"        
      emailID:
        type: string
        example: "sharma.anuj@tecnotree.com"
      tncAccepted:
        type: array
        items:
          type: string
        example: 
        - Version: "2.0"
          AcceptedDate: "2020-07-11T13:43:30.830Z"
      tncLastUpdtdate:
        type: string
        example: "2020-07-01T10:10:11.830Z" 
      tncLastUpdtversion:
        type: string
        example: "2.0"           
  ChangePinResponse:
    type: object
    required:
      - name
    properties:
      statusCode:
        type: string
        example: "0000"
        description: "Success API code. '0000' in case of success"
      statusDescription:
        type: string
        example: "String" 
      transactionId:
        type: string
        example: "String"       
      data:
        type: object
        $ref: "#/definitions/ChangePinResponseData" 
  ChangePinResponseData:
    type: "object"
    title: "ChangePinResponseData"
    properties:
      message:
        type: "string"        
        example: "Subscriber secret has been changed and SMS sent successfully"
        description: "API Success Message.i.e. Subscriber secret has been changed and SMS sent successfully"  
  resetPinResponse:
    type: object
    required:
      - name
    properties:
      statusCode:
        type: string
        example: "0000"
        description: "Success API code. '0000' in case of success"
      statusDescription:
        type: string
        example: "String" 
      transactionId:
        type: string
        example: "String"       
      data:
        type: object
        $ref: "#/definitions/ResetPinResponseData" 
  ResetPinResponseData:
    type: "object"
    title: "ResetPinResponseData"
    properties:
      message:
        type: "string"        
        example: "pin changed and SMS sent to customer Successfully"
        description: "API Success Message.i.e. Pin changed and SMS sent to customer Successfully"   
  ValidateSecurityAnswerResponse:
    type: object
    required:
      - name
    properties:
      statusCode:
        type: string
        example: "0000"
        description: "Success API code. '0000' in case of success"
      statusDescription:
        type: string
        example: "String" 
      transactionId:
        type: string
        example: "String"       
      data:
        type: object
        $ref: "#/definitions/ValidateSecurityAnswerResponseData" 
  ValidateSecurityAnswerResponseData:
    type: "object"
    title: "ValidateSecurityAnswerResponseData"
    properties:
      message:
        type: "string"        
        example: "Subscriber answer validated successfully"
        description: "API Success Message.i.e. Subscriber answer validated successfully" 
  chanageSecurityQnAResponse:
    type: object
    required:
      - name
    properties:
      statusCode:
        type: string
        example: "0000"
        description: "Success API code. '0000' in case of success"
      statusDescription:
        type: string
        example: "String" 
      transactionId:
        type: string
        example: "String"       
      data:
        type: object
        $ref: "#/definitions/chanageSecurityQnAData" 
  chanageSecurityQnAData:
    type: "object"
    title: "chanageSecurityQnAData"
    properties:
      message:
        type: "string"        
        example: "QA Updated Successfully"
        description: "API Success Message.i.e. QA Updated Successfully"    
  CreatePinResponse:
    type: object
    required:
      - name
    properties:
      statusCode:
        type: string
        example: "0000"
        description: "Success API code. '0000' in case of success"
      statusDescription:
        type: string
        example: "String" 
      transactionId:
        type: string
        example: "String" 
      data:
        type: object
        $ref: "#/definitions/CreatePinResponseData" 
  CreatePinResponseData:
    type: "object"
    title: "CreatePinResponseData"
    properties:
      message:
        type: "string"        
        example: "Subscriber secret created successfully"
        description: "API Success Message. i.e. Subscriber secret created successfully" 
  Error:
    type: object
    required:
      - "statusCode"
      - "statusMessage"
    properties:
      statusCode:
        type: string
        description: This is the MADAPI Canonical Error Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system errors are mapped to specific canonical error codes which are returned. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes'
        example: '1000'
      statusMessage:
        type: string
        description: More details and corrective actions related to the error which can be shown to a client
      supportMessage:
        type: string
        description: Internal message meant for consumers of the API to troubleshoot the error (could possible include the back-end system error code in the message if it would be useful)
      transactionId:
        type: string
        description: This is the same transactionId that is sent in the request
        example: 'cdfa7bc3-cbcd-473b-a743-4fc90dcc91e4'
      timestamp:
        type: string
        format: date-time
        description: Timestamp that the error occurred 
        example: '2020-08-01T12:34'
      path:
        type: string
        description: The path that caused the error
        example: '/customers/234805738473/pin'
      method:
        type: string
        description: The HTTP method type that was used
        example: 'GET'