The Customer KYC(Know Your Client) Verification API will validate the 3PP Customer KYC information with MTN Customer KYC information.
swagger: "2.0"
info:
description: The Customer KYC(Know Your Client) Verification API will validate the 3PP Customer KYC information with
MTN Customer KYC information
version: "1.0.2"
title: MTN Customer KYC Verification API
host: api.mtn.com
basePath : "/v1/kycVerification/"
securityDefinitions:
basicAuth:
type: basic
ApiKeyAuth:
type: apiKey
name: X-API-Key
in: header
schemes:
- https
consumes:
- application/json
produces:
- application/json
security:
- ApiKeyAuth: []
- basicAuth: []
paths:
/customers:
get:
tags:
- Customer KYC
summary: Verify multiple customer kyc information by submitting an array of only msisdn or BVNs as a query params
description: This endpoint is responsible for handling the verification of multiple kyc information by sending an array of unique identifiers i.e MSISDN, BVN only
parameters:
- name: transactionId
in: header
x-example: e938-300949-394999-39993
type: string
description: A transactionId for tracking purposes
- name: targetSystem
in: header
x-example: NIBSS
type: string
description: Target System
- in: header
name: bvns
description: An array list of all the bvns to get customer details from
x-example: "[BVN123455,BVN3409394]"
type: array
items:
type: string
x-example: "BVN123455,BVN3409394"
responses:
"200":
description: Callback Success Response
schema:
$ref: '#/definitions/CustomerVerificationKYCMultiResponse'
"400":
description: Bad Request
schema:
allOf:
- properties:
statusCode:
type: string
description: "MADAPI canonical code for success"
example: '5000'
- $ref: '#/definitions/ErrorPayload'
"401":
description: Unauthorized
schema:
allOf:
- properties:
statusCode:
type: string
description: "MADAPI canonical code for success"
example: '4000'
- $ref: '#/definitions/ErrorPayload'
"403":
description: Forbidden
schema:
allOf:
- properties:
statusCode:
type: string
description: "MADAPI canonical code for success"
example: '4001'
- $ref: '#/definitions/ErrorPayload'
"404":
description: Not Found
schema:
allOf:
- properties:
statusCode:
type: string
description: "MADAPI canonical code for success"
example: '1000'
- $ref: '#/definitions/ErrorPayload'
"405":
description: Method Not Allowed
schema:
allOf:
- properties:
statusCode:
type: string
description: "MADAPI canonical code for success"
example: '3000'
- $ref: '#/definitions/ErrorPayload'
"406":
description: Not acceptable
schema:
allOf:
- properties:
statusCode:
type: string
description: "MADAPI canonical code for success"
example: '3000'
- $ref: '#/definitions/ErrorPayload'
"415":
description: Unsupported media Type
schema:
allOf:
- properties:
statusCode:
type: string
description: "MADAPI canonical code for success"
example: '3000'
- $ref: '#/definitions/ErrorPayload'
"500":
description: Internal Server Error
schema:
allOf:
- properties:
statusCode:
type: string
description: "MADAPI canonical code for success"
example: '3000'
- $ref: '#/definitions/ErrorPayload'
post:
tags:
- Customer KYC
summary: Verify multiple customer kyc information by submitting an array of customer information
description: This endpoint is responsible for handling the verification of multiple customers by passing an array of customers data.
parameters:
- name: transactionId
in: header
x-example: e938-300949-394999-39993
type: string
description: A transactionId for tracking purposes
- name: targetSystem
in: header
x-example: NIBSS
type: string
description: Target System
- name: requestType
in: query
description: The type of request to be made ie. whether it's a Face match or fingerprint verification, Required to be passed when targetSystem is NIBSS
required: false
type: string
enum: [FACE_MATCH, FINGERPRINT_MATCH]
- name: verificationType
in: query
required: false
type: string
description: Defines the type of verification 3PP wants to perform base on the passed payload ie. Whether it's a finger print, fingerprint with date of birth verification etc. Required to be passed when targetSystem is NIBSS
enum: [FINGERPRINT, FINGERPRINT_DOB]
- in: body
name: body
description: The request body to be sent to the backend
schema:
$ref: "#/definitions/CustomerKYCVerificationMultipleRequest"
responses:
"200":
description: Callback Success Response
schema:
$ref: '#/definitions/CustomerVerificationKYCMultiResponse'
"400":
description: Bad Request
schema:
allOf:
- properties:
statusCode:
type: string
description: "MADAPI canonical code for success"
example: '5000'
- $ref: '#/definitions/ErrorPayload'
"401":
description: Unauthorized
schema:
allOf:
- properties:
statusCode:
type: string
description: "MADAPI canonical code for success"
example: '4000'
- $ref: '#/definitions/ErrorPayload'
"403":
description: Forbidden
schema:
allOf:
- properties:
statusCode:
type: string
description: "MADAPI canonical code for success"
example: '4001'
- $ref: '#/definitions/ErrorPayload'
"404":
description: Not Found
schema:
allOf:
- properties:
statusCode:
type: string
description: "MADAPI canonical code for success"
example: '1000'
- $ref: '#/definitions/ErrorPayload'
"405":
description: Method Not Allowed
schema:
allOf:
- properties:
statusCode:
type: string
description: "MADAPI canonical code for success"
example: '3000'
- $ref: '#/definitions/ErrorPayload'
"406":
description: Not acceptable
schema:
allOf:
- properties:
statusCode:
type: string
description: "MADAPI canonical code for success"
example: '3000'
- $ref: '#/definitions/ErrorPayload'
"415":
description: Unsupported media Type
schema:
allOf:
- properties:
statusCode:
type: string
description: "MADAPI canonical code for success"
example: '3000'
- $ref: '#/definitions/ErrorPayload'
"500":
description: Internal Server Error
schema:
allOf:
- properties:
statusCode:
type: string
description: "MADAPI canonical code for success"
example: '3000'
- $ref: '#/definitions/ErrorPayload'
/customers/{customerId}:
post:
tags:
- Customer KYC
summary: Verify mtn customer kyc information against 3PP customer kyc information
description: This endpoint is to enable trusted partners verify customer's KYC information passed in the request body. The verification logic will be carried out at the process layer where each KYC attributes will be validated to be TRUE or FALSE based on their matching record on the network downstream system
parameters:
- name: customerId
in: path
description: ID of the customer. It could be MSISDN, email address, or any other customer identifier. if customerId is msisdn, then the format must be E.123
required: true
type: string
- name: isConsentVerified
in: query
type: "boolean"
description: "This will indicate that the customer consent has been acquired by the partner for KYC verification. For the request to be executed, this field should be set to TRUE if the consent validation has been successfully processed by the partner"
required: true
enum:
- FALSE
- TRUE
- in: body
name: body
description: Request body
required: true
schema:
$ref: '#/definitions/BasicKYCRequestData'
- in: header
name: transactionId
type: string
required: false
description: "A unique ID for tracking a particular transaction, optional and to be generated if not passed by the API caller"
x-example: c125d1e7-843f-410f-9252-71a55ec7cb92
- in: query
name: targetSystem
type: string
enum:
- DAAS
- CLM
- BANK_BILLING
- CLM_REST
- BIOSMART
responses:
"200":
description: Callback Success Response
schema:
$ref: '#/definitions/KYCVerificationResponse'
"400":
description: Bad Request
schema:
allOf:
- properties:
statusCode:
type: string
description: "MADAPI canonical code for success"
example: '5000'
- $ref: '#/definitions/ErrorPayload'
"401":
description: Unauthorized
schema:
allOf:
- properties:
statusCode:
type: string
description: "MADAPI canonical code for success"
example: '4000'
- $ref: '#/definitions/ErrorPayload'
"403":
description: Forbidden
schema:
allOf:
- properties:
statusCode:
type: string
description: "MADAPI canonical code for success"
example: '4001'
- $ref: '#/definitions/ErrorPayload'
"404":
description: Not Found
schema:
allOf:
- properties:
statusCode:
type: string
description: "MADAPI canonical code for success"
example: '1000'
- $ref: '#/definitions/ErrorPayload'
"405":
description: Method Not Allowed
schema:
allOf:
- properties:
statusCode:
type: string
description: "MADAPI canonical code for success"
example: '3000'
- $ref: '#/definitions/ErrorPayload'
"406":
description: Not acceptable
schema:
allOf:
- properties:
statusCode:
type: string
description: "MADAPI canonical code for success"
example: '3000'
- $ref: '#/definitions/ErrorPayload'
"415":
description: Unsupported media Type
schema:
allOf:
- properties:
statusCode:
type: string
description: "MADAPI canonical code for success"
example: '3000'
- $ref: '#/definitions/ErrorPayload'
"500":
description: Internal Server Error
schema:
allOf:
- properties:
statusCode:
type: string
description: "MADAPI canonical code for success"
example: '3000'
- $ref: '#/definitions/ErrorPayload'
get:
security:
- basicAuth: [ ]
tags:
- Customer KYC
summary: Verify if customer MSISDN is active on either the bank or MTN
description: This endpoint is to enable a 3PP confirm if a mobile number is active on the bank and to get a hashed mobile number
parameters:
- name: customerId
in: path
description: customer MSISDN that is to be confirmed
required: true
type: string
- name: transactionId
in: query
type: "string"
description: "transactionId for tracking purposes"
- name: verificationType
type: string
in: query
description: Verification Type.
enum:
- BANK
- HASHCODE
- EVALIDATOR
- WinBack
- VALENTINE_PROMO
- name: targetSystem
type: string
in: query
enum:
- DAAS
- CLM
- BANK_BILLING
- CLM_REST
- NIBSS
- name: externalCode
in: query
type: "string"
description: "This can be the bank's short code"
- name: startDate
in: query
type: "string"
description:
An optional parameter, together with endDate, allows developers to
specify a time range by which to query customer data on. If you want
to request data for 2 months, then start date will need to set to 2
months prior to today, and endDate to todays date. If this is not
set, the date range will be defaulted to 6 months
- name: endDate
in: query
type: "string"
description:
An optional parameter, together with startDate, allows developers to
specify a time range by which to query customer data on. If you want
to request data for 2 months, then start date will need to set to 2
months prior to today, and endDate to todays date. If this is not
set, the date range will be defaulted to 6 months
responses:
"200":
description: Successful verification
schema:
$ref: '#/definitions/CustomerVerificationResponse'
"400":
description: Bad Request
schema:
allOf:
- properties:
statusCode:
type: string
description: "MADAPI canonical code for success"
example: '5000'
- $ref: '#/definitions/ErrorPayload'
"401":
description: Unauthorized
schema:
allOf:
- properties:
statusCode:
type: string
description: "MADAPI canonical code for success"
example: '4000'
- $ref: '#/definitions/ErrorPayload'
"403":
description: Forbidden
schema:
allOf:
- properties:
statusCode:
type: string
description: "MADAPI canonical code for success"
example: '4001'
- $ref: '#/definitions/ErrorPayload'
"404":
description: Not Found
schema:
allOf:
- properties:
statusCode:
type: string
description: "MADAPI canonical code for success"
example: '1000'
- $ref: '#/definitions/ErrorPayload'
"405":
description: Method Not Allowed
schema:
allOf:
- properties:
statusCode:
type: string
description: "MADAPI canonical code for success"
example: '3000'
- $ref: '#/definitions/ErrorPayload'
"406":
description: Not acceptable
schema:
allOf:
- properties:
statusCode:
type: string
description: "MADAPI canonical code for success"
example: '3000'
- $ref: '#/definitions/ErrorPayload'
"415":
description: Unsupported media Type
schema:
allOf:
- properties:
statusCode:
type: string
description: "MADAPI canonical code for success"
example: '3000'
- $ref: '#/definitions/ErrorPayload'
"500":
description: Internal Server Error
schema:
allOf:
- properties:
statusCode:
type: string
description: "MADAPI canonical code for success"
example: '3000'
- $ref: '#/definitions/ErrorPayload'
/customers/{customerId}/kycScore:
post:
tags:
- Customer KYC
summary: Verify mtn customer kyc information against 3PP customer kyc information
description: This endpoint is to enable trusted partners to verify customer's KYC information passed in the request body. The verification logic will be carried out where each KYC attributes will be validated and given a percentage score (between 0 - 100) based on their matching record on the network downstream system
parameters:
- name: customerId
in: path
description: ID of the customer. It could be MSISDN, email address, or any other customer identifier. if customerId is msisdn, then the format must be E.123
required: true
type: string
- in: body
name: body
description: Request body
required: true
schema:
$ref: '#/definitions/KYCRequestDataScore'
- in: header
name: transactionId
type: string
required: false
description: "A unique ID for tracking a particular transaction, optional and to be generated if not passed by the API caller"
x-example: c125d1e7-843f-410f-9252-71a55ec7cb92
responses:
"200":
description: Callback Success Response
schema:
$ref: '#/definitions/KYCVerificationScoreResponse'
"400":
description: Bad Request
schema:
allOf:
- properties:
statusCode:
type: string
description: "MADAPI canonical code for success"
example: '5000'
- $ref: '#/definitions/ErrorPayload'
"401":
description: Unauthorized
schema:
allOf:
- properties:
statusCode:
type: string
description: "MADAPI canonical code for success"
example: '4000'
- $ref: '#/definitions/ErrorPayload'
"403":
description: Forbidden
schema:
allOf:
- properties:
statusCode:
type: string
description: "MADAPI canonical code for success"
example: '4001'
- $ref: '#/definitions/ErrorPayload'
"404":
description: Not Found
schema:
allOf:
- properties:
statusCode:
type: string
description: "MADAPI canonical code for success"
example: '1000'
- $ref: '#/definitions/ErrorPayload'
"405":
description: Method Not Allowed
schema:
allOf:
- properties:
statusCode:
type: string
description: "MADAPI canonical code for success"
example: '3000'
- $ref: '#/definitions/ErrorPayload'
"406":
description: Not acceptable
schema:
allOf:
- properties:
statusCode:
type: string
description: "MADAPI canonical code for success"
example: '3000'
- $ref: '#/definitions/ErrorPayload'
"415":
description: Unsupported media Type
schema:
allOf:
- properties:
statusCode:
type: string
description: "MADAPI canonical code for success"
example: '3000'
- $ref: '#/definitions/ErrorPayload'
"500":
description: Internal Server Error
schema:
allOf:
- properties:
statusCode:
type: string
description: "MADAPI canonical code for success"
example: '3000'
- $ref: '#/definitions/ErrorPayload'
/customers/{customerId}/nameScore:
post:
tags:
- Customer KYC
summary: Verify mtn customer kyc information against 3PP customer kyc information
description: This endpoint is to enable trusted partners to verify customer's KYC information passed in the request body. The verification logic will be carried out where each KYC attributes will be validated and given a percentage score (between 0 - 100) based on their matching record on the network downstream system
parameters:
- name: customerId
in: path
description: ID of the customer. It could be MSISDN, email address, or any other customer identifier. if customerId is msisdn, then the format must be E.123
required: true
type: string
- in: body
name: body
description: Request body
required: true
schema:
$ref: '#/definitions/KYCNameRequestDataScore'
- in: header
name: transactionId
type: string
required: false
description: "A unique ID for tracking a particular transaction, optional and to be generated if not passed by the API caller"
x-example: c125d1e7-843f-410f-9252-71a55ec7cb92
responses:
"200":
description: Callback Success Response
schema:
$ref: '#/definitions/KYCNameVerificationScoreResponse'
"400":
description: Bad Request
schema:
allOf:
- properties:
statusCode:
type: string
description: "MADAPI canonical code for success"
example: '5000'
- $ref: '#/definitions/ErrorPayload'
"401":
description: Unauthorized
schema:
allOf:
- properties:
statusCode:
type: string
description: "MADAPI canonical code for success"
example: '4000'
- $ref: '#/definitions/ErrorPayload'
"403":
description: Forbidden
schema:
allOf:
- properties:
statusCode:
type: string
description: "MADAPI canonical code for success"
example: '4001'
- $ref: '#/definitions/ErrorPayload'
"404":
description: Not Found
schema:
allOf:
- properties:
statusCode:
type: string
description: "MADAPI canonical code for success"
example: '1000'
- $ref: '#/definitions/ErrorPayload'
"405":
description: Method Not Allowed
schema:
allOf:
- properties:
statusCode:
type: string
description: "MADAPI canonical code for success"
example: '4001'
- $ref: '#/definitions/ErrorPayload'
"406":
description: Not acceptable
schema:
allOf:
- properties:
statusCode:
type: string
description: "MADAPI canonical code for success"
example: '3000'
- $ref: '#/definitions/ErrorPayload'
"415":
description: Unsupported media Type
schema:
allOf:
- properties:
statusCode:
type: string
description: "MADAPI canonical code for success"
example: '3000'
- $ref: '#/definitions/ErrorPayload'
"500":
description: Internal Server Error
schema:
allOf:
- properties:
statusCode:
type: string
description: "MADAPI canonical code for success"
example: '3000'
- $ref: '#/definitions/ErrorPayload'
/customers/{customerId}/addressScore:
post:
tags:
- Customer KYC
summary: Verify mtn customer kyc information against 3PP customer kyc information
description: This endpoint is to enable trusted partners to verify customer's KYC information passed in the request body. The verification logic will be carried out where each KYC attributes will be validated and given a percentage score (between 0 - 100) based on their matching record on the network downstream system
parameters:
- name: customerId
in: path
description: ID of the customer. It could be MSISDN, email address, or any other customer identifier. if customerId is msisdn, then the format must be E.123
required: true
type: string
- in: body
name: body
description: Request body
required: true
schema:
$ref: '#/definitions/KYCAddressRequestDataScore'
- in: header
name: transactionId
type: string
required: false
description: "A unique ID for tracking a particular transaction, optional and to be generated if not passed by the API caller"
x-example: c125d1e7-843f-410f-9252-71a55ec7cb92
responses:
"200":
description: Callback Success Response
schema:
$ref: '#/definitions/KYCAddressVerificationScoreResponse'
"400":
description: Bad Request
schema:
allOf:
- properties:
statusCode:
type: string
description: "MADAPI canonical code for success"
example: '5000'
- $ref: '#/definitions/ErrorPayload'
"401":
description: Unauthorized
schema:
allOf:
- properties:
statusCode:
type: string
description: "MADAPI canonical code for success"
example: '4000'
- $ref: '#/definitions/ErrorPayload'
"403":
description: Forbidden
schema:
allOf:
- properties:
statusCode:
type: string
description: "MADAPI canonical code for success"
example: '4001'
- $ref: '#/definitions/ErrorPayload'
"404":
description: Not Found
schema:
allOf:
- properties:
statusCode:
type: string
description: "MADAPI canonical code for success"
example: '1000'
- $ref: '#/definitions/ErrorPayload'
"405":
description: Method Not Allowed
schema:
allOf:
- properties:
statusCode:
type: string
description: "MADAPI canonical code for success"
example: '4001'
- $ref: '#/definitions/ErrorPayload'
"406":
description: Not acceptable
schema:
allOf:
- properties:
statusCode:
type: string
description: "MADAPI canonical code for success"
example: '3000'
- $ref: '#/definitions/ErrorPayload'
"415":
description: Unsupported media Type
schema:
allOf:
- properties:
statusCode:
type: string
description: "MADAPI canonical code for success"
example: '3000'
- $ref: '#/definitions/ErrorPayload'
"500":
description: Internal Server Error
schema:
allOf:
- properties:
statusCode:
type: string
description: "MADAPI canonical code for success"
example: '3000'
- $ref: '#/definitions/ErrorPayload'
/customers/{customerId}/biometric/verify:
post:
tags:
- Customer KYC
summary: Verify customer kyc information by uploading customer biometric data
description: This endpoint is to enable trusted partners verify customer's KYC information by passing customer biometric details
parameters:
- name: customerId
in: path
description: ID of the customer. It could be MSISDN, email address, or any other customer identifier. if customerId is msisdn, then the format must be E.123
required: true
type: string
- name: transactionId
in: header
description: Transaction Id for tracking purposes
required: false
type: string
- name: targetSystem
in: header
description: Target system
type: string
required: false
x-example: BIOSMART, NIBSS
- name: requestType
in: query
description: The type of request to be made ie. whether it's a Face match or fingerprint verification, Required to be passed when targetSystem is NIBSS
required: false
type: string
enum: [FINGERPRINT_MATCH]
- name: verificationType
in: query
required: false
type: string
description: Defines the type of verification 3PP wants to perform base on the passed payload ie. Whether it's a finger print, fingerprint with date of birth verifica
# --- truncated at 32 KB (66 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mtn-group/refs/heads/main/openapi/mtn-group-customer-kyc-verification.yml