openapi: 3.2.0
info:
  description: The Balance Management API facilitates the management of Customer Account capabilitites. It provides a generic API any client or back-end can call to request a Topup function that allows a reseller to refill/credit a subscriber airtime account from the reseller’s account
  version: '1.0'
  title: V1 Balance Management API
servers:
- url: https://api.mtn.com/v1
security:
- ApiKeyAuth: []
- OAuth2: []
tags:
- name: Balance Management
paths:
  /accounts/{recipientPhoneNumber}/topUp:
    post:
      tags:
      - Balance Management
      summary: Provides the ability to request a TopUp on a specified balanceType
      description: Manages Customer accountBalance information by specifying the 'recipientPhoneNumber'.
      parameters:
      - name: recipientPhoneNumber
        in: path
        description: PhoneNumber of the recipient for whom the Topup is intended. The format must be E.123
        required: true
        schema:
          type: string
      - 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: false
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalanceTopUpResponse'
        '204':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalanceTopUpResponse'
        '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 No Allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '406':
          description: Not acceptable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '415':
          description: Unsopported media Type
          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/BalanceTopUpRequest'
        description: Request body
        required: true
components:
  schemas:
    BalanceTopUpResponse__links_self:
      type: object
      properties:
        href:
          type: string
          example: https://host:port/accounts/v1/balanceTopUp/12345
          description: Hyperlink to access the problem.
    Data:
      type: object
      properties:
        requestedTopUpAmount:
          $ref: '#/components/schemas/Amount'
        senderInformation:
          type: object
          properties:
            senderAccountNumber:
              type: string
              example: AYO123
              description: Account number of the Reseller on ERS
            senderAccountDescription:
              type: string
              example: Reseller account for reseller
              description: Sender Account Description
            senderCreditLimit:
              $ref: '#/components/schemas/Amount'
            senderUpdatedBalance:
              $ref: '#/components/schemas/Amount'
            senderStatus:
              type: string
              example: active
              description: The account status of the sender
            senderPhoneNumber:
              type: string
              example: 0780055601
              description: PhoneNumber of the sender / Reseller for whom the Topup is intended. The format must be E.123
        recipientInformation:
          type: object
          properties:
            recipientAccountId:
              type: string
              example: 07880056231
              description: The ERS AccountID of the Recipient
            recipientPhoneNumber:
              type: string
              example: 0788004541
              description: the recipient's Phone Number
            recipientUpdatedBalance:
              $ref: '#/components/schemas/Amount'
            actualTopUpAmount:
              $ref: '#/components/schemas/Amount'
    Amount:
      type: object
      required:
      - value
      - type
      - unit
      description: The amount details for a wallet. Decimals and negatives not allowed
      properties:
        type:
          description: This is the type of the wallet value.
          type: string
          enum:
          - CURRENCY
          - DATA
          - MINUTES
          - SMS
        value:
          type: string
          description: This is the value of a balance wallet.
          example: '45.25'
        unit:
          description: This is the unit of the wallet value.
          type: string
          enum:
          - ZAR
          - NGN
          - GB
          - MB
          - MINUTES
          - SMS
          - FCFA
          example: NGN
    BalanceTopUpResponse:
      type: object
      properties:
        statusCode:
          type: string
          description: HTTP error code extension
        Data:
          $ref: '#/components/schemas/Data'
        _links:
          $ref: '#/components/schemas/BalanceTopUpResponse__links'
    BalanceTopUpResponse__links:
      type: object
      properties:
        self:
          $ref: '#/components/schemas/BalanceTopUpResponse__links_self'
      description: Relevant links to the problem.
    BalanceTopUpRequest:
      type: object
      required:
      - balanceType
      - amount
      - senderAccountId
      properties:
        currency:
          type: string
          example: FCFA
          description: Currency of the country where topup is performed
          enum:
          - FCFA
        clientReference:
          type: string
          example: Ayo123
          description: Comment that the client want to assign to this transaction.
        balanceType:
          type: string
          example: airtime
          description: Specifying the bucket type on which the topUp should be performed.
          enum:
          - airtime
        senderAccountId:
          type: string
          example: 0788003055
          description: the AccountId on ERS of the sender. This is needed ot identify the Reseller's account on ERS
        amount:
          $ref: '#/components/schemas/Amount'
    Error:
      type: object
      properties:
        statusCode:
          type: string
          description: HTTP error code extension
        statusMessage:
          type: string
          description: More details and corrective actions related to the error which can be shown to a client.
        supportMessage:
          type: string
          description: Support Message
        transactionId:
          type: string
          description: Message ID
        _links:
          $ref: '#/components/schemas/BalanceTopUpResponse__links'
  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