To facilitate the capability for customer to create/validate/change Pin Information.
swagger: '2.0'
info:
description: To facilitate the capability for customer to create/validate/change Pin Information.
version: 1.0.2
title: Customer PIN Management API
schemes:
- https
host: api.mtn.com
basePath: /customerPinManagement/v2
consumes:
- application/json;charset=utf-8
produces:
- application/json;charset=utf-8
securityDefinitions:
ApiKeyAuth:
type: apiKey
name: X-API-Key
in: header
OAuth2:
type: oauth2
flow: application
tokenUrl: "https://api.mtn.com/v1/oauth/access_token/accesstoken?grant_type=client_credentials"
security:
- ApiKeyAuth: []
- OAuth2: []
paths:
/customer/{customerId}/pin:
post:
tags:
- PIN
summary: To create Pin customer will provide mandatory(customerId, secret, alternateNumber, securityQuestion, tncDetails,channel,transId) attributes. Also will provide emailID as optional input
description: >-
create Pin Details, user must enter the MSISDN/Service Number of Customer, the PIN number, alternate mobile Number , Answer for the Security Question and valid channel id. Finally the user will enter the Unique Trans ID as per below format yyyymmddhhmmss<UniqueSequenceNumber> i.e 20200711123459103
operationId: createCutomerPin
parameters:
- name: "transactionId"
in: header
description: 'Client generated Id to include for tracing requests.'
type: string
required: false
x-example: '6f0bece6-7df3-4da4-af02-5e7f16e5e6fc'
- name: customerId
in: path
required : true
type: "string"
description: "Customer id will be act as serviceNumber and it can Customer's msisdn, serviceId, accountId, or invoiceId."
- name: countryCode
in: header
description: "Country ISO code. Must be ISO 3166-1 alpha-3 codes (It is a 3 character string)"
required: false
type: string
enum:
- NGA
- UGA
- ZAF
- RWA
- name: "secret"
in: header
description: 'PIN number to be set'
type: string
format: base64
required: true
x-example: 'MTIzNDU2Nzg5MTA='
- name: "repeatedSecret"
in: header
description: "A repeated secret to validate the provided secret"
type: string
required: false
x-example: "1234455"
- name: "emailID"
in: header
description: 'Customer’s Email ID'
type: string
required: false
x-example: 'sharma.anuj@tecnotree.com'
- name: "alternateNumber"
in: header
description: 'An alternative identifier associated with the customer, ie. a mobile number, a repeat of secret etc.'
type: string
required: false
x-example: '12345678910'
- name: "tncDetails"
in: header
description: 'Terms & Condition should be “1.0” or as configured for the channel, not required if target system is EWP for PSB IVR'
type: string
required: false
x-example: '1.0'
- name: "channel"
in: header
description: 'Name of the channel, can be a channel information, a credential type depending on the backend system'
type: string
x-example: "CONVIVA"
required: true
- name: targetSystem
type: string
in: query
enum: [EWP]
description: The backend system expected to fulfil the request
- name: X-Authorization
type: string
in: header
description: Client credentials to be authenticated by EWP or ECW
- name: description
in: header
description: A request info, can be a bank domain name etc.
type: string
x-example: "TESTYDFS"
- name: currency
in: query
description: A currency
type: string
x-example: "NGN"
- name: invitationCode
in: query
description: "An invitation code associated with the PIN creation"
type: string
x-example: "12345"
- name: segment
type: string
in: query
required: false
description: This is the type of customer doing the transaction. This can be customer, agent or admin
- name: idType
type: string
in: query
required: false
description: Type of the customerId in the path.
enum: [MSISDN, USER]
- name: body
in: body
description: "Security Question and Answer Details, not required when target system is EWP for PSB IVR"
required: false
schema:
$ref: "#/definitions/SecurityQuestionAnswers"
responses:
'200':
description: 'Success'
schema:
$ref: "#/definitions/CreatePinResponse"
'400':
description: "Bad Request"
schema:
$ref: "#/definitions/Error"
'401':
description: "Unauthorized"
schema:
$ref: "#/definitions/Error"
'403':
description: "Forbidden"
schema:
$ref: "#/definitions/Error"
'404':
description: "Customer not found"
schema:
$ref: "#/definitions/Error"
examples:
The services object/envelope will be null: >
{
"services": null
}
'405':
description: "Method Not allowed"
schema:
$ref: "#/definitions/Error"
'500':
description: "Internal Server Error"
schema:
$ref: "#/definitions/Error"
get:
tags:
- PIN
summary: To validate Pin Details user will enter (customerId, secret, channel, transId) Attributes
description: >-
To validate Pin Details, user must enter the MSISDN/Service Number of Customer, the PIN number, channel id. Finally the user will enter the Unique Trans ID as per below format yyyymmddhhmmss<UniqueSequenceNumber> i.e 20200711123459104
operationId: validateCutomerPin
parameters:
- name: "transactionId"
in: header
description: 'Client generated Id to include for tracing requests.'
type: string
required: false
x-example: '6f0bece6-7df3-4da4-af02-5e7f16e5e6fc'
- name: customerId
in: path
required : true
type: "string"
description: "Customer id will be act as serviceNumber and it can Customer's msisdn, serviceId, accountId, or invoiceId."
- name: countryCode
in: header
description: "Country ISO code. Must be ISO 3166-1 alpha-3 codes (It is a 3 character string)"
required: false
type: string
enum:
- NGA
- UGA
- ZAF
- RWA
- name: "secret"
in: header
description: 'PIN number to be set'
type: string
format: base64
required: true
x-example: 'MTIzNDU2Nzg5MTA='
- name: "channel"
in: header
description: 'channel'
type: string
required: true
x-example: '12345678910'
responses:
'200':
description: 'Success'
schema:
$ref: "#/definitions/ValidatePinResponse"
'400':
description: "Bad Request"
schema:
$ref: "#/definitions/Error"
'401':
description: "Unauthorized"
schema:
$ref: "#/definitions/Error"
'403':
description: "Forbidden"
schema:
$ref: "#/definitions/Error"
'404':
description: "Customer not found"
schema:
$ref: "#/definitions/Error"
examples:
The services object/envelope will be null: >
{
"services": null
}
'405':
description: "Method Not allowed"
schema:
$ref: "#/definitions/Error"
'500':
description: "Internal Server Error"
schema:
$ref: "#/definitions/Error"
put:
tags:
- PIN
summary: To change Pin Details user will enter (customerId, operationType, currentSecret, newSecret,channel,transId) Attributes
description: >-
To change Pin Details, user must enter the 'MSISDN/Service Number of Customer'. User has to enter the 'current Secret/PIN' and 'New Secret/PIN'. User will enter Security Answer selected during first time Secret/PIN Creation. Finally the user will enter the 'channel id' & 'Unique Trans ID as per below format yyyymmddhhmmss<UniqueSequenceNumber> i.e 20200711123459105
operationId: changeCutomerPin
parameters:
- name: "transactionId"
in: header
description: 'Client generated Id to include for tracing requests.'
type: string
required: false
x-example: '6f0bece6-7df3-4da4-af02-5e7f16e5e6fc'
- name: customerId
in: path
required : true
type: "string"
description: "Customer id will be act as serviceNumber and it can Customer's msisdn, serviceId, accountId, or invoiceId."
- name: countryCode
in: header
description: "Country ISO code. Must be ISO 3166-1 alpha-3 codes (It is a 3 character string)"
required: false
type: string
enum:
- NGA
- UGA
- ZAF
- RWA
- name: "currentSecret"
in: header
description: 'Customers current secret/pin'
type: string
format: base64
required: false
x-example: 'MTIzNDU2Nzg5MTA='
- name: "repeatedSecret"
in: header
description: 'Customers repeated password'
type: string
required: false
x-example: '1234'
- name: "newSecret"
in: header
description: 'Customers new secret/pin'
type: string
format: base64
required: true
x-example: 'MTIzNDU2Nzg5MTA='
- name: "securityAnswer"
in: header
description: 'Give secured answer'
type: string
required: false
x-example: 'BMW'
- name: "channel"
in: header
description: 'channel'
type: string
required: false
x-example: '12345678910'
- name: targetSystem
in: query
type: string
required: false
enum: [CIS,EWP]
description: The backend system expected to fulfil the request
- name: X-Authorization
type: string
in: header
description: Client credentials to be authenticated by EWP or ECW
- name: segment
type: string
in: query
required: false
description: This is the type of customer doing the transaction. This can be customer, agent or admin
- name: idType
type: string
in: query
required: false
description: Type of the customerId in the path.
enum: [MSISDN, USER]
- name: requestType
type: string
in: query
description: The type of operation being performed in the change
enum: [CHANGE_PIN, RESET_PIN]
responses:
'200':
description: 'Success'
schema:
$ref: "#/definitions/ChangePinResponse"
'400':
description: "Bad Request"
schema:
$ref: "#/definitions/Error"
'401':
description: "Unauthorized"
schema:
$ref: "#/definitions/Error"
'403':
description: "Forbidden"
schema:
$ref: "#/definitions/Error"
'404':
description: "Customer not found"
schema:
$ref: "#/definitions/Error"
examples:
The services object/envelope will be null: >
{
"services": null
}
'405':
description: "Method Not allowed"
schema:
$ref: "#/definitions/Error"
'500':
description: "Internal Server Error"
schema:
$ref: "#/definitions/Error"
patch:
tags:
- PIN
summary: To reset Pin Details user will enter (customerId, operationType, validateAnswers, motherName,dateOfBirth,stateOfOrigin,channel,transId) Attributes
description: >-
To reset Pin Details, user must enter the 'MSISDN/Service Number of Customer'. User has to enter the Y-indicates validate security answer,
N-indicates no validation for Validate Answers'. User will enter Mothers maiden name also will enter the Date of Birth in format YYYY-MM-DD and State of Origin code.
Finally the user will enter the 'channel id' & 'Unique Trans ID as per below format yyyymmddhhmmss<UniqueSequenceNumber> i.e 20200711123459105
operationId: resetCutomerPin
parameters:
- name: "transactionId"
in: header
description: 'Client generated Id to include for tracing requests.'
type: string
required: false
x-example: '6f0bece6-7df3-4da4-af02-5e7f16e5e6fc'
- name: customerId
in: path
required : true
type: "string"
description: "Customer id will be act as serviceNumber and it can Customer's msisdn, serviceId, accountId, or invoiceId."
- name: countryCode
in: header
description: "Country ISO code. Must be ISO 3166-1 alpha-3 codes (It is a 3 character string)"
required: false
type: string
enum:
- NGA
- UGA
- ZAF
- RWA
- name: "validateAnswers"
in: header
description: 'Y-indicates validate security answer, N-indicates no validation'
type: string
required: false
x-example: 'Y'
- name: "motherName"
in: query
description: 'Mothers maiden name'
type: string
required: false
x-example: 'abcd'
- name: "dateOfBirth"
in: query
description: 'Date of Birth in format YYYY-MM-DD'
type: string
required: false
x-example: '2020-10-13'
- name: "stateOfOrigin"
in: query
description: 'State of Origin code'
type: string
required: false
x-example: '+91'
- name: "channel"
in: header
description: 'channel'
type: string
required: true
x-example: '12345678910'
- name: "idNumber"
in: query
description: 'Customer ID'
type: string
required: false
x-example: '12345678910'
- name: description
in: query
type: string
required: false
- name: targetSystem
in: query
type: string
required: false
enum: [CIS]
responses:
'200':
description: 'Success'
schema:
$ref: "#/definitions/resetPinResponse"
'400':
description: "Bad Request"
schema:
$ref: "#/definitions/Error"
'401':
description: "Unauthorized"
schema:
$ref: "#/definitions/Error"
'403':
description: "Forbidden"
schema:
$ref: "#/definitions/Error"
'404':
description: "Customer not found"
schema:
$ref: "#/definitions/Error"
examples:
The services object/envelope will be null: >
{
"services": null
}
'405':
description: "Method Not allowed"
schema:
$ref: "#/definitions/Error"
'500':
description: "Internal Server Error"
schema:
$ref: "#/definitions/Error"
/customer/{customerId}/pinProfile:
put:
tags:
- PIN
summary: To change Pin Details user will enter (customerId, operationType,securityQuestion,securityAnswer,channel,emailID,tncDetails) Attributes
description: >-
To change Pin Details, user must enter the 'MSISDN/Service Number of Customer'. User will enter Security Answer to be updated. Finally the user will enter the 'channel id'
operationId: chanageSecurityQnACutomerPin
parameters:
- name: "transactionId"
in: header
description: 'Client generated Id to include for tracing requests.'
type: string
required: false
x-example: '6f0bece6-7df3-4da4-af02-5e7f16e5e6fc'
- name: customerId
in: path
required : true
type: "string"
description: "Customer id will be act as serviceNumber and it can Customer's msisdn, serviceId, accountId, or invoiceId."
- name: countryCode
in: header
description: "Country ISO code. Must be ISO 3166-1 alpha-3 codes (It is a 3 character string)"
required: false
type: string
enum:
- NGA
- UGA
- ZAF
- RWA
- name: "channel"
in: query
description: 'channel'
type: string
required: false
x-example: '12345678910'
- name: "operationType"
in: query
description: "Specify the operation of the request"
type: string
enum:
- UpdateQA
- UpdateEmailID
- UpdateTNC
required: true
x-example: "updateQA"
- name: "emailID"
in: header
description: 'Customer’s Email ID'
type: string
required: false
- name: "tncDetails"
in: header
description: 'Terms & Condition should be “1.0” or as configured for the channel'
type: string
required: false
- name: body
in: body
description: "Security Question and Answer Details"
required: false
schema:
$ref: "#/definitions/SecurityQuestionAnswers"
responses:
'200':
description: 'Success'
schema:
$ref: "#/definitions/ValidateSecurityAnswerResponse"
'400':
description: "Bad Request"
schema:
$ref: "#/definitions/Error"
'401':
description: "Unauthorized"
schema:
$ref: "#/definitions/Error"
'403':
description: "Forbidden"
schema:
$ref: "#/definitions/Error"
'404':
description: "Customer not found"
schema:
$ref: "#/definitions/Error"
examples:
The services object/envelope will be null: >
{
"services": null
}
'405':
description: "Method Not allowed"
schema:
$ref: "#/definitions/Error"
'500':
description: "Internal Server Error"
schema:
$ref: "#/definitions/Error"
get:
tags:
- PIN
summary: To get Pin profile Details user will enter (customerId, operationType,securityQuestion,securityAnswer,channel) Attributes
description: >-
To get Pin Details, user must enter the 'MSISDN/Service Number of Customer'. User will enter Security Answer to be updated. Finally the user will enter the 'channel id'
operationId: getProfileDetails
parameters:
- name: "transactionId"
in: header
description: 'Client generated Id to include for tracing requests.'
type: string
required: false
x-example: '6f0bece6-7df3-4da4-af02-5e7f16e5e6fc'
- name: customerId
in: path
required : true
type: "string"
description: "Customer id will be act as serviceNumber and it can Customer's msisdn, serviceId, accountId, or invoiceId."
- name: countryCode
in: header
description: "Country ISO code. Must be ISO 3166-1 alpha-3 codes (It is a 3 character string)"
required: false
type: string
enum:
- NGA
- UGA
- ZAF
- RWA
- name: "channel"
in: query
description: 'channel'
type: string
required: false
x-example: '12345678910'
- name: "operationType"
in: query
description: "Specify the operation of the request"
type: string
enum:
- QueryProfile
- QueryTNC
required: true
x-example: "QueryTNC"
responses:
'200':
description: 'Success'
schema:
$ref: "#/definitions/GetProfileDetailsResponse"
'400':
description: "Bad Request"
schema:
$ref: "#/definitions/Error"
'401':
description: "Unauthorized"
schema:
$ref: "#/definitions/Error"
'403':
description: "Forbidden"
schema:
$ref: "#/definitions/Error"
'404':
description: "Customer not found"
schema:
$ref: "#/definitions/Error"
examples:
The services object/envelope will be null: >
{
"services": null
}
'405':
description: "Method Not allowed"
schema:
$ref: "#/definitions/Error"
'500':
description: "Internal Server Error"
schema:
$ref: "#/definitions/Error"
definitions:
SecurityQuestionAnswers:
type: array
items:
type: object
properties:
SecurityQuestionAnswer:
$ref: "#/definitions/securityquestionAnswer"
securityquestionAnswer:
type: object
required:
- name
properties:
securityQuestion:
type: string
example: string
description: "user will enter security question"
securityAnswer:
type: string
example: string
description: "user will enter answer for security question"
ValidatePinResponse:
type: object
required:
- name
properties:
statusCode:
type: string
example: "0000"
description: "Success API code. '0000' in case of success"
statusMessage:
type: string
example: "String"
transactionId:
type: string
example: "String"
data:
type: object
$ref: "#/definitions/ValidatePinResponseData"
ValidatePinResponseData:
type: "object"
title: "ValidatePinResponseData"
properties:
message:
type: "string"
example: "Subscriber secret authenticated successfully"
description: "API Success Message. i.e. Subscriber secret authenticated successfully"
forcePasswordChange:
type: string
example: "false"
description: "true/false"
securityQuestionAvailable:
type: string
example: "true"
emailID:
type: string
example: "sharma.anuj@tecnotree.com"
tncAccepted:
type: array
items:
type: string
example:
- Version: "2.0"
AcceptedDate: "2020-07-11T13:43:30.830Z"
tncLastUpdtdate:
type: string
example: "2020-07-01T10:10:11.830Z"
tncLastUpdtversion:
type: string
example: "2.0"
ChangePinResponse:
type: object
required:
- name
properties:
statusCode:
type: string
example: "0000"
description: "Success API code. '0000' in case of success"
statusMessage:
type: string
example: "String"
transactionId:
type: string
example: "String"
customerId:
type: string
example: "String"
data:
type: object
$ref: "#/definitions/ChangePinResponseData"
ChangePinResponseData:
type: "object"
title: "ChangePinResponseData"
properties:
message:
type: "string"
example: "Subscriber secret has been changed and SMS sent successfully"
description: "API Success Message.i.e. Subscriber secret has been changed and SMS sent successfully"
amountCharged:
type: object
properties:
value:
type: number
unit:
type: string
resetPinResponse:
type: object
required:
- name
properties:
statusCode:
type: string
example: "0000"
description: "Success API code. '0000' in case of success"
statusMessage:
type: string
example: "String"
transactionId:
type: string
example: "String"
data:
type: object
$ref: "#/definitions/ResetPinResponseData"
ResetPinResponseData:
type: "object"
title: "ResetPinResponseData"
properties:
message:
type: "string"
example: "pin changed and SMS sent to customer Successfully"
description: "API Success Message.i.e. Pin changed and SMS sent to customer Successfully"
amountCharged:
type: object
properties:
value:
type: number
unit:
type: string
ValidateSecurityAnswerResponse:
type: object
required:
- name
properties:
statusCode:
type: string
example: "0000"
description: "Success API code. '0000' in case of success"
statusMessage:
type: string
example: "String"
transactionId:
type: string
example: "String"
data:
type: object
$ref: "#/definitions/ValidateSecurityAnswerResponseData"
ValidateSecurityAnswerResponseData:
type: "object"
title: "ValidateSecurityAnswerResponseData"
properties:
message:
type: "string"
example: "Subscriber answer validated successfully"
description: "API Success Message.i.e. Subscriber answer validated successfully"
GetProfileDetailsResponse:
type: object
required:
- name
properties:
statusCode:
type: string
example: "0000"
description: "Success API code. '0000' in case of success"
statusMessage:
type: string
example: "String"
transactionId:
type: string
example: "String"
data:
type: object
$ref: "#/definitions/GetProfileDetailsResponseData"
GetProfileDetailsResponseData:
type: "object"
title: "GetProfileDetailsResponseData"
properties:
message:
type: "string"
example: "Terms & Conditions retreived Successfully"
description: "API Success Message. i.e. This is Smartapp Terms & Conditions"
chanageSecurityQnAResponse:
type: object
required:
- name
properties:
statusCode:
type: string
example: "0000"
description: "Success API code. '0000' in case of success"
statusMessage:
type: string
example: "String"
transactionId:
type: string
example: "String"
data:
type: object
$ref: '#/definitions/chanageSecurityQnAData'
chanageSecurityQnAData:
type: "object"
title: "chanageSecurityQnAData"
properties:
message:
type: "string"
example: "QA Updated Successfully"
description: "API Success Message.i.e. QA Updated Successfully"
CreatePinResponse:
type: object
required:
- name
properties:
statusCode:
type: string
example: "0000"
description: "Success API code. '0000' in case of success"
statusMessage:
type: string
example: "String"
transactionId:
type: string
example: "String"
data:
type: object
$ref: "#/definitions/CreatePinResponseData"
CreatePinResponseData:
type: "object"
title: "CreatePinResponseData"
properties:
message:
type: "string"
example: "Subscriber secret created successfully"
description: "API Success Message. i.e. Subscriber secret created successfully"
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/234805738473/pin'
method:
type: string
description: The HTTP method type that was used
example: 'GET'