A suite of apis for customer validation.
swagger: '2.0'
info:
description: A suite of apis for customer validation.
version: "v1"
title: MoMo Verification API
schemes:
- https
host: "api.mtn.com"
basePath: "/v1"
consumes:
- "application/json"
produces:
- "application/json"
securityDefinitions:
ApiKeyAuth:
type: "apiKey"
name: "X-API-Key"
in: "header"
OAuth2:
type: oauth2
flow: application
tokenUrl: https://api.mtn.com/v1/oauth/access_token
security:
- ApiKeyAuth: []
- OAuth2: []
paths:
'/verify/{customerId}/generateQnA':
get:
tags:
- "Validate using QnA"
summary: "Generate Q&A for ID based validation"
description: "Validates the MoMo account for performing PIN Reset"
produces:
- "application/json"
parameters:
- name: "customerId"
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
- name: accountHolderIdNumber
in: query
description: Identification Number of the consumer who wants to register for MoMo or do a Pin Reset.
e.g. 8512285568081
type: string
- name: requestIdentifier
in: query
description: requestIdentifier will identifies the request is MoMo registration or Zero balance pin reset.
type: string
enum:
- Registration
- PinReset
responses:
"200":
description: "Successful response"
schema:
$ref: "#/definitions/generateQAResponse"
"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'
'/verify/{customerId}/validateQnA':
post:
tags:
- "Validate using QnA"
summary: "Validate Q&A for ID based validation"
description: "Validates the MoMo account for performing PIN Reset"
produces:
- "application/json"
parameters:
- name: "customerId"
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
- name: accountHolderIdNumber
in: query
description: Identification Number of the consumer who wants to register for MoMo or do a Pin Reset.
type: "string"
- name: requestId
in: query
type: string
description: ID which is generated during the get Q&A call, needs to be passed here
- name: answerChoice
in: body
schema:
$ref: "#/definitions/QnABody"
responses:
"200":
description: "Successful response"
schema:
$ref: "#/definitions/ValidateQnAResponse"
"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:
generateQAResponse:
type: "object"
properties:
statusCode:
type: string
description: HTTP error code
statusMessage:
type: string
description: HTTP error description
customerId:
type: string
example: MTN123456
description: Id provided in the input
transactionId:
type: "string"
description: "Transaction Id of the request"
data:
$ref: '#/definitions/dataQA'
_links:
$ref: '#/definitions/ValidateQA_links'
ValidateQnAResponse:
type: "object"
properties:
statusCode:
type: string
description: HTTP error code
statusMessage:
type: string
description: HTTP error description
customerId:
type: string
example: MTN123456
description: Id provided in the input
transactionId:
type: "string"
description: "Transaction Id of the request"
dataQA:
type: array
description: This contains the list of challenging questions (3 questions as of now) that are related to the data provided at the time of generating ID number (accountHolderIdNumber) at the corresponding registration office. These questions will be generated only if the valid id is provided for the MoMo registration.
items:
type: object
properties:
requestId:
type: string
description: Unique ID generated by Provider system, this same requestId is to be sent in the validate Q&A call
questionId:
type: string
description: Unique ID generated while generating question. Source system must pass this question Id when validating the profile.
questionText:
type: string
description: Describes the question that is being asked to validate the user profile for customer registration. e.g. What is your first name?
answers:
type: array
description: Contains multiple answers(3 answers for each questio). User needs to pick 1 answer from the answers and validate in subsequent call.
items:
type: object
properties:
answerId:
type: string
description: Unique ID generated while generating answer. Source system must pass this question Id when validating the profile
answerText:
type: string
description: The answer that can be selected by the user to validate the registration process. e.g. SONJA
QnABody:
type: "object"
properties:
Answers:
type: array
description: Contains list of question and answers to validate the customer
profile. Source system must pick the questions verificaion process,
select the answers from the options and send the request to SOA.
items:
type: object
properties:
questionId:
type: string
description: Unique ID generated at Contactable while generating
question. Source system must pass this question Id when validating
the profile. e.g. 972bcefb-1dfd-4526-9dc1-21429e234abb
answerId:
type: string
description: Unique ID generated at Contactable while generating
answer. Source system must pass this question Id when validating
the profile. e.g. fdccbded-6414-46c1-8493-acf1a3d00d7a
ValidateQA_links:
type: object
properties:
self:
$ref: '#/definitions/ValidateQA_links_self'
description: Relevant links to the Accoutholder Profile.
ValidateQA_links_self:
type: object
properties:
href:
type: string
example: https://host:port/v1/verification/12345
description: Hyperlink to access the Accountholder's Profile.
Error:
type: object
required:
- "statusCode"
- "statusMessage"
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. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes'
example: '1000'
statusMessage:
type: string
description: More details and corrective actions related to the error which can be shown to a client
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)
transactionId:
type: string
description: This is the same transactionId that is sent in the request
example: 'cdfa7bc3-cbcd-473b-a743-4fc90dcc91e4'
timestamp:
type: string
format: date-time
description: Timestamp that the error occurred
example: '2020-08-01T12:34'
path:
type: string
description: The path that caused the error
example: '/customers/27831234567/generateQnA'
method:
type: string
description: The HTTP method type that was used
example: 'GET'