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.
swagger: "2.0"
info:
version: "v1"
title: "MTN 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"
consumes:
- "application/json"
produces:
- "application/json"
securityDefinitions:
OAuth2:
type: oauth2
flow: application
tokenUrl: https://api.mtn.com/v1/oauth/access_token
security:
- OAuth2: []
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: false
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: true
type: string
- name: targetSystem
in: query
type: string
description: "The target system or the backend system"
x-example: "EWP"
- name: validationType
in: query
type: string
description: "Enum of types of validations to be passed"
enum: [CHECK_ELIGIBILITY, MOMO,NextGen_PaymentGateway]
- name: segment
type: string
in: query
required: false
description: This is the type of customer doing the transaction. This can be [agent , admin, merchant,subscriber]
enum:
- subscriber
- admin
- agent
- merchant
x-example: subscriber
- name: idType
type: string
in: query
required: false
description: Type of the customerId in the path.
enum: [MSISDN, USER]
- name: nodeId
type: string
in: query
description: Node making the request
x-example: Comviva
- name: channel
type: string
x-example: "MyMTNAPP"
in: query
required: false
description: "Channel identifier"
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, resource or accountholderid can be passed if targetSystem is EWP"
required: true
type: "string"
- name: "transactionId"
description: "Transaction ID or Session ID if target system is EWP"
in: "header"
required: false
type: "string"
- name: X-Authorization
in: header
description: 'Encrypted ECW credentials'
required: true
type: string
- name: accountNumber
in: query
type: string
x-example: "2222000000012345"
description: "An optional customer account number"
- name: channelId
in: query
type: string
description: "Channel code or ID"
x-example: '1'
- name: targetSystem
in: query
type: string
description: "The target system or the backend system"
x-example: "EWP"
- name: validationType
in: query
type: string
description: "The action or type of validation the API call is suppose to undertake."
x-example: "ELIGIBILITY"
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
properties:
accountholderids:
type: array
items:
type: string
extension:
type: object
resource:
type: string
title: VerifyRequest
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: '#/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:
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
AccountholderProfile:
type: "object"
properties:
statusCode:
type: string
description: HTTP error code extension
statusMessage:
type: string
description: Message of the transaction. Either Success or Failure.
transactionId:
type: string
description: Unique identifier for every request to the backend. Mapped from input request.
example: 5345345
customerId:
type: string
example: MTN123456
description: Id provided in the input, could be an MSISDN or an account id that was used in getting the info.
sequenceNo:
type: string
description: A unique id used in tracing all requests
example: 12345
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. eg. Internal identity code associated with the account holder"
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. eg. ID:470007/ID. etc"
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 or surname."
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: "2018-05-01T00:00"
accountholderStatus:
type: "string"
description: "Status of the currently queried account holder"
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"
parentAttributes:
type: "array"
description: Parent attributes
items:
$ref: "#/definitions/ParentAttributes"
languageCode:
type: "object"
description: "The language code of the account holder."
properties:
code:
type: "string"
OpenWallet:
type: "object"
description: "Describes the payload to sent by a 3PP for opening an account"
properties:
msisdn:
type: string
description: The MSISDN of the wallet to be created
maxLength: 16
example: 234039994032
msisdnVerificationCode:
type: string
description: OTP to the validate mobile number or MSISDN
maxLength: 64
example: "03904"
username:
type: string
description: A valid unique username the account holder have registered for verification
maxLength: 64
example: "EWP"
emailVerificationCode:
type: string
description: OTP to the validation email
maxLength: 64
alias:
type: string
description: An Alias name added to the account holder
accountHolder:
type: object
$ref: "#/definitions/WalletHolderData"
WalletHolderData:
type: object
description: All personal details about the account holder. eg. Name, birth dates, addresses, employments
properties:
name:
type: string
description: Legitimate name associated with the account holder
ParentAttributes:
type: "object"
description: >-
Describes a given characteristic of an object or entity through a name/value pair.
required:
- name
- value
properties:
name:
type: string
description: Name of the characteristic
valueType:
type: string
description: Data type of the value of the characteristic
value:
$ref: '#/definitions/Any'
description: The value of the characteristic
Any: {}
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: '#/definitions/AccountholderProfileResponse__links'