openapi: 3.2.0
info:
  description: To facilitate the capability for consumers to realize withdrawals via MADAPI. The callback (i.. Completed) will be handled via MADAPI's callback API.
  version: v1.0
  title: Mobile Money Withdrawals v1 Submit Withdrawal Request API
servers:
- url: https://preprod.mtn.com/v1
security:
- ApiKeyAuth: []
- OAuth2: []
tags:
- name: Submit Withdrawal Request
paths:
  /withdraw:
    post:
      tags:
      - Submit Withdrawal Request
      summary: Provides the ability for a consumer to execute a withdrawal request to service providers.
      description: Provides the ability for a consumer to execute a withdrawal request to service providers.
      operationId: createWithdrawal
      parameters:
      - name: transactionId
        in: header
        description: Transaction used to trance the request
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success
          headers:
            transactionId:
              description: Transaction Id as generated by MADAPI
              schema:
                type: string
          x-example: 6f0bece6-7df3-4da4-af02-5e7f16e5e6fc
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WithdrawalResponse'
        '201':
          description: Successful transaction generated.
          headers:
            Location:
              description: Location header will include the link to the newly created transaction.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WithdrawalResponse'
        '204':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WithdrawalResponse'
        '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: Customer not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '405':
          description: Method Not allowed
          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/WithdrawalRequest'
        description: Withdrawal that is created.
        required: true
components:
  schemas:
    TargetSystemEnum:
      type: string
      title: targetSystemEnum
      description: The name of the target system.
      enum:
      - ECW
      - AYO
      - EWP
    Data:
      type: object
      properties:
        transactionId:
          type: string
          description: Unique identifier in the client for the transaction in case it is needed to correlate. Generated by back-end system.
        newBalance:
          $ref: '#/components/schemas/MoneyType'
        transactionNote:
          type: string
          description: A descriptive note for sender transaction history.
          example: Manual Boost for RWC
        status:
          type: string
          description: Status of the payment method.
          example: Approved
        additionalInformation:
          $ref: '#/components/schemas/AdditionalInformation'
    CallingSystemEnum:
      type: string
      title: callingSystemEnum
      description: The name of the calling system.
      enum:
      - ECW
      - AYO
      - EWP
    MoneyType:
      type: object
      description: Representation of monetary value.
      properties:
        amount:
          format: decimal
          type: number
          description: Amount of money
          example: 50
        units:
          type: string
          description: Currency
          example: XOF
      required:
      - amount
      - units
    WithdrawalRequest:
      type: object
      properties:
        correlatorId:
          type: string
          description: Unique identifier in the client for the transaction in case it is needed to correlate.
          example: c5f80cb8-dc8b-11ea-87d0-0242ac130003
        customerId:
          type: string
          description: Customer identifier
        resource:
          type: string
          example: abcde
          description: Account identifier from the calling system
        transactionRequestDate:
          type: string
          format: date-time
          description: Date when the transaction was performed.
          example: '2020-08-12T11:04:53.668Z'
        callingSystem:
          $ref: '#/components/schemas/CallingSystemEnum'
        targetSystem:
          $ref: '#/components/schemas/TargetSystemEnum'
        description:
          type: string
          description: Text describing the contents of the transaction.
          example: Manual Boost for RW
        authorizationCode:
          type: string
          description: Authorization code retrieved from an external payment gateway that could be used for conciliation.
          example: xxxxxxxxxxxxxxxxx
        amount:
          $ref: '#/components/schemas/MoneyType'
        status:
          type: string
          description: Status of the transaction
          example: Pending
        externalReference:
          type: string
          description: Reference unique to the calling party. This must be supplied to tie up the callback.
        additionalInformation:
          type: array
          items:
            $ref: '#/components/schemas/AdditionalInformation'
      required:
      - correlatorId
      - callingSystem
      - externalReference
      - customerId
      - status
    AdditionalInformation:
      description: Additional information relating to the payment transaction.
      properties:
        name:
          type: string
          description: Name of additional information item.
          example: BundleName
        description:
          type: string
          description: Description of additional information item.
          example: Voice_1111
      required:
      - name
      - description
    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: '2019-03-22T23:00:00Z'
        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
    WithdrawalResponse:
      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. 0000 is for a success. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes'
          example: '0000'
        providerTransactionId:
          type: string
          example: FT172145YB21
          description: ID of the transaction, generated by back-end system.
        data:
          $ref: '#/components/schemas/Data'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      name: X-API-Key
      in: header
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          scopes: {}
          tokenUrl: https://mtn-preprod-preprod.apigee.net/v1/oauth/access_token