MTN Group Party Role Risk Assessment API

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 concat

# --- truncated at 32 KB (59 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mtn-group/refs/heads/main/openapi/mtn-group-partyroleriskassessment-api-openapi.yml