MTN Group Callmeback API

openapi: 3.2.0
info:
  description: callmeback API  will be used to post a request in AYO, when initiated by  Users via different Applications like "portal", "IVR" etc.
  version: v1.0
  title: V1 Callmeback API
servers:
- url: https://za.api.mtn.com
security:
- ApiKeyAuth: []
- OAuth2: []
tags:
- name: Callmeback
paths:
  /ayo/v1/callmeback:
    post:
      tags:
      - Callmeback
      description: Accept a callmeback request and send to downstream system layer.
      operationId: callmebackUsingPOST
      parameters:
      - name: transactionId
        in: header
        description: transactionId is unique id sent by 3pp to track the request.
        schema:
          type: string
      - name: x-origin-channelId
        in: header
        description: provides informtion source system(3PP) like 'MTNWeb', 'IVR','MoMoAPP', 'USSD'
        required: true
        schema:
          type: string
      - name: transactionDate
        in: header
        description: '2020-08-12T12:05:36.484Z'
        required: true
        schema:
          type: string
      - name: targetSystem
        in: header
        description: AYO-MTN-ZAF
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
        '400':
          description: Business Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CallMeBackRequest'
        description: Callmeback data
        required: true
components:
  schemas:
    Error:
      type: object
      required:
      - statusCode
      - statusMessage
      - transactionId
      - supportMessage
      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.
          example: '1000'
        statusMessage:
          type: string
          description: More details and corrective actions related to the error which can be shown to a client mapped to message from AYO Response
        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), mapped to description from the response of AYO
        transactionId:
          type: string
          description: This is the same transactionId that is sent in the request
          example: cdfa7bc3-cbcd-473b-a743-4fc90dcc91e4
        path:
          type: string
          description: The path that caused the error
          example: /test/27831234567
        method:
          type: string
          description: The HTTP method type that was used
          example: POST
        type:
          type: string
          example: business error
          description: type of error is shown for non 200 response and mapped from AYO response
    CallMeBackRequest:
      required:
      - id
      - idType
      - name
      - reason
      - information
      description: Callmeback
      properties:
        id:
          description: id is a string which countains a value, if  id is msisdn (MADAPI Encrypts msisdn as per AYO encryption Requirement), In the logs Msisdn can be shown as encrypted and nonencrypted format(DTqlExQCSuW7K+hoes45mg==)
          example: '2345676788'
          type: string
        idType:
          enum:
          - MSISDN
          type: string
          description: type of id
          example: MSISDN
        information:
          type: string
          $ref: '#/components/schemas/information'
    information:
      type: object
      description: defines all the fields for callmeback request for AYO
      required:
      - name
      - reason
      properties:
        name:
          description: Name of the user sent by channel as a string.(Maxlength-30,Minlength-2)
          example: John Smith
        reason:
          type: string
          enum:
          - Claim related
          - Cover related
          - Payment related
          - Mobile number change
          - Other
          - Lead
          - Service Enqiry
          - Complaint
          description: Reasons for callmeback request, selected by user and sent to MADAPI by channels for IVR- 'Service Enquiry' and 'Complaint', for MTNWeb 'Claim related',  'Cover related','Payment related','Mobile Number Change','Other', for MoMoAPP and USSD 'Lead'
          example: claiam Query
        preferredTimeSlotCode:
          type: string
          description: TimeSlots are selected by users and Sent MADAPI and below logic is applied to define Timeslot and is sent to southbound system Morning(8AM-12PM),Afternoon(12PM-6PM) and 'Unknown', if no value is sent MADAPI sends as 'Unknown'
          example: Afternoon
        policyHolderMsisdn:
          type: string
          description: msisdn is  number sent by 3pp  (MADAPI Encrypts msisdn as per AYO encryption Requirement), In the logs Msisdn can be shown as encrypted and nonencrypted format(DTqlExQCSuW7K+hoes45mg==)
          example: '233456786'
        policyHolderIdNumber:
          type: string
          description: policyHolderIdNumber is a input value sent by channels to southbound system(AYO)(MADAPI Encrypts msisdn as per AYO encryption Requirement), In the logs Msisdn can be shown as encrypted and nonencrypted format(DTqlExQCSuW7K+hoes45mg==)
          example: SP19363JS
        description:
          type: string
          description: Free Text field for further information into the  reason descriptions,User can provide additional information
          example: 'Claims query '
        customerInfoShareConsent:
          type: boolean
          description: CustomerInfoShareConsent is a boolean value which will be sent by channels and  MADAPI Sends to backend
          example: 'true'
    Success:
      type: object
      required:
      - statusCode
      - statusMessage
      - transactionId
      - supportMessage
      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.
          example: '0000'
        statusMessage:
          type: string
          description: More details and corrective actions related to the error which can be shown to a client
          example: success
        transactionId:
          type: string
          description: This is the same transactionId that is sent in the request
          example: cdfa7bc3-cbcd-473b-a743-4fc90dcc91e4
        supportMessage:
          type: string
          example: success
          description: Message will hold success for 200 response
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      name: X-API-Key
      in: header
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          scopes: {}
          tokenUrl: https://api.mtn.com/v1/oauth/access_token