openapi: 3.2.0 info: version: v1.11 title: MTN Customer Profiles Member Summary API description: An API to retrieve the profile of an MTN customer. Please refer to the reference guides https://developers.mtn.com/API-Reference-Guides and Response and Error Codes documents https://developers.mtn.com/ResponseCodes servers: - url: https://api.mtn.com/v2 security: - ApiKeyAuth: [] - OAuth2: [] tags: - name: Member Summary paths: /customers/{customerId}/summary: get: tags: - Member Summary summary: Member Summary description: Retrieves the acountholder's (member summary) from ayo . parameters: - name: customerId in: path description: ID value of the Accountholder/Customer i.e. MSISDN - ex-27123456788 required: true schema: type: string - name: id in: header description: id of the customer ex- SAID, Passportid etc schema: type: string - name: transactionDate in: header description: Transaction date ex '2022-06-03T14:19:38.996Z' schema: type: string - name: transactionId in: header description: transactionId is the unique identifier to track the request ex '202rtre5t5567trt67y89' schema: type: string - name: targetSystem in: header description: target system is backend for which the request is initiated ex- AYO-MTN-ZAF required: true schema: type: string - name: idType in: header description: idType defines the type of customerid ex- passport etc schema: type: string - name: x-origin-channelId in: header description: information on originator ex-USSD schema: type: string responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/ayoSummaryResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ayoSummaryError' '401': description: UnAuthorized content: application/json: schema: $ref: '#/components/schemas/ayoSummaryError' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ayoSummaryError' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ayoSummaryError' components: schemas: ayocoverDetails: type: object properties: benefit: type: string example: CARE365MYFAPH description: Benefits are the additions information given to the customer as defined by AYO policyNumber: type: string example: 7132669 description: Policy Number is string value defined in AYO policyStatus: type: string example: In Force description: Policy Status is defined in three different values 'Not Takenup', 'In Force', 'Termination Notice' productCode: type: string example: MyMTN Prepaid Funeral Khava description: product code is commercial name of the product used by the customer as defined in AYO consents: type: string description: consent example: y coverPeriod: type: integer example: 6 description: Policy Cover Period is numerical value which defines the duration calculated in months coverAmount: $ref: '#/components/schemas/ayoAmount' totalPremium: $ref: '#/components/schemas/ayoAmount' ayoAmount: type: object properties: amount: type: integer example: 3000 description: amount is numerical value defined in different features like premium and cover currencyCode: type: string example: ZAR description: Currecy code is currency in which amount is defined, for southAfrica it is ZAR ayoSummaryResponse: type: object required: - memberAggrementNumber - coverDetails 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 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 example: Success transactionId: type: string description: This is the same transactionId that is sent in the request example: cdfa7bc3-cbcd-473b-a743-4fc90dcc91e4 memberAggrementNumber: type: string example: 2120000059490612 description: Personal ID Number which is the unique value provided by ayo for every customer coverDetails: description: Cover details consist of all the information related to policy associated with the customer $ref: '#/components/schemas/ayocoverDetails' ayoSummaryError: type: object required: - statusCode - statusMessage - supportMessage - transactionId 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: '4001' statusMessage: type: string description: More details and corrective actions related to the error which can be shown to a client example: Bad request 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 example: No policy is found per the id number. 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: /27831234567/summary method: type: string description: The HTTP method type that was used example: GET type: type: string example: business error description: type of error is shown for non 200 response and mapped from AYO 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