MTN Group Activation API

openapi: 3.2.0
info:
  description: To register services and activate services content tokens
  version: v1.0
  title: Customer Billing Token Activation API
servers:
- url: https://api.mtn.com/v1/customer
security:
- ApiKeyAuth: []
- OAuth2: []
tags:
- name: Activation
paths:
  /bill/activateToken:
    post:
      tags:
      - Activation
      summary: Activate Token Service
      description: Billing Recurring Service Token Activation
      parameters:
      - name: targetSystem
        in: header
        required: false
        schema:
          type: string
          enum:
          - Pantheon
      - name: allowPoll
        in: header
        required: true
        schema:
          type: boolean
          enum:
          - true
          - false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateOrderResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadReq'
        '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'
        '452':
          description: Invalid API Version
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInvAPIVersion'
        '454':
          description: MSISDN Not Provided
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMsisdnNotProvided'
        '463':
          description: Subscription Channel Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSubChanNotFound'
        '464':
          description: Subscription Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSubNotFound'
        '466':
          description: Service Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSvcNotFound'
        '467':
          description: Active Subscription Exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorActSubsEx'
        '470':
          description: Service Not Linked To Billing Channel
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSvcNotLinked'
        '473':
          description: Service ID or Service Ref Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSvcIdSvcRefNotFound'
        '478':
          description: Invalid MSISDN
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInvMsisdn'
        '480':
          description: Invalid Billing Rate
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInvBillRate'
        '485':
          description: Pending Subscription Exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorPendingSubEx'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '515':
          description: Subscription Not Active
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSubNotActive'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ActivateTokenRequest'
        required: true
components:
  schemas:
    RelatedParty:
      type: object
      description: Related Entity reference. A related party defines party or party role linked to a specific entity.
      required:
      - '@referredType'
      - id
      properties:
        id:
          type: string
          description: Unique identifier of a related entity eg MSISDN.
          example: 9994746
        role:
          type: string
          description: Role played by the related party
          example: Customer
        '@referredType':
          type: string
          description: The actual type of the target instance when needed for disambiguation.
    Price:
      type: object
      description: Provides all amounts (tax included, duty free, tax rate), used currency and percentage to apply for Price Alteration.
      properties:
        taxIncludedAmount:
          $ref: '#/components/schemas/Money'
          description: All taxes included amount (expressed in the given currency)
    ErrorActSubsEx:
      type: object
      title: Error
      required:
      - status
      - message
      properties:
        statusCode:
          type: string
          description: Status code returned by provider system
          example: 1002
        statusMessage:
          type: string
          description: Status description
          example: 'DEP ::: Active Subscription Exists'
        supportMessage:
          type: string
          description: More error details and corrective measures
          example: Backend specific response
        path:
          type: string
          description: The path that caused the error
        timestamp:
          type: string
          format: date-time
          description: Time stamp of the error
        transactionId:
          type: string
          description: Transaction id returned by the provider system.
    ErrorInvBillRate:
      type: object
      title: Error
      required:
      - status
      - message
      properties:
        statusCode:
          type: string
          description: Status code returned by provider system
          example: 1006
        statusMessage:
          type: string
          description: Status description
          example: 'DEP ::: Invalid Billing Rate'
        supportMessage:
          type: string
          description: More error details and corrective measures
          example: Backend specific response
        path:
          type: string
          description: The path that caused the error
        timestamp:
          type: string
          format: date-time
          description: Time stamp of the error
        transactionId:
          type: string
          description: Transaction id returned by the provider system.
    ErrorSubNotActive:
      type: object
      title: Error
      required:
      - status
      - message
      properties:
        statusCode:
          type: string
          description: Status code returned by provider system
          example: 1003
        statusMessage:
          type: string
          description: Status description
          example: 'DEP ::: Subscription Not Active'
        supportMessage:
          type: string
          description: More error details and corrective measures
          example: Backend specific response
        path:
          type: string
          description: The path that caused the error
        timestamp:
          type: string
          format: date-time
          description: Time stamp of the error
        transactionId:
          type: string
          description: Transaction id returned by the provider system.
    CreateOrderResponse:
      required:
      - statusCode
      - statusMessage
      - data
      type: object
      properties:
        statusCode:
          type: string
          description: Result code. Example- '0000'
        statusMessage:
          type: string
          description: Result message. Example- 'Successfully processed'
        transactionId:
          type: string
          description: Transaction id returned by the provider system.
        data:
          type: object
          properties:
            billingToken:
              type: object
              properties:
                msn:
                  type: string
                  minLength: 16
                  maxLength: 64
                  description: This field represents the message sequence number assigned by the CGW this can be used to uniquely track submitted requests.
                  example: '5115314911298406'
                contentToken:
                  type: string
                  minLength: 16
                  maxLength: 96
                  description: Token generated to be used for identifying the service for activation, billing, cancellation and refund.
                  example: 81B27C92607C6D47274C2859CF51B954A4EE99DFCC7DD89066F6CD41D74A10CE23CCD7C8A32B73DEDC0F2470B703F058
                allowToActivate:
                  type: boolean
                  description: Information inidicating if activation of token will be allowed.
                  example: true
                proposalIndicator:
                  type: integer
                  description: This indicates what is proposed, 0 - Nothing, 1 - Spend Limit only, 2 - Digital Limit only, 3 - Both Digital and Spend Limit, 4 - Nothing with SUL equals to SPUL and Digital Limit equal to New Monthly Committed Value
                  enum:
                  - 0
                  - 1
                  - 2
                  - 3
                  - 4
                proposedDigitalLimit:
                  type: integer
                  minimum: 1
                  maximum: 999999
                  description: This the proposed digital limit in Rxx whole rands only.
                  example: 25000
                proposedSpendLimit:
                  type: integer
                  minimum: 1
                  maximum: 999999
                  description: This the proposed digital limit in Rxx whole rands only.
                  example: 25000
                proratedBill:
                  type: integer
                  minimum: 0
                  maximum: 999999
                  description: The prorated amount in cents. Note, this field won't be returned if the token is not a monthly token, which is specified via selectedDebitOrderDate
                  example: 90
                proratedBillDate:
                  type: string
                  minLength: 10
                  maxLength: 10
                  description: The date upon which the prorated billing will be performed, in the format 'yyyy-mm-dd'. Note, this field won't be returned if the token is not a monthly token, which is specified via selectedDebitOrderDate
                  example: '2023-02-22'
            subscription:
              $ref: '#/components/schemas/ProductOrder2'
    ProductRefOrValue2:
      type: object
      description: A product to be created defined by value or existing defined by reference. The polymorphic attributes @type, @schemaLocation & @referredType are related to the product entity and not the RelatedProductRefOrValue class itself
      properties:
        characteristic:
          type: array
          description: product characteristics such as amount, type, etc
          items:
            $ref: '#/components/schemas/productCharacteristic2'
    ErrorInvMsisdn:
      type: object
      title: Error
      required:
      - status
      - message
      properties:
        statusCode:
          type: string
          description: Status code returned by provider system
          example: 1008
        statusMessage:
          type: string
          description: Status description
          example: 'DEP ::: Invalid MSISDN'
        supportMessage:
          type: string
          description: More error details and corrective measures
          example: Backend specific response
        path:
          type: string
          description: The path that caused the error
        timestamp:
          type: string
          format: date-time
          description: Time stamp of the error
        transactionId:
          type: string
          description: Transaction id returned by the provider system.
    ErrorPendingSubEx:
      type: object
      title: Error
      required:
      - status
      - message
      properties:
        statusCode:
          type: string
          description: Status code returned by provider system
          example: 1005
        statusMessage:
          type: string
          description: Status description
          example: 'DEP ::: Pending Subscription Exists'
        supportMessage:
          type: string
          description: More error details and corrective measures
          example: Backend specific response
        path:
          type: string
          description: The path that caused the error
        timestamp:
          type: string
          format: date-time
          description: Time stamp of the error
        transactionId:
          type: string
          description: Transaction id returned by the provider system.
    ProductTerm:
      type: object
      description: Description of a productTerm linked to this product. This represent a commitment with a duration
      properties:
        description:
          type: string
          description: Description of the productTerm
        name:
          type: string
          description: Name of the productTerm
        '@type':
          type: string
          description: When sub-classing, this defines the sub-class entity name
    ErrorBadReq:
      type: object
      title: Error
      required:
      - status
      - message
      properties:
        statusCode:
          type: string
          description: Status code returned by provider system
          example: 5000
        statusMessage:
          type: string
          description: Status description
          example: Bad Request
        supportMessage:
          type: string
          description: More error details and corrective measures
          example: Backend specific response
        path:
          type: string
          description: The path that caused the error
        timestamp:
          type: string
          format: date-time
          description: Time stamp of the error
        transactionId:
          type: string
          description: Transaction id returned by the provider system.
    ErrorSubChanNotFound:
      type: object
      title: Error
      required:
      - status
      - message
      properties:
        statusCode:
          type: string
          description: Status code returned by provider system
          example: 1007
        statusMessage:
          type: string
          description: Status description
          example: 'DEP ::: Subscription Channel Not Found'
        supportMessage:
          type: string
          description: More error details and corrective measures
          example: Backend specific response
        path:
          type: string
          description: The path that caused the error
        timestamp:
          type: string
          format: date-time
          description: Time stamp of the error
        transactionId:
          type: string
          description: Transaction id returned by the provider system.
    RelatedChannel:
      type: object
      description: Related channel to another entity. May be online web, mobile app, social ,etc.
      required:
      - id
      properties:
        id:
          type: string
          description: Unique identifier of a related entity.
        role:
          type: string
          description: Role of channel
        href:
          type: string
          description: Reference of the related entity.
    ErrorMsisdnNotProvided:
      type: object
      title: Error
      required:
      - status
      - message
      properties:
        statusCode:
          type: string
          description: Status code returned by provider system
          example: 4003
        statusMessage:
          type: string
          description: Status description
          example: 'DEP ::: MSISDN Not Provided'
        supportMessage:
          type: string
          description: More error details and corrective measures
          example: Backend specific response
        path:
          type: string
          description: The path that caused the error
        timestamp:
          type: string
          format: date-time
          description: Time stamp of the error
        transactionId:
          type: string
          description: Transaction id returned by the provider system.
    ErrorSubNotFound:
      type: object
      title: Error
      required:
      - status
      - message
      properties:
        statusCode:
          type: string
          description: Status code returned by provider system
          example: 1000
        statusMessage:
          type: string
          description: Status description
          example: 'DEP ::: Subscription Not Found'
        supportMessage:
          type: string
          description: More error details and corrective measures
          example: Backend specific response
        path:
          type: string
          description: The path that caused the error
        timestamp:
          type: string
          format: date-time
          description: Time stamp of the error
        transactionId:
          type: string
          description: Transaction id returned by the provider system.
    ProductOrderItem:
      type: object
      description: An identified part of the order. A product order is decomposed into one or more order items.
      properties:
        product:
          $ref: '#/components/schemas/ProductRefOrValue'
        itemTotalPrice:
          $ref: '#/components/schemas/OrderPrice'
    Error:
      type: object
      title: Error
      required:
      - status
      - message
      properties:
        statusCode:
          type: string
          description: Status code returned by provider system
        statusMessage:
          type: string
          description: Status description
        supportMessage:
          type: string
          description: More error details and corrective measures
        path:
          type: string
          description: The path that caused the error
        timestamp:
          type: string
          format: date-time
          description: Time stamp of the error
        transactionId:
          type: string
          description: Transaction id returned by the provider system.
    ErrorInvAPIVersion:
      type: object
      title: Error
      required:
      - status
      - message
      properties:
        statusCode:
          type: string
          description: Status code returned by provider system
          example: 3001
        statusMessage:
          type: string
          description: Status description
          example: 'DEP ::: Invalid API Version'
        supportMessage:
          type: string
          description: More error details and corrective measures
          example: Backend specific response
        path:
          type: string
          description: The path that caused the error
        timestamp:
          type: string
          format: date-time
          description: Time stamp of the error
        transactionId:
          type: string
          description: Transaction id returned by the provider system.
    AgreementRef:
      type: object
      description: Agreement reference. An agreement represents a contract or arrangement, either written or verbal and sometimes enforceable by law, such as a service level agreement or a customer price agreement. An agreement involves a number of other business entities, such as products, services, and resources and/or their specifications.
      required:
      - id
      properties:
        id:
          type: string
          description: Unique identifier of a related entity.
    ErrorSvcIdSvcRefNotFound:
      type: object
      title: Error
      required:
      - status
      - message
      properties:
        statusCode:
          type: string
          description: Status code returned by provider system
          example: 3004
        statusMessage:
          type: string
          description: Status description
          example: 'DEP ::: Service ID or Service Ref Not Found'
        supportMessage:
          type: string
          description: More error details and corrective measures
          example: Backend specific response
        path:
          type: string
          description: The path that caused the error
        timestamp:
          type: string
          format: date-time
          description: Time stamp of the error
        transactionId:
          type: string
          description: Transaction id returned by the provider system.
    ProductOrder2:
      type: object
      description: A Product Order is a type of order which  can  be used to place an order between a customer and a service provider or between a service provider and a partner and vice versa,
      required:
      - productOrderItem
      properties:
        id:
          type: string
          description: ID created on repository side (OM system)
        description:
          type: string
          description: Description of the product order
        externalId:
          type: string
          description: ID given by the consumer and only understandable by him (to facilitate his searches afterwards)
        orderDate:
          type: string
          format: date-time
          description: Date when the order was created
        agreement:
          $ref: '#/components/schemas/AgreementRef'
        channel:
          type: array
          items:
            $ref: '#/components/schemas/RelatedChannel'
        productOrderItem:
          type: array
          items:
            $ref: '#/components/schemas/ProductOrderItem'
          minItems: 1
        relatedParty:
          type: array
          items:
            $ref: '#/components/schemas/RelatedParty'
    ErrorSvcNotLinked:
      type: object
      title: Error
      required:
      - status
      - message
      properties:
        statusCode:
          type: string
          description: Status code returned by provider system
          example: 5001
        statusMessage:
          type: string
          description: Status description
          example: 'DEP ::: Service Not Linked To Billing Channel'
        supportMessage:
          type: string
          description: More error details and corrective measures
          example: Backend specific response
        path:
          type: string
          description: The path that caused the error
        timestamp:
          type: string
          format: date-time
          description: Time stamp of the error
        transactionId:
          type: string
          description: Transaction id returned by the provider system.
    AgreementItemRef2:
      type: object
      description: Agreement reference. An agreement represents a contract or arrangement, either written or verbal and sometimes enforceable by law, such as a service level agreement or a customer price agreement. An agreement involves a number of other business entities, such as products, services, and resources and/or their specifications.
      properties:
        id:
          type: string
          description: Unique identifier of a related entity.
    ProductRefOrValue:
      type: object
      description: A product to be created defined by value or existing defined by reference. The polymorphic attributes @type, @schemaLocation & @referredType are related to the product entity and not the RelatedProductRefOrValue class itself
      properties:
        agreement:
          type: array
          items:
            $ref: '#/components/schemas/AgreementItemRef2'
        characteristic:
          type: array
          description: product characteristics such as amount, type, etc
          items:
            $ref: '#/components/schemas/productCharacteristic'
        productOffering:
          $ref: '#/components/schemas/ProductOfferingRef'
        productTerm:
          type: array
          description: Description of a productTerm linked to this product. This represent a commitment with a duration
          items:
            $ref: '#/components/schemas/ProductTerm'
        status:
          type: array
          description: status of product
          items:
            $ref: '#/components/schemas/ProductStatusType'
        orderDate:
          type: string
          description: Date when the order was created.
        startDate:
          type: string
          description: Is the date from which the product starts
        terminationDate:
          type: string
          description: Is the date when the product was terminated.
    productCharacteristic2:
      type: object
      properties:
        name:
          type: string
          example: hulaya data
    Money:
      type: object
      description: A base / value business entity used to represent money
      properties:
        unit:
          type: string
          description: Currency (ISO4217 norm uses 3 letters to define the currency)
        value:
          type: number
          format: float
          description: A positive floating point number
    productCharacteristic:
      type: object
      properties:
        name:
          type: string
          example: hulaya data
        value:
          type: number
          example: 6
    ProductOfferingRef:
      type: object
      description: ProductOffering reference. A product offering represents entities that are orderable from the provider of the catalog, this resource includes pricing information.
      properties:
        id:
          type: string
          description: Unique identifier of a related entity.
        name:
          type: string
          description: Name of unique identifier of related entity
    ErrorSvcNotFound:
      type: object
      title: Error
      required:
      - status
      - message
      properties:
        statusCode:
          type: string
          description: Status code returned by provider system
          example: 3000
        statusMessage:
          type: string
          description: Status description
          example: 'DEP ::: Service Not Found'
        supportMessage:
          type: string
          description: More error details and corrective measures
          example: Backend specific response
        path:
          type: string
          description: The path that caused the error
        timestamp:
          type: string
          format: date-time
          description: Time stamp of the error
        transactionId:
          type: string
          description: Transaction id returned by the provider system.
    ActivateTokenRequest:
      type: object
      properties:
        billingToken:
          required:
          - transactionId
          - contractingPartnerId
          - platformPartnerId
          - contentToken
          properties:
            transactionId:
              type: string
              minLength: 9
              maxLength: 36
              description: Unique transaction identifier. It is advised that the client system use the methods defined in [RFC4122](https://tools.ietf.org/html/rfc4122) to generate this value.
              example: '123456768'
            contractingPartnerId:
              type: string
              minLength: 9
              maxLength: 9
              description: Contracting Partner Identifier as supplied by MTN Digital Department.
              example: '911844857'
            platformPartnerId:
              type: string
              minLength: 9
              maxLength: 9
              description: Platform Partner Identifier.
              example: '911844857'
            contentToken:
              type: string
              minLength: 16
              maxLength: 96
              description: Token generated to be used for identifying the service for activation, billing, cancellation and refund.
              example: 81B27C92607C6D47274C2859CF51B954A4EE99DFCC7DD89066F6CD41D74A10CE23CCD7C8A32B73DEDC0F2470B703F058
            limitConsent:
              type: string
              description: Y - Indicates consent was given by the subscriber, either the digital limit, spend limit or both will be updated. N - no limit will be updated.
              enum:
              - Y
              - N
        subscription:
          type: object
          properties:
            id:
              type: string
            productOrderItem:
              type: array
              items:
                $ref: '#/components/schemas/ProductOrderItem2'
              minItems: 1
            channel:
              type: array
              items:
                $ref: '#/components/schemas/RelatedChannel'
    ProductOrderItem2:
      type: object
      description: An identified part of the order. A product order is decomposed into one or more order items.
      properties:
        product:
          $ref: '#/components/schemas/ProductRefOrValue2'
    ProductStatusType:
      type: string
      description: Possible values for the status of the product
      enum:
      - created
      - pendingActive
      - cancelled
      - active
      - pendingTerminate
      - terminated
      - suspended
      - 'aborted '
    OrderPrice:
      type: object
      description: An amount, usually of money, that represents the actual price paid by the Customer for this item or this order
      properties:
        priceType:
          type: string
          description: A category that describes the price, such as recurring, discount, allowance, penalty, and so forth
        recurringChargePeriod:
          type: string
          description: Could be month, week...
        price:
          $ref: '#/components/schemas/Price'
          description: a structure used to define price amount
  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