swagger: '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
schemes:
  - https
host: "preprod.mtn.com"
basePath: /v1
consumes:
  - application/json
produces:
  - application/json
securityDefinitions:
  ApiKeyAuth:
    type: apiKey
    name: X-API-Key
    in: header
  OAuth2:
    type: oauth2
    flow: application
    tokenUrl: 'https://mtn-preprod-preprod.apigee.net/v1/oauth/access_token'
security:
  - ApiKeyAuth: []
  - OAuth2: []
tags:
  - name: Withdrawal
    description: Withdrawal instruction.
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: withdrawalRequest
          in: body
          description: Withdrawal that is created.
          required: true
          schema:
            $ref: '#/definitions/WithdrawalRequest'
        - name: transactionId
          in: header
          description: Transaction used to trance the request
          required: false
          type: string
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/WithdrawalResponse'
          headers:
            transactionId:
              type: string
              description: Transaction Id as generated by MADAPI
          x-example: 6f0bece6-7df3-4da4-af02-5e7f16e5e6fc
        '201':
          description: Successful transaction generated.
          schema:
            $ref: '#/definitions/WithdrawalResponse'
          headers:
            Location:
              type: string
              description: >-
                Location header will include the link to the newly created
                transaction.
        '204':
          description: Success
          schema:
            $ref: '#/definitions/WithdrawalResponse'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/Error'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/Error'
        '403':
          description: Forbidden
          schema:
            $ref: '#/definitions/Error'
        '404':
          description: Customer not found
          schema:
            $ref: '#/definitions/Error'
        '405':
          description: Method Not allowed
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/Error'
definitions:
  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: '#/definitions/CallingSystemEnum'
      targetSystem:
        $ref: '#/definitions/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: '#/definitions/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: '#/definitions/AdditionalInformation'
    required:
      - correlatorId
      - callingSystem
      - externalReference
      - customerId
      - status

  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
  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

  CallingSystemEnum:
    type: string
    title: callingSystemEnum
    description: The name of the calling system.
    enum:
      - "ECW"
      - "AYO"
      - "EWP"
  TargetSystemEnum:
    type: string
    title: targetSystemEnum
    description: The name of the target system.
    enum:
      - "ECW"
      - "AYO"
      - "EWP"
  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: '#/definitions/Data'


  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: '#/definitions/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: '#/definitions/AdditionalInformation'
  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"