swagger: '2.0'
info:
  version: v1
  title: Accountholders 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.'
host: api.mtn.com
basePath: /v1
schemes:
  - https
securityDefinitions:
  OAuth2:
    type: oauth2
    flow: application
    tokenUrl: 'https://api.mtn.com/v1/oauth/access_token'
security:
  - OAuth2: []
consumes:
  - application/json
produces:
  - application/json
paths:
  '/accountholders/{id}':
    get:
      tags:
        - status
      summary: View accountholder's profile
      description: Retrieves the acountholder's profile of a MTN customer.
      produces:
        - application/json
      parameters:
        - name: id
          in: path
          description: ID value of the Accountholder i.e. MSISDN - the format must be E.123
          required: true
          type: string
        - name: transactionId
          description: Transaction ID
          in: header
          required: true
          type: string
        - name: includeoffnet
          description: Indicates whether to include offnet data in the response
          in: query
          required: false
          type: boolean
        - name: x-authorization
          in: header
          description: Encrypted ECW credentials
          required: false
          type: string
      responses:
        '200':
          description: Successful response
          schema:
            $ref: '#/definitions/AccountholderProfile'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/Error'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/Error'
        '403':
          description: Forbidden
          schema:
            $ref: '#/definitions/Error'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/Error'
        '405':
          description: Method No Allowed
          schema:
            $ref: '#/definitions/Error'
        '406':
          description: Not acceptable
          schema:
            $ref: '#/definitions/Error'
        '415':
          description: Unsupported Media Type
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/Error'
  '/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'
      produces:
        - application/json
      parameters:
        - name: id
          in: path
          description: ID value of the Accountholder i.e. MSISDN - the format must be E.123
          required: true
          type: string
        - name: transactionId
          description: Transaction ID
          in: header
          required: true
          type: string
        - name: X-Authorization
          in: header
          description: Encrypted ECW credentials
          required: false
          type: string
      responses:
        '200':
          description: Successful response
          schema:
            $ref: '#/definitions/AccountholderStatus'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/Error'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/Error'
        '403':
          description: Forbidden
          schema:
            $ref: '#/definitions/Error'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/Error'
        '405':
          description: Method No Allowed
          schema:
            $ref: '#/definitions/Error'
        '406':
          description: Not acceptable
          schema:
            $ref: '#/definitions/Error'
        '415':
          description: Unsupported Media Type
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/Error'
  '/accountholders/{id}/verify':
    post:
      tags:
        - Verify a Partner's FInancial Resources
      summary: Verify an accountholder's financial resource information.
      description: 'Verifies an accountholder''s (or list of accountholders) financial resource information.This is typically called before linking an accountholder to a specific resource in the consuming system. The response will return a boolean to indicate whether an accountholder and service resource is valid (true) in the service provider system. The extension variable is an open field where any additional information that needs to flow between the consumer and target system, can be specified.'
      produces:
        - application/json
      parameters:
        - name: id
          in: path
          description: 'ID value of the Accountholder in the Service Provider Systemi.e. MSISDN - the format must be E.123 - as this operation is typically used to link financial resources, the liset of accountholder id''s in the input model, will be verified against this partner id.'
          required: true
          type: string
        - name: transactionId
          description: 'Client generated Id to include for tracing requests, so that the API can easily trace the HTTP request all the way from a client to MTNs backend processes (via our proxies). Each time a request is made to an MTN API the client should include a unique request reference in the HTTP Header. The value must be between 5 and 20 characters, and consist of ASCII letters, digits, or the characters +, /, =, and -. Invalid or blank IDs will be ignored and replaced with generated ones. MTN may use this to detect duplicate transactions from the client, but this functionality is not always guaranteed, so clients must make their own efforts to prevent duplicate transactions. MTN will also log the transactionId in order to assist with debugging and to correlate transactions processed by the API to requests from the client.'
          in: header
          required: true
          type: string
        - name: X-Authorization
          in: header
          description: Encrypted ECW credentials
          required: false
          type: string
        - in: body
          name: body
          description: Request body
          required: true
          schema:
            $ref: '#/definitions/verifyRequest'
      responses:
        '200':
          description: Successful response
          schema:
            $ref: '#/definitions/AccountholderStatus'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/Error'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/Error'
        '403':
          description: Forbidden
          schema:
            $ref: '#/definitions/Error'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/Error'
        '405':
          description: Method No Allowed
          schema:
            $ref: '#/definitions/Error'
        '406':
          description: Not acceptable
          schema:
            $ref: '#/definitions/Error'
        '415':
          description: Unsupported Media Type
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/Error'
definitions:
  verifyRequest:
    type: object
    required:
      - identity
    properties:
      optInVerificationPerformed:
        type: boolean
        description: Consumer populates this value to indicate whether the it has performed opt in verification. The target system will base its response on this value.
        example: true
      identity:
        type: array
        description: 'The account holder''s list of identity values. These values will not be verified individually, but in it''s totality and return a response in isValid pertaining to the whole list. If one fails, the entire list verifies isValid= false, The complete list has to verify successfully, in order for isValid=true.'
        items:
          type: object
          properties:
            idType:
              type: string
              description: A valid identity type associated with the account holder.
              example: MSISDN
              enum:
                - ALIAS
                - EMAIL
                - EXT
                - ID
                - MSISDN
                - MPOS
                - USER
            idValue:
              type: string
              description: A valid identity value associated with the account holder.
              example: '22546370829'
      extension:
        type: array
        description: 'Any additional information the consumer wants to send down to the target system. MADAPI will not interrogate, transform or validate this element, will merely act as a pass-thru for this value.'
        items:
          type: object
          properties:
            extensionInformation:
              type: string
          
  AccountholderStatus:
    type: object
    properties:
      statusCode:
        type: string
        description: HTTP error code extension
      customerId:
        type: string
        example: MTN123456
        description: Id provided in the input
      data:
        $ref: '#/definitions/validationData'
      _links:
        $ref: '#/definitions/AccountholderStatusResponse__links'
  AccountholderStatusResponse__links:
    type: object
    properties:
      self:
        $ref: '#/definitions/AccountholderStatusResponse__links_self'
    description: Relevant links to the Accoutholder Profile.
  AccountholderStatusResponse__links_self:
    type: object
    properties:
      href:
        type: string
        example: 'https://host:port/v1/accountholderstatus/12345'
        description: Hyperlink to access the Accountholder's Status.
        
  validationData:
    type: object
    properties:
      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: object
          properties:
            extensionInformation:
              type: string
          
          
  AccountholderProfile:
    type: object
    properties:
      statusCode:
        type: string
        description: HTTP error code extension
      customerId:
        type: string
        example: MTN123456
        description: Id provided in the input
      data:
        $ref: '#/definitions/data'
      _links:
        $ref: '#/definitions/AccountholderProfileResponse__links'
  AccountholderProfileResponse__links:
    type: object
    properties:
      self:
        $ref: '#/definitions/AccountholderProfileResponse__links_self'
    description: Relevant links to the Accoutholder Profile.
  AccountholderProfileResponse__links_self:
    type: object
    properties:
      href:
        type: string
        example: 'https://host:port/v1/accountholders/12345'
        description: Hyperlink to access the Accountholder's Profile.
  data:
    type: object
    properties:
      identity:
        type: array
        description: The account holder's list of identity values.
        items:
          type: object
          properties:
            idType:
              type: string
              description: A valid identity type associated with the account holder.
              example: MSISDN
              enum:
                - ALIAS
                - EMAIL
                - EXT
                - ID
                - MSISDN
                - MPOS
                - USER
            idValue:
              type: string
              description: A valid identity value associated with the account holder.
              example: '22546370829'
      offnet:
        type: boolean
        description: Indicates whether the record is for an offnet customer.
        example: false
      firstName:
        type: string
        description: The account holder's first name.
        example: John
      lastName:
        type: string
        description: The account holder's last name.
        example: Doe
      profileName:
        type: string
        description: The account holder's profile name.
        example: Mobile Money User Profile
      employeeId:
        type: string
        description: The account holder's employee Id.
      fris:
        type: array
        description: 'The default Financial Resource Identifiers, if any, of the account holder, and their associated currencies'
        items:
          type: object
          properties:
            friType:
              type: string
              description: Defined FRI Type
              example: 'MSISDN, ALIAS, BANK, etc'
            currency:
              type: object
              description: The currency of the FRI.
              properties:
                code:
                  type: string
                  description: 'The currency, as an ISO 4217 formatted string.'
                  example: XOF
      loyaltyPointsAccountFri:
        type: string
        description: The loyalty points account FRI of the account holder.
        example: 'FRI:1040249/MM'
      acceptedtc:
        type: array
        description: The version of the terms and conditions that the account holder has accepted.
        items:
          type: object
          properties:
            acceptedtcversion:
              type: string
              description: The account holder's accepted tc version.
              example: v2
            dateTime:
              type: string
              format: date-time
              description: The account holder's accepted tc date.
              example: '2021-01-30T08:30:00Z'
      accountholderStatus:
        type: string
        example: ACTIVE
        enum:
          - ACTIVE
          - BLOCKED
          - CLOSED
          - CREATED
          - REGISTERED
          - REGISTERED_BLOCKED
          - REGISTERED_CLOSED
      bankDomainName:
        type: string
        description: The account holder's bank domain name.
        example: MFS
      homeChargingRegionName:
        type: string
        description: The account holder's home charging region name.
      accountholderType:
        type: string
        description: Account holder Type.
      hasParent:
        type: boolean
        description: Indicates if the account holder has a parent
        example: false
      languageCode:
        type: object
        description: The language code of the account holder.
        properties:
          code:
            type: string
      child:
        type: array
        description: The children of the account holder. Contains a subset of account holder information.
        items:
          $ref: '#/definitions/childrenData'
          
  childrenData:
    type: object
    properties:
      identity:
        type: array
        description: The account holder's list of identity values.
        items:
          type: object
          properties:
            idType:
              type: string
              description: A valid identity type associated with the account holder.
              example: MSISDN
              enum:
                - ALIAS
                - EMAIL
                - EXT
                - ID
                - MSISDN
                - MPOS
                - USER
            idValue:
              type: string
              description: A valid identity value associated with the account holder.
              example: '22546370829'
      offnet:
        type: boolean
        description: Indicates whether the record is for an offnet customer.
        example: false
      firstName:
        type: string
        description: The account holder's first name.
        example: John
      lastName:
        type: string
        description: The account holder's last name.
        example: Doe
      profileName:
        type: string
        description: The account holder's profile name.
        example: Mobile Money User Profile
      employeeId:
        type: string
        description: The account holder's employee Id.
      fris:
        type: array
        description: 'The default Financial Resource Identifiers, if any, of the account holder, and their associated currencies'
        items:
          type: object
          properties:
            friType:
              type: string
              description: Defined FRI Type
              example: 'MSISDN, ALIAS, BANK, etc'
            currency:
              type: object
              description: The currency of the FRI.
              properties:
                code:
                  type: string
                  description: 'The currency, as an ISO 4217 formatted string.'
                  example: XOF
      loyaltyPointsAccountFri:
        type: string
        description: The loyalty points account FRI of the account holder.
        example: 'FRI:1040249/MM'
      acceptedtc:
        type: array
        description: The version of the terms and conditions that the account holder has accepted.
        items:
          type: object
          properties:
            acceptedtcversion:
              type: string
              description: The account holder's accepted tc version.
              example: v2
            dateTime:
              type: string
              format: date-time
              description: The account holder's accepted tc date.
              example: '2021-01-30T08:30:00Z'
      accountholderStatus:
        type: string
        example: ACTIVE
        enum:
          - ACTIVE
          - BLOCKED
          - CLOSED
          - CREATED
          - REGISTERED
          - REGISTERED_BLOCKED
          - REGISTERED_CLOSED
      bankDomainName:
        type: string
        description: The account holder's bank domain name.
        example: MFS
      homeChargingRegionName:
        type: string
        description: The account holder's home charging region name.
      accountholderType:
        type: string
        description: Account holder Type.
      hasParent:
        type: boolean
        description: Indicates if the account holder has a parent
        example: false
      languageCode:
        type: object
        description: The language code of the account holder.
        properties:
          code:
            type: string        
          
  Error:
    type: object
    required:
      - code
      - reason
    description: 'Used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx).'
    properties:
      timestamp:
        type: string
        format: date-time
        description: Timestamp when the error occured.
        example: '2021-01-30T08:30:00Z'
      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
      transactionId:
        type: string
        description: Message ID
      _links:
        $ref: '#/definitions/AccountholderProfileResponse__links'