openapi: 3.2.0
info:
  description: A suite of apis for customer consent validation.
  version: 2.0.0
  title: Consent Validation Create Customer PreApproval API
servers:
- url: https://api.mtn.com/v1
security:
- ApiKeyAuth: []
- OAuth2: []
tags:
- name: Create Customer PreApproval
paths:
  /consent/preapproval:
    post:
      tags:
      - Create Customer PreApproval
      summary: Provides the ability to create a customer PreApproval Request
      description: Manages Customer PreApproval information by specifying the from and to 'customerIds'. For most solution the to and from customer id's will be the same. This functionality is used when the preapprovals are used to preapprove future debit transaction between different parties.
      parameters:
      - name: transactionId
        in: header
        description: Client generated Id to include for tracing requests, so that the API can easily trace the HTTP request all the way from a client to MTNs backend processes (via our proxies). Each time a request is made to an MTN API the client should include a unique request reference in the HTTP Header. The value must be between 5 and 20 characters, and consist of ASCII letters, digits, or the characters +, /, =, and -. Invalid or blank IDs will be ignored and replaced with generated ones. MTN may use this to detect duplicate transactions from the client, but this functionality is not always guaranteed, so clients must make their own efforts to prevent duplicate transactions. MTN will also log the transactionId in order to assist with debugging and to correlate transactions processed by the API to requests from the client.
        required: true
        schema:
          type: string
      - name: X-Authorization
        in: header
        description: Encrypted ECW credentials
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/preapprovalResponse'
        '204':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/preapprovalResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/preapprovalError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/preapprovalError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/preapprovalError'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/preapprovalError'
        '405':
          description: Method No Allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/preapprovalError'
        '406':
          description: Not acceptable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/preapprovalError'
        '415':
          description: Unsupported media Type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/preapprovalError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/preapprovalError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/preapprovalRequest'
        description: Request body
        required: true
components:
  schemas:
    preapprovalData:
      type: object
      properties:
        preapprovalStatus:
          type: string
          example: APPROVED
          description: Current status of the preapproval. Valid values that is expected in the return is APPROVED, EXPIRED, PENDING, REJECTED
        expiryTime:
          type: string
          format: dateTime
          description: Expiry date and time of the preapproval. Expected format is yyyy:DD:mmThh:mm:ssZ
          example: 2020-05-30 17:00:00+00:00
        existingPreapproval:
          type: boolean
          example: true
          description: Indicates whether an existing preapproval exists
    preapprovalError:
      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: /subscribers/27831234567
        method:
          type: string
          description: The HTTP method type that was used
          example: GET
    preapprovalRequest:
      type: object
      required:
      - message
      properties:
        fromCustomerId:
          type: string
          example: FRI:2330183736/MSISDN
          description: The sending account of the approval (typically but not necessarily, the customer/subscriber information)
        toCustomerId:
          type: string
          example: FRI:ayo.deposit/USER
          description: The receiving entity of the approval (typically but not necessarily, a wallet)
        fromCurrency:
          type: string
          example: ZAR
          description: The currency code of the sending account. It is the consuming client's responsibility to populate this with a valid value.
        toCurrency:
          type: string
          example: GBP
          description: The currency code of the receiving account. It is the consuming client's responsibility to populate this with a valid value.
        message:
          type: string
          example: Please process preapproval
          description: Message to be considered for preapproval request. Max 256 characters allowed
        duration:
          type: string
          format: long
          example: 20
          description: Duration in seconds for which the preapproval would be valid, Numeric 64-bit signed value, Null and Zero allowed.
        callbackURL:
          type: string
          minLength: 8
          maxLength: 256
          example: https://api.mtn.com/v1/preapprovalCompleted/ece09e1b-77e1-45f2-8da0-83a82e05258a
          description: Callback URL of the calling application of this API, for the preapprovalCompleted notification to be sent back
        referenceId:
          type: string
          example: ece09e1b-77e1-45f2-8da0-83a82e05258a
          description: External Reference. This number must be unique as the consuming client will have to store and use this number to tie the callback.
    preapprovalResponse__links:
      type: object
      properties:
        self:
          $ref: '#/components/schemas/preapprovalResponse__links_self'
      description: Relevant links to the problem.
    preapprovalResponse:
      type: object
      properties:
        statusCode:
          type: string
          description: HTTP error code extension
        preapprovalId:
          type: string
          example: 12456789
          description: ID of the preapproval, generated by back-end system
        data:
          $ref: '#/components/schemas/preapprovalData'
        _links:
          $ref: '#/components/schemas/preapprovalResponse__links'
    preapprovalResponse__links_self:
      type: object
      properties:
        href:
          type: string
          example: https://host:port/consent/v1/preapprovals/12345
          description: Hyperlink to access the problem.
  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