openapi: 3.2.0
info:
  version: v1
  title: MTN Accountholders Validate an Individual's Account Status API
  contact:
    name: MTN API Support
    email: api.support@mtn.com
  description: The Accountholders API returns basic information of the Accountholder including MTN Mobile Money account status. i.e. ACTIVE, SUSPENDED, BLOCKED etc. It also support validation of a MoMo accountholder, as well as the verification of financial resourceinformation.
servers:
- url: https://api.mtn.com/v1
security:
- OAuth2: []
tags:
- name: Validate an Individual's Account Status
paths:
  /accountholders/{id}/validate:
    get:
      tags:
      - Validate an Individual's Account Status
      summary: Validate an accountholder's account status
      description: Validates the account status of a MoMo customer. By supplying the customer's id to validate, MADAPI will send the reques tto the backend system and map the response back to a boolean which will indicate whether the customer is a valid MoMo customer on ECW
      parameters:
      - name: id
        in: path
        description: ID value of the Accountholder i.e. MSISDN - the format must be E.123, resource or accountholderid can be passed if targetSystem is EWP
        required: true
        schema:
          type: string
      - name: transactionId
        description: Transaction ID or Session ID if target system is EWP
        in: header
        required: false
        schema:
          type: string
      - name: X-Authorization
        in: header
        description: Encrypted ECW credentials
        required: true
        schema:
          type: string
      - name: accountNumber
        in: query
        x-example: '2222000000012345'
        description: An optional customer account number
        schema:
          type: string
      - name: channelId
        in: query
        description: Channel code or ID
        x-example: '1'
        schema:
          type: string
      - name: targetSystem
        in: query
        description: The target system or the backend system
        x-example: EWP
        schema:
          type: string
      - name: validationType
        in: query
        description: The action or type of validation the API call is suppose to undertake.
        x-example: ELIGIBILITY
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountholderStatus'
        '400':
          description: Bad Request
          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'
        '405':
          description: Method No Allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '406':
          description: Not acceptable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '415':
          description: Unsupported Media Type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    AccountholderStatus:
      type: object
      properties:
        statusCode:
          type: string
          description: HTTP error code extension
        statusMessage:
          type: string
          description: Status description of the response
        customerId:
          type: string
          example: MTN123456
          description: Id provided in the input
        sequenceNo:
          type: string
          example: 1234
          description: A unique id for tracing all requests
        data:
          $ref: '#/components/schemas/validationData'
        _links:
          $ref: '#/components/schemas/AccountholderStatusResponse__links'
    AccountholderProfileResponse__links:
      type: object
      properties:
        self:
          $ref: '#/components/schemas/AccountholderProfileResponse__links_self'
      description: Relevant links to the Accoutholder Profile.
    AccountholderStatusResponse__links:
      type: object
      properties:
        self:
          $ref: '#/components/schemas/AccountholderStatusResponse__links_self'
      description: Relevant links to the Accoutholder Profile.
    validationData:
      type: object
      properties:
        firstName:
          type: string
          description: First Name of the customer
          example: John
        lastName:
          type: string
          description: Last Name of the customer
          example: Doe
        gender:
          type: string
          description: Gender of the customer
          example: FEMALE
        dateOfBirth:
          type: string
          description: Date of birth of the customer
          example: '1992-12-17'
        isValid:
          type: boolean
          description: Indicates whether the accountholder is validated. True = yes.
          example: false
        extension:
          type: array
          description: List of additional values returned from the provider system
          items:
            type: string
    AccountholderStatusResponse__links_self:
      type: object
      properties:
        href:
          type: string
          example: https://host:port/v1/accountholderstatus/12345
          description: Hyperlink to access the Accountholder's Status.
    AccountholderProfileResponse__links_self:
      type: object
      properties:
        href:
          type: string
          example: https://host:port/v1/accountholders/12345
          description: Hyperlink to access the Accountholder's Profile.
    Error:
      type: object
      required:
      - statusCode
      - statusMessage
      properties:
        timestamp:
          type: string
          format: date-time
          description: Timestamp when the error occured.
          example: 2018-05-01T00:00
        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'
        statusMessage:
          type: string
          description: More details and corrective actions related to the error which can be shown to a client.
        supportMessage:
          type: string
          description: Support Message
        customerId:
          type: string
          description: Customer ID or msisdn
        sequenceNo:
          type: string
          description: A unique id for tracing all requests
          example: 12345
        transactionId:
          type: string
          description: Message ID
        _links:
          $ref: '#/components/schemas/AccountholderProfileResponse__links'
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          scopes: {}
          tokenUrl: https://api.mtn.com/v1/oauth/access_token