swagger: '2.0'
info:
  version: v.2.1
  title: MTN Customer Plans API
  contact:
    name: MTN API Support
    email: developer-support@mtn.com
  description: An API to retrieve the Plan details of an MTN customer and calculate aYo premiums. Can also be used by 3rd-party partners (3PP) for airtime recharge of a prepaid subscriber
host: api.mtn.com
basePath: /v2
schemes:
  - https
consumes:
  - application/json
produces:
  - application/json
securityDefinitions:
  ApiKeyAuth:
    type: apiKey
    name: X-API-Key
    in: header
  OAuth2:
    type: oauth2
    flow: application
    tokenUrl: 'https://api.mtn.com/v1/oauth/access_token'
security:
  - ApiKeyAuth: []
  - OAuth2: []
paths:
  '/customers/{customerId}/plans':
    get:
      description: Retrieves the Billing Plan and related details of an MTN customer.
      summary: View customer plans
      tags:
        - Customers
      parameters:
        - name: customerId
          in: path
          description: 'ID of the customer. It could be MSISDN, email address, or any other customer identifier. if id is msisdn, format must be Eg.123'
          required: true
          type: string
        - name: fixedLine
          in: query
          description: Fixed line whose balances is fetched
          required: false
          type: string
        - name: plan
          in: query
          description: Plan type to filter list of balances
          required: false
          type: string
          enum:
            - VOICE
            - DATA
            - SMS
        - name: momo
          in: query
          description: Indicates whether to query balances for a MoMo Customer
          required: false
          type: boolean
        - name: includeReservations
          in: query
          description: Indicates whether reservations should be included in the response. This parameter goes hand in hand with the momo query parameter and will have no use if supplied when momo is not true. Default is false.
          required: false
          type: boolean
        - name: quoteid
          in: query
          description: Indicates whether a corresponding quote should be considered. This parameter goes hand-in-hand with the momo query parameter and will have no use if supplied when momo is not true.
          required: false
          type: string
        - name: x-authorization
          in: header
          description: Encrypted ECW credentials
          required: false
          type: string
      responses:
        '200':
          description: 'Customer Plans object. For a successful request, the response will contain all the customers details. If the customer does not have any requested data, then those fields will be null. E.g. if the customer does not have a startDate set, then it will be null. If the customer does not have any Balance set, then the Balance array will be null.'
          schema:
            $ref: '#/definitions/CustomerPlans'
        '207':
          description: 'If there was an error retrieving some part of the request, then the successful request will be shown, and the remaining failed objects will be be excluded. E.g. if there was an error retrieving Balance information, then the balance object will be empty'
          examples:
            'Partially Successfuls Response, showing valid plan data, but balance object is null':
              data:
                type: Postpaid
                status: Active
                startDate: '2019-04-12T14:31:21.810Z'
                endDate: '2021-04-12T14:31:21.810Z'
                language: '1'
                balance: null
        '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
          examples:
            The data object/envelope will be null:
              data: null
        '405':
          description: Method Not allowed
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/Error'
    post:
      description: Requesting a MTN customer's premium per product.
      summary: Request Premium
      tags:
        - Premiums
      parameters:
        - name: customerId
          in: path
          description: 'ID of the customer who is sending the transaction. It could be MSISDN, email address, or any other customer identifier. if id is msisdn, format must be E.123'
          required: true
          type: string
        - in: body
          name: body
          description: Request body
          required: true
          schema:
            $ref: '#/definitions/PremiumRequest'
      responses:
        '200':
          description: 'Customer Plans Premium object. For a successful request, the response will contain all the customers Premium details. If the customer does not have any requested data, then those fields will be null."'
          schema:
            $ref: '#/definitions/CustomerPremium'
        '207':
          description: 'If there was an error retrieving some part of the request, then the successful request will be shown, and the remaining failed objects will be be excluded.'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/PremiumError'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/PremiumError'
        '403':
          description: Forbidden
          schema:
            $ref: '#/definitions/PremiumError'
        '404':
          description: Customer not found
          examples:
            The data object/envelope will be null:
              data: null
        '405':
          description: Method Not allowed
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/PremiumError'            
  '/customers/{customerId}/plans/{productCode}':
    get:
      description: Retrieves plans for product
      summary: View customer plans for product
      tags:
        - Customers
      security:
        - ApiKeyAuth: []
      parameters:
        - name: customerId
          in: path
          description: 'ID of the customer. It could be MSISDN, email address, or any other customer identifier. if id is msisdn, format must be E.123'
          required: true
          type: string
        - name: productCode
          in: path
          description: Product code for data package
          required: true
          type: string
      responses:
        '200':
          description: 'Customer Plans object. For a successful request, the response will contain all the plans details. If the customer does not have any requested data, then those fields will be null. E.g. if the customer does not have a startDate set, then it will be null. If the customer does not have any Balance set, then the Balance array will be null.'
          schema:
            $ref: '#/definitions/CustomerPlans'
        '207':
          description: 'If there was an error retrieving some part of the request, then the successful request will be shown, and the remaining failed objects will be be excluded. E.g. if there was an error retrieving Balance information, then the balance object will be empty'
          examples:
            'Partially Successfuls Response, showing valid plan data, but balance object is null':
              data:
                type: Postpaid
                status: Active
                startDate: '2019-04-12T14:31:21.810Z'
                endDate: '2021-04-12T14:31:21.810Z'
                language: '1'
                balance: null
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/Error'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/Error'
        '403':
          description: Forbidden
          schema:
            $ref: '#/definitions/Error'
  '/customers/{customerId}/plans/refill':
    patch:
      tags:
        - Customers
      summary: Airtime Refill
      description: Will be used by 3rd-party partners (3PP) for airtime recharge of a prepaid subscriber
      operationId: refillAccount
      security:
        - ApiKeyAuth: []
      parameters:
        - name: customerId
          in: path
          description: 'ID of the customer. It could be MSISDN, email address, or any other customer identifier. if id is msisdn, format must be E.123'
          type: string
          required: true
        - name: transactionId
          in: header
          description: Client generated unique Id to include for tracing requests
          type: string
          required: false
        - name: sourceSystemId
          in: header
          description: Source system Id to include for tracing requests
          type: string
          required: false
        - name: refillRequest
          in: body
          required: true
          schema:
            type: object
            required:
              - refillType
            properties:
              refillType:
                type: string
                description: Specify the refill type
                enum:
                  - voucher
                  - voucherless
              voucherActivationCode:
                type: string
                description: 'Voucher Activation Code, Required if refillType is Voucher Base.'
              refillProfileId:
                type: string
                description: 'Refill Profile ID, Required if refillType is Voucherless.'
              transactionAmount:
                type: string
                description: Required if refillType is Voucherless
      responses:
        '200':
          description: OK
          schema:
            type: object
            properties:
              statusCode:
                type: string
                description: HTTP error code extension
              statusMessage:
                type: string
              data:
                type: object
                properties:
                  amount:
                    type: string
                    description: 'The whole units of the amount. For example if currency is NGN, then 100 unit is'
                  currencyCode:
                    type: string
                    description: The 3-letter currency code defined in ISO 4217.
              _link:
                type: object
                properties:
                  self:
                    type: object
                    properties:
                      href:
                        type: string
                        example: 'https://api.mtn.com/v1/customers/2348064816493/refill'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/Error'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/Error'
        '403':
          description: Forbidden
          schema:
            $ref: '#/definitions/Error'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/Error'
        '503':
          description: Service Unavailable
          schema:
            $ref: '#/definitions/Error'
        '999':
          description: Unknown Error
          schema:
            $ref: '#/definitions/Error'
definitions:
  PremiumRequest:
    type: object
    required:
      - receivingCustomerId
      - transactionId
      - product
      - amount
      - transactionType
    properties:
      amount:
        type: string
        $ref: '#/definitions/Amount'
      transactionId:
        type: string
        description: Internal correlation ID
      accountHolderId:
        type: string
        description: The accountholder's ID to which the sendingCustomerId belong
      quoteId:
        type: string
        description: Can be provided when a quote is associated with the request.
      receivingCustomerId:
        type: string
        description: The beneficiary's customer ID.
      product:
        type: string
        description: The product for which the premium is requested
      transactionType:
        type: string
        description: Different transaction types can have different premiums associated with it.
      message:
        type: string
        description: The calling customer can populate a message intended for the back-end application.
  CustomerPremium:
    type: object
    required:
      - originReferenceId
    properties:
      originReferenceId:
        type: string
        description: Origin Reference Id
      statusCode:
        type: string
        description: 'This will have MADAPI response mapping, based on the value received from the downstream system'
      data:
        $ref: '#/definitions/PremiumData'
      link:
        $ref: '#/definitions/PremiumResponse__links'
  PremiumData:
    type: object
    description: Contains response information pertaining to the premium request.
    properties:
      message:
        type: string
        description: A message send by the back end pertaining to the premium calculation request
      premium:
        $ref: '#/definitions/Amount'
      loyaltyInformation:
        $ref: '#/definitions/LoyaltyBalances'
  LoyaltyBalances:
    type: object
    description: Contains all the loyalty balances associated with a customer.
    properties:
      generatedAmount:
        $ref: '#/definitions/Amount'
      consumedAmount:
        $ref: '#/definitions/Amount'
      newBalance:
        $ref: '#/definitions/Amount'
  Customer:
    type: object
    required:
      - customerId
      - _links
    properties:
      customerId:
        type: string
      plans:
        type: object
        description: The customers billing plan
        $ref: '#/definitions/CustomerPlans'
  CustomerLinks:
    type: object
    required:
      - self
    properties:
      self:
        type: object
        required:
          - href
        description: The link to retrieve the plans for a customer.
        properties:
          href:
            type: string
            description: The link to retrieve the plans for a customer.
            example: 'https://api.mtn.com/v2/customers/27832000000/plan'
  CustomerPlans:
    type: object
    required:
      - _link
    properties:
      _link:
        $ref: '#/definitions/CustomerLinks'
      data:
        $ref: '#/definitions/Plans'
  MomoBalanceDetail:
    type: object
    description: The MoMo Balance details for a requested customer.
    properties:
      balance:
        description: Account holder's available balance for the requested financial resource.
        $ref: '#/definitions/Amount'
      positiveReservations:
        description: Account holder's positive reservations (pending incoming transactions) for the requested financial resource. This value is set if the includereservations field in the request is set to true.
        $ref: '#/definitions/Amount'
      negativeReservations:
        description: Account holder's negative reservations (pending outgoing transactions for the requested financial resource. This value is set if the includereservations field in the request is set to true.
        $ref: '#/definitions/Amount'
      loyaltyInformation:
        $ref: '#/definitions/LoyaltyBalances'
      overdraft:
        $ref: '#/definitions/OverdraftInformation'
  OverdraftInformation:
    type: object
    description: Contains overdraft balances if available
    properties:
      balance:
        $ref: '#/definitions/Amount'
      limit:
        $ref: '#/definitions/Amount'
      accessFee:
        $ref: '#/definitions/Amount'
      interest:
        $ref: '#/definitions/Amount'
  Plans:
    type: object
    required:
      - type
      - status
      - startDate
      - endDate
      - language
      - tariffPlan
      - balance
    description: The plan details for the customer.
    properties:
      type:
        type: string
        description: The billing type of the plan.
        enum:
          - Prepaid
          - Postpaid
          - Hybrid
      status:
        type: string
        description: The current status of the plan.
        enum:
          - Active
          - Suspended
          - Inactive
          - RICA Barred
          - Blacklisted
      startDate:
        type: string
        description: The date the customer was created/provisioned
        format: date-time
      endDate:
        type: string
        description: The date the plan will be deactivated.
        format: date-time
      language:
        type: string
        description: The customers language.
      tariffPlan:
        type: string
        description: The customers active tariff plan.
      balance:
        type: array
        description: The account balance details of a customer
        items:
          $ref: '#/definitions/CustomerBalance'
      offers:
        $ref: '#/definitions/OfferDetails'
  CustomerBalance:
    type: object
    required:
      - balanceType
      - expiryDate
      - balanceDetail
      - wallets
    description: The plan balance details for the customer.
    properties:
      balanceType:
        type: string
        description: 'Identifies the type of balance. A customer plan may have multiple types of balances for different usage, for example, voice, SMS, and game services.'
      expiryDate:
        type: string
        format: date-time
        description: Expiry date of the wallet's value.
      category:
        type: string
        description: Identifies the category of the balance type.
      balanceDetail:
        $ref: '#/definitions/BalanceDetail'
      momoBalanceData:
        type: object
        $ref: '#/definitions/MomoBalanceDetail'
      wallets:
        type: array
        description: The different wallets used to compute the active and unused values of this balance.
        items:
          $ref: '#/definitions/Wallet'
  BalanceDetail:
    type: object
    required:
      - type
      - activeValue
      - activeUnit
    description: The details for a balance type.
    properties:
      type:
        type: string
        description: This is the type of the value.
        enum:
          - CURRENCY
          - DATA
          - MINUTES
          - SMS
      activeValue:
        type: string
        description: This is the aggregated formatted active value of a balance type.
      activeUnit:
        type: string
        description: This is the unit of the aggregated active value.
        enum:
          - ZAR
          - NGN
          - GB
          - MB
          - MINUTES
          - SMS
      unusedValue:
        type: string
        description: This is the aggregated formatted unused value of a balance type.
        example: '45.25'
      unusedUnit:
        type: string
        description: This is the unit of the aggregated unused value.
        enum:
          - ZAR
          - NGN
          - GB
          - MB
          - MINUTES
          - SMS
        example: NGN
  Wallet:
    type: object
    required:
      - name
      - status
      - expiryDate
      - amount
    description: The details for a wallet account.
    properties:
      name:
        type: string
        description: The name of a wallet account.
      status:
        type: string
        description: The status of a wallet's value.
        enum:
          - Active
          - Unused
        example: Active
      expiryDate:
        type: string
        format: date-time
        description: Expiry date of the wallet's value.
      amount:
        $ref: '#/definitions/Amount'
  Amount:
    type: object
    required:
      - value
      - type
      - unit
    description: The amount details for a wallet.
    properties:
      type:
        type: string
        description: This is the type of the wallet value.
        enum:
          - CURRENCY
          - DATA
          - MINUTES
          - SMS
      value:
        type: string
        description: This is the value of a balance wallet.
      unit:
        type: string
        description: This is the unit of the wallet value.
        enum:
          - ZAR
          - NGN
          - GB
          - MB
          - MINUTES
          - SMS
          - FCFA
        example: NGN
  PremiumError:
    type: object
    properties:
      statusCode:
        type: string
        description: 'This will have MADAPI response mapping, based on the value received from the downstream system'
      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: '#/definitions/PremiumResponse__links'
  PremiumResponse__links_self:
    type: object
    properties:
      href:
        type: string
        description: Hyperlink to access the problem.
  PremiumResponse__links:
    type: object
    properties:
      self:
        $ref: '#/definitions/PremiumResponse__links_self'
    description: Relevant links to the problem.
  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'
      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
      timestamp:
        type: string
        format: date-time
        description: Timestamp that the error occurred
      path:
        type: string
        description: The path that caused the error
      method:
        type: string
        description: The HTTP method type that was used
        example: GET
  OfferDetails:
    type: object
    description: The Offer Details per customer.
    properties:
      offerId:
        type: string
        example: '123456'
        description: The Offer ID
      offerType:
        type: string
        example: '2'
        description: The type of offer
      startDate:
        type: string
        format: dateTime
        example: '20210205T16:08:08+0530'
        description: The start date of offer
      expiryDate:
        type: string
        format: dateTime
        example: '20210205T16:08:08+0530'
        description: Date at which offer will expire
      expiryDateValue:
        type: string
        example: '53402237800000'
        description: Value of the expiry date