openapi: 3.2.0 info: description: This API assesses risks for an MTN customer as well as creates applications version: 1.0.0 title: MTN Customer Risk Management Party Role Risk Assessment API contact: email: developer-support@mtn.com license: name: Apache 2.0 url: http://www.apache.org/licenses/LICENSE-2.0 servers: - url: https://za.api.mtn.com/v1/riskManagement security: - ApiKeyAuth: [] - OAuth2: [] tags: - name: partyRoleRiskAssessment paths: /partyRoleRiskAssessment/createApplication: post: summary: Creates a PartyRoleRiskAssessment description: This operation creates a PartyRoleRiskAssessment entity. tags: - partyRoleRiskAssessment responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/PartyRoleRiskAssessment' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' '405': description: Method Not Allowed content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: Conflict content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' requestBody: content: application/json: schema: $ref: '#/components/schemas/PartyRoleRiskAssessment_Create' required: true /partyRoleRiskAssessment/fraudRiskAssessment: post: summary: Creates a fraudRiskAssessment description: This operation creates a PartyRoleRiskAssessment entity. tags: - partyRoleRiskAssessment responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/fraudRiskAssessmentResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' '405': description: Method Not Allowed content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: Conflict content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' requestBody: content: application/json: schema: $ref: '#/components/schemas/fraudRiskAssessment' required: true /partyRoleRiskAssessment/fullVet: post: summary: Creates a Full Vet request description: This operation creates a PartyRoleRiskAssessment entity. tags: - partyRoleRiskAssessment responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/fullVetAssessmentResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' '405': description: Method Not Allowed content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: Conflict content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' requestBody: content: application/json: schema: $ref: '#/components/schemas/fullVetAssessment' required: true /partyRoleRiskAssessment/affordability: post: summary: Checks application affordability description: This operation creates a partyRole eligibility check entity. tags: - partyRoleRiskAssessment responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/AffordabilityResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' '405': description: Method Not Allowed content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: Conflict content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' requestBody: content: application/json: schema: $ref: '#/components/schemas/AffordabilityRequest' description: The partyRoleRiskAssessment to be created required: true /partyRoleRiskAssessment/avs: get: summary: AVS Decision description: This operation creates a PartyRoleRiskAssessment entity tags: - partyRoleRiskAssessment parameters: - name: applicationId in: query required: true schema: type: string - name: startDate description: The date and time when the calling system submits the request to Provenir. required: true in: query schema: type: string format: date-time - name: bankAccountNo in: query description: Bank account number for AVS schema: type: string - name: bankName in: query description: Name of applicant’s Bank schema: type: string - name: bankAccountType in: query schema: type: string enum: - Savings - Current - CreditCard default: Savings - name: branchCode in: query description: Branch Code of the Bank in which the Bank Account is held schema: type: string responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/avsResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' '405': description: Method Not Allowed content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: Conflict content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' /partyRoleRiskAssessment/orderVet: post: summary: Creates an Order Vet request description: This operation creates a PartyRoleRiskAssessment entity tags: - partyRoleRiskAssessment responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/orderVetAssessmentResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' '405': description: Method Not Allowed content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: Conflict content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' requestBody: content: application/json: schema: $ref: '#/components/schemas/orderVetAssessment' description: The partyRoleRiskAssessment to be created required: true /partyRoleRiskAssessment/ntu: get: summary: Request to confirm customer NTU description: Request to confirm the client has not continued with the order. If order is cancelled before a fullvet call (ApplicationID, Affordability or fraud call) is made then this call needs to be made to Provenir. tags: - partyRoleRiskAssessment parameters: - name: applicationId in: query required: true schema: type: string - name: requestedStartDate description: The partyRoleRiskAssessment to be created required: true in: query schema: type: string responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/ntuResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' '405': description: Method Not Allowed content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: Conflict content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' /partyRoleRiskAssessment/query: get: summary: Query Application ID description: Query Application ID tags: - partyRoleRiskAssessment parameters: - name: applicationId in: query required: true schema: type: string - name: requestedStartDate description: The partyRoleRiskAssessment to be created required: true in: query schema: type: string responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/queryResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' '405': description: Method Not Allowed content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: Conflict content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: orderVetAssessment: type: object properties: applicationId: type: string description: Application reference number requestedStartDate: type: string format: date-time currentOrderDetails: title: orderDetails type: object properties: orderLineCount: type: string description: Current Order - Number of contracts taken up orderNumber: maxLength: 30 type: string description: unique identifier for an order Mandatory for orderType="Prepaid" Optional for orderType="Postpaid" currentOrderLineItems: type: array items: type: object properties: orderOffsetMRC: type: string description: Current Order - Voluntary and Mandatory Upfront payment distributed to reduce total MRC orderSPUL: type: string description: Positive value representing the Total out of bundle spend required on all contract summed up msisdn: type: string description: Needs to be sent where applicationType = “Upgrade” dealID: type: string description: Deal Id of the Product products: type: array items: type: object properties: productid: type: string description: The code associated with the product the applicant has selected e.g. “1234” avsResponse: type: object 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: '0000' 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) errorIndicator: type: boolean description: If data validation from the calling system call is valid data: type: object properties: requestedStartDate: type: string format: date-time requestedCompletionDate: type: string format: date-time riskAssessmentResult: type: object properties: decision: type: string description: Decision engine decision on call (“Continue”/”Decline”) example: Continue reasonCode: type: string description: Code to uniquely identify each reason returned reasonDescription: type: string description: Text to be displayed to calling system for reason of decision attemptsRemaining: type: integer description: Number of attempts left to change bank details fraudServiceBlock: type: object properties: fraudCheckType: type: string description: Fraud check type as passed in the original request fraudResStartTime: type: string description: Date and Timestamp of the Request start time in the Provenir system fraudResEndTime: type: string description: Date and Timestamp of the Response End in the Provenir system fraudDecision: type: string description: DE decision on call (Approve/Refer/Decline) fraudReasons: type: array items: $ref: '#/components/schemas/fraudReason' phone: type: object properties: phoneType: type: string description: Type of the number – Mobile/Home/Business example: Mobile areaCode: type: string description: Area code for the phone number example: 9 countryCode: type: string description: Country code for the phone number example: 27 value: type: string description: Type of the number – Mobile/Home/Business example: 0214700080 orderVetAssessmentResponse: type: object 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: '0000' maxLength: 30 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) errorIndicator: type: boolean description: If data validation from the calling system call is valid (“true” / “false”) e.g., false data: type: object properties: id: type: string description: Unique identifier of the application decision: type: string description: Decision engine decision on call ("Approve"/"Decline"/"Refer") example: Decline declineReviewInd: type: boolean description: Is decline review allowed (“true” / “false”) limitReviewInd: type: boolean description: Is decline review allowed (“true” / “false”) reviseOrderInd: type: boolean description: Is decline review allowed (“true” / “false”) approvedWithConditionsInd: type: boolean description: Is decline review allowed (“true” / “false”) condition: type: object properties: conditionReasonCode: type: string description: Code to uniquely identify each reason returned conditionValue: type: string description: Conditional value that needs to be met conditionReasonDesc: type: string description: Description of Condition to be met fraudRiskAssessmentResponse: type: object 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: '0000' maxLength: 30 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) errorIndicator: type: boolean description: If data validation from the calling system call is valid (“true” / “false”) e.g., false data: type: object properties: id: type: string description: Unique identifier of the application overallFraudDecision: type: string description: Overall DE decision on application (Continue OR Decline) example: Decline fraudServiceBlocks: type: array items: $ref: '#/components/schemas/fraudServiceBlock' queryResponse: type: object 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: '0000' 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) data: type: object properties: application: type: object properties: id: type: string description: Unique identifier of the application requestedStartDate: type: string format: date-time description: Date and Timestamp of the Provenir system. Java Zoned Date and time - Africa/Johannesburg (UTC+02:00) requestedCompletionDate: type: string format: date-time description: Date and Timestamp of the Provenir system. Java Zoned Date and time - Africa/Johannesburg (UTC+02:00) errorIndicator: type: boolean description: If data validation from the calling system call is valid errorDescription: type: string description: Reason of what failed validation, will be concatenated if more than one fraud: type: object properties: id: type: string description: Unique identifier of the application errorIndicator: type: boolean description: If data validation from the calling system call is valid errorDescription: type: string description: Reason of what failed validation, will be concatenated if more than one overallFraudDecision: type: string description: Overall DE decision on application (Continue OR Decline) example: Decline fraudServiceBlocks: type: array items: $ref: '#/components/schemas/fraudServiceBlock' affordability: type: object properties: id: type: string description: Unique identifier of the application errorIndicator: type: boolean description: If data validation from the calling system call is valid errorDescription: type: string description: Reason of what failed validation, will be concatenated if more than one requestedStartDate: type: string format: date-time description: Date and Timestamp of the Request start time in the Provenir system. Java Zoned Date and time - Africa/Johannesburg (UTC+02:00) requestedCompletionDate: type: string format: date-time description: Date and Timestamp of the Request start time in the Provenir system. Java Zoned Date and time - Africa/Johannesburg (UTC+02:00) riskAssessment: type: object properties: recommendation: type: string description: Recommendation to be offered to customer (“Full deal” / “SIM only”) e.g, “Full Deal” remainingCreditLimit: type: number format: float description: Remaining Credit limit based on new credit limit considering existing exposure creditLimit: type: number format: float description: Credit amount provided to applicant, -1 will be given when a decline fullVet: type: object properties: id: type: string description: Unique identifier of the application errorIndicator: type: boolean description: If data validation from the calling system call is valid errorDescription: type: string description: Reason of what failed validation, will be concatenated if more than one caseNumber: type: string description: Case Management ref no. as received from the MTN API decision: type: string description: Decision engine decision on call ("Approve"/"Decline"/"Refer") example: Decline finalReason: type: object properties: reasonCode: type: string description: Code to uniquely identify each reason returned reasonDescription: type: string description: Text to be displayed to Siebel for reason of decision declineReviewInd: type: boolean description: Is decline review allowed (“true” / “false”) limitReviewInd: type: boolean description: Is decline review allowed (“true” / “false”) reviseOrderInd: type: boolean description: Is decline review allowed (“true” / “false”) approvedWithConditionsInd: type: boolean description: Is decline review allowed (“true” / “false”) condition: type: object properties: conditionReasonCode: type: string description: Code to uniquely identify each reason returned conditionValue: type: string description: Conditional value that needs to be met conditionReasonDesc: type: string description: Description of Condition to be met expiry: type: string description: Expiry date of Fullvet call, if expired order should auto cancel – UTC ISO 8601 example: 1981-06-02 orderVet: type: object properties: id: type: string description: Unique identifier of the application errorIndicator: type: boolean description: If data validation from the calling system call is valid errorDescription: type: string description: Reason of what failed validation, will be concatenated if more than one decision: type: string description: Decision engine decision on call ("Approve"/"Decline"/"Refer") example: Decline declineReviewInd: type: boolean description: Is decline review allowed (“true” / “false”) limitReviewInd: type: boolean description: Is decline review allowed (“true” / “false”) reviseOrderInd: type: boolean description: Is decline review allowed (“true” / “false”) approvedWithConditionsInd: type: boolean description: Is decline review allowed (“true” / “false”) condition: type: object properties: conditionReasonCode: type: string description: Code to uniquely identify each reason returned conditionValue: type: string description: Conditional value that needs to be met conditionReasonDesc: type: string description: Description of Condition to be met avs: type: object properties: requestedStartDate: type: string format: date-time requestedCompletionDate: type: string format: date-time errorIndicator: type: boolean description: If data validation from the calling system call is valid errorDescription: type: string description: Reason of what failed validation, will be concatenated if more than one riskAssessmentResult: type: object properties: decision: type: string description: Decision engine decision on call (“Continue”/”Decline”) example: Continue reasonCode: type: string description: Code to uniquely identify each reason returned reasonDescription: type: string description: Text to be displayed to calling system for reason of decision attemptsRemaining: type: integer description: Number of attempts left to change bank details 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 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: /loans/2348024008124/... AffordabilityResponse: type: object 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: '0000' maxLength: 30 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) errorIndicator: type: boolean description: If data validation from the calling system call is valid (“true” / “false”) e.g., false data: type: object properties: id: type: string description: Unique identifier of the application requestedStartDate: type: string format: date-time description: Date and Timestamp of the Request start time in the Provenir system. Java Zoned Date and time - Africa/Johannesburg (UTC+02:00) requestedCompletionDate: type: string format: date-time description: Date and Timestamp of the Request start time in the Provenir system. Java Zoned Date and time - Africa/Johannesburg (UTC+02:00) riskAssessment: type: object properties: recommendation: type: string description: Recommendation to be offered to customer (“Full deal” / “SIM only”) e.g, “Full Deal” remainingCreditLimit: type: number format: float description: Remaining Credit limit based on new credit limit considering existing exposure creditLimit: type: number format: float description: Credit amount provided to applicant, -1 will be given when a decline PartyRoleRiskAssessment_Create: type: object properties: requestedStartDate: type: string format: date-time description: Date and Timestamp of the requesting system. Java Zoned Date and time - Africa/Johannesburg (UTC+02:00) channel: required: - id type: array items: type: object properties: name: maxLength: 30 type: string description: The name of the requesting channel enum: - Online - Store - TeleSales role: type: string description: Role playing by the channel. merchantType: maxLength: 1 type: string description: is this request for MTN or an external party "I" - Internal MTN request, "E" - External request (future) enum: - I - E orderDetails: title: orderDetails type: array description: Array of order details items: required: - subscriptionType type: object properties: subscriptionType: maxLength: 30 type: string description: the type of order that the request relates to "Postpaid" - Postpaid Contract, "Prepaid" - Prepaid Sale/Purchase e.g. Prepaid Sales, Bundle Add-On enum: - Prepaid - Postpaid orderNumber: maxLength: 30 type: string description: unique identifier for an order Mandatory for orderType="Prepaid" Optional for orderType="Postpaid" application: required: - applicationType - customerType - customerClass type: object properties: applicationType: maxLength: 30 type: string description: Type of application being processed "New"/"Upgrade"/"Addsim"/"M2M" New - If the applicant has not had an account with MTN previously and is a completely new/first time applicant. Applicant without an active postpaid account Upgrade - If the applicant is an existing MTN customer that wants to upgrade his contract ` Addsim - If the applicant is an existing MTN customer and wants to add an additional SIM onto his current contract M2M (Month-to-month)- If the applicant is an existing MTN customer and has now opted for a month-to-month postpaid contract, with payment in advance and can terminate at any time. If the applicant is a new/existing MTN customer and has now opted for a month-to-month new postpaid contract, with payment in advance and can terminate at any time (possible device cost claw back) enum: - New - Addsim - Upgrade - M2M customerType: maxLength: 30 type: string description: ID to denote the Customer Type "CONS” = Consumer-CBU, “ECON” = Employee Connect-EBU, “STAFF” = Staff-CBU This value is to define the specific order application. enum: - CONS - ECON - STAFF customerClass: maxLength: 30 type: string description: for CustomerType = "CONS", CustomerClass- CONS (default)/M2M. for CustomerType = “ECON” , CustomerClass- ECON (default)/M2M. for CustomerType = “STAFF”, CustomerClass- “STAFF” enum: - CONS - ECON - STAFF - M2M partyRole: required: - party type: object properties: type: maxLength: 30 type: string description: Individual or Enterprise enum: - Individual - Enterprise fraudCheckType: type: string description: The fraud type request to be executed A - DeviceVerfication B - WatchList, FPM&SAFPS, Mobile Verfication C - EmailVerification D - MTNInternalHotList E - MobileVerfication example: A,B,C,D relatedParty: required: - firstName - lastName - idType - idNumber - dateOfBirth - gender type: object properties: idType: type: string description: The ID type being used to create the profile. Possible Values are ''RSAID'', ''PASSPORT'''. This field is mandatory while creating a customer. enum: - RSAID - PASSPORT idNumber: maxLength: 30 type: string description: Id number based on ID type. This field is mandatory while creating a customer. firstName: maxLength: 30 type: string description: 'First full name of the subscriber as per RSA ID or Passport. This field is mandatory while creating a customer. ' lastName: maxLength: 30 type: string description: Surname name of the subscriber as per RSA ID or Passport. This field is mandatory while creating a customer. Character length 50 gender: type: string description: subscriber's Gender. This field is mandatory while creating a customer. enum: - M - F - O dateOfBirth: maxLength: 10 type: string description: subscriber's date of birth. This field is mandatory while creating a customer. Date Format "YYYY-MM-DD" format: date fullVetAssessment: type: object properties: applicationId: type: string description: Application reference number requestedStartDate: type: string format: date-time description: Date and Timestamp of the Request start time in the Provenir system. Java Zoned Date and time - Africa/Johannesburg (UTC+02:00) suspectedFraudInd: type: boolean description: Does sales agent suspect fraud (“true” / “false”) authenticationType: type: string description: The authentication type passed for the application to progress to FULLVET. example: BIO biometricsColour: type: string description: Biometrics colour for the application (“Green”/ ”Yellow”). example: Yellow currentOrderDetails: title: orderDetails type: object properties: orderLineCount: type: string description: Current Order - Number of contracts taken up orderNumber: maxLength: 30 type: string description: unique identifier for an order Mandatory for orderType="Prepaid" Optional for orderType="Postpaid" currentOrderLineItems: type: array items: type: object properties: orderOffsetMRC: type: string description: Current Order - Voluntary and Mandatory Upfront payment distributed to reduce total MRC orderSPUL: type: string description: Positive value representing the Total out of bundle spend required on all contract summed up msisdn: type: string description: Needs to be sent where applicationType = “Upgrade” dealID: type: string description: Deal Id of the Product products: type: array items: type: object properties: productid: type: string description: The code associated with the product the applicant has selected e.g. “1234” address: type: object properties: addressType: type: string description: The address Type (“Residential” / “Delivery”) example: Residential addressLine1: type: string description: Line 1 of the address example: 52 Street addressLine2: type: string description: Line 2 of the address example: LOVELY AREA suburb: type: string description: Suburb of the address example: ILLOVO city: type: string description: City of the address example: Cape Town province: type: string description: Province of the address example: GP postalCode: type: string description: Postal of the address example: 2196 fraudRiskAssessment: type: object properties: applicationId: type: string description: Application reference number requestedStartDate: type: string format: date-time description: Date and Timestamp of the requesting system. Java Zoned Date and time - Africa/Johannesburg (UTC+02:00) partyRole: required: - party type: object properties: type: maxLength: 30 type: string description: Individual or Enterprise enum: - Individual - Enterprise fraudCheckType: type: string description: The fraud type request to be executed A - DeviceVerfication B - WatchList, FPM&SAFPS, Mobile Verfication C - EmailVerification D - MTNInternalHotList E - MobileVerfication example: A,B,C,D relatedParty: type: object properties: email: type: string description: Contact email address for the applicant. firstName: maxLength: 30 type: string description: 'First full name of the subscriber as per RSA ID or Passport. This field is mandatory while creating a customer. ' lastName: maxLength: 30 type: string description: Surname name of the subscriber as per RSA ID or Passport. This field is mandatory while creating a customer. Character length 50 gender: type: string description: subscriber's Gender. This field is mandatory while creating a customer. enum: - M - F - O dateOfBirth: maxLength: 10 type: string description: subscriber's date of birth. This field is mandatory while creating a customer. Date Format "YYYY-MM-DD" format: date surname: type: string description: Surname of the subscriber addresses: type: array items: $ref: '#/components/schemas/address' phones: type: array items: $ref: '#/components/schemas/phone' dealerCode: type: string description: SABC code of originating dealer agentID: type: string description: ID of originating Agent ipAddress: type: string description: IPV4 or IPV6 address from where the transaction is being submitted blackboxString: type: string description: Iovation black box value (generated via JavaScript on web/SDK on app).Encoded string up to 4KB. AffordabilityRequest: type: object properties: applicationId: type: string description: Unique identifier of the application requestedStartDate: type: string format: date-time description: Date and Timestamp of the Provenir system. Java Zoned Date and time - Africa/Johannesburg (UTC+02:00) price: type: object description: Provides all amounts (tax included, duty free, tax rate) properties: dutyFreeAmount: $ref: '#/components/schemas/Money' description: All taxes excluded amount (expressed in the given currency) taxIncludedAmount: $ref: '#/components/schemas/Money' description: All taxes included amount (expressed in the given currency) additionalAmount: $ref: '#/components/schemas/Money' description: Positive value representing the amount of additional income provided by customer. This should be a monthly amount. billingAccount: description: Bank statement details that are uploaded for Bank Statement raw data retrieval. type: array items: type: object properties: bankAccountNo: type: string description: Bank account number bankAccountType: type: string description: Applicant Bank Account Type 'Savings' 'Current' 'Credit Card' e.g. “Savings” Default to blank if unavailable. branchCode: type: string description: Branch Code of the Bank in which the Bank Account is held. Default to zero if unavailable. bankName: type: string description: Name of applicant Bank totalIncome: type: number format: float description: Positive value representing the Total Income verified from the Bank Statement raw data e.g. 58000.50 Default to zero if unavailable. totalExpense: type: number format: float description: Positive value representing the Total Expenses verified from the Bank Statement raw data e.g. 6000.75 Default to zero if unavailable. bouncedDebitOrders: type: number description: Total bounced debit orders verified from the Bank Statement raw data. Default to zero if unavailable. PartyRoleRiskAssessment: type: object 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: '0000' maxLength: 30 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) errorIndicator: type: boolean description: If data validation from the calling system call is valid (“true” / “false”) e.g., false data: type: object properties: id: type: string description: Unique identifier of the application requestedStartDate: type: string format: date-time description: Date and Timestamp of the Provenir system. Java Zoned Date and time - Africa/Johannesburg (UTC+02:00) requestedCompletionDate: type: string format: date-time description: Date and Timestamp of the Provenir system. Java Zoned Date and time - Africa/Johannesburg (UTC+02:00) fullVetAssessmentResponse: type: object 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: '0000' maxLength: 30 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) errorIndicator: type: boolean description: If data validation from the calling system call is valid (“true” / “false”) e.g., false data: type: object properties: id: type: string description: Unique identifier of the application caseNumber: type: string description: Case Management ref no. as received from the MTN API decision: type: string description: Decision engine decision on call ("Approve"/"Decline"/"Refer") example: Decline finalReason: type: object properties: reasonCode: type: string description: Code to uniquely identify each reason returned reasonDescription: type: string description: Text to be displayed to Siebel for reason of decision declineReviewInd: type: boolean description: Is decline review allowed (“true” / “false”) limitReviewInd: type: boolean description: Is decline review allowed (“true” / “false”) reviseOrderInd: type: boolean description: Is decline review allowed (“true” / “false”) approvedWithConditionsInd: type: boolean description: Is decline review allowed (“true” / “false”) condition: type: object properties: conditionReasonCode: type: string description: Code to uniquely identify each reason returned conditionValue: type: string description: Conditional value that needs to be met conditionReasonDesc: type: string description: Description of Condition to be met expiry: type: string description: Expiry date of Fullvet call, if expired order should auto cancel – UTC ISO 8601 example: 1981-06-02 Money: type: object description: A base / value business entity used to represent money properties: value: type: number format: float description: A positive floating point number fraudReason: type: object properties: reasonCode: type: string description: Code to uniquely identify each reason returned reasonDescription: type: string description: Text to be displayed to calling system for reason of decision ntuResponse: type: object 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: '0000' 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) errorIndicator: type: boolean description: If data validation from the calling system call is valid data: type: object properties: requestedStartDate: type: string format: date-time requestedCompletionDate: type: string format: date-time securitySchemes: ApiKeyAuth: type: apiKey name: X-API-Key in: header OAuth2: type: oauth2 flows: clientCredentials: scopes: {} tokenUrl: https://api.mtn.com/v1/oauth/access_token