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'