openapi: 3.0.3
info:
    title: Ponitor Airtime API
    version: 1.1.0
    description: |-
        Buy Airtime or a data bundle for a single Liberian mobile number and check how the
        purchase went.

        No added fees: a $1.00 top-up costs your Ponitor wallet $1.00, and a data bundle costs
        its listed price.
        Every purchase carries your own `externalId`; sending the same `externalId` again
        returns the original purchase instead of charging you twice.

        Bulk purchases to contact groups, wallet balance and purchase history are managed
        in the Ponitor web app, not through this API.
    contact:
        name: Ponitor
        url: https://www.ponitor.com
        email: info@ponitor.com
    license:
        name: MIT License
        url: https://opensource.org/licenses/MIT

servers:
    - url: https://api.ponitor.com/airtime/v1
      description: Live
    - url: https://sandbox-api.ponitor.com/airtime/v1
      description: Sandbox

tags:
    - name: airtime
      description: Buy Airtime or data and look up a purchase
    - name: products
      description: The data bundles on sale

paths:
    /products:
        get:
            summary: List data bundles
            description: |-
                The data bundles you can buy now, by carrier, cheapest first within each validity.
                Bundles come and go with the networks: list them before you sell. Each bundle has
                an `id` (`prod_…`), which never changes, and a readable `code`
                (`mtn-data-1-8gb-7d`). Buy with either one.
            operationId: listAirtimeProducts
            tags: [products]
            security:
                - apiKeyAuth: []
                - oauth2: []
            parameters:
                - name: carrier
                  in: query
                  required: false
                  schema:
                      $ref: '#/components/schemas/Carrier'
                - name: type
                  in: query
                  required: false
                  schema:
                      type: string
                      enum: [DATA]
            responses:
                '200':
                    description: The bundles on sale
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    products:
                                        type: array
                                        items:
                                            $ref: '#/components/schemas/Product'
                '400':
                    $ref: '#/components/responses/400BadRequest'
                '401':
                    $ref: '#/components/responses/401Unauthorized'
                '500':
                    $ref: '#/components/responses/500ServerError'

    /products/{idOrCode}:
        parameters:
            - name: idOrCode
              in: path
              required: true
              description: |-
                  The bundle's `id` (`prod_p4nzx9xp335h`) or its `code` (`mtn-data-15gb-30d`). The
                  two formats can't be confused: an id starts with `prod_`, and a code never has
                  an underscore.
              schema:
                  type: string
              examples:
                  id:
                      summary: By id
                      value: prod_p4nzx9xp335h
                  code:
                      summary: By code
                      value: mtn-data-15gb-30d
        get:
            summary: Get a data bundle
            description: |-
                One bundle on sale, by its id or its code. `404` for an unknown id or code, or a
                bundle that is no longer sold.
            operationId: getAirtimeProduct
            tags: [products]
            security:
                - apiKeyAuth: []
                - oauth2: []
            responses:
                '200':
                    description: The bundle
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Product'
                '400':
                    $ref: '#/components/responses/400BadRequest'
                '401':
                    $ref: '#/components/responses/401Unauthorized'
                '404':
                    $ref: '#/components/responses/404NotFound'
                '500':
                    $ref: '#/components/responses/500ServerError'

    /purchases:
        post:
            summary: Buy Airtime or a data bundle for one number
            description: |-
                Tops up one Orange or Lonestar Cell MTN number with Airtime (send `amount`) or a
                data bundle. Send `amount` or a bundle, never both.

                Name the bundle by its `productId` (the bundle's `id`, `prod_…`) or its
                `productCode` (the bundle's `code`). You may send both if they name the same
                bundle; if they name different bundles the request is refused with a `400` and
                nothing is charged. The `id` never changes, so prefer it for anything you store.

                For Airtime the subscriber receives `amount` and your wallet is charged `cost`.
                No added fees: `cost` is the same as `amount`. For a bundle your wallet is charged
                its price, and the purchase keeps the bundle as it was when you bought it
                (`product`).

                The response status tells you where the purchase stands:

                - `SUCCESS`: delivered.
                - `PENDING`: accepted by the network but not yet confirmed. Ponitor keeps
                  checking for up to an hour; poll `GET /purchases/{id}` to see it settle. The cost
                  stays held until it does.
                - `FAILED`: the network declined it. The cost goes back to your wallet;
                  `failureReason` says why.

                Replaying a request with an `externalId` you have already used returns the
                original purchase with `200` instead of creating a new one.

                To make sure a bundle costs what you showed your customer, send that price as
                `expectedPrice`. If the bundle's price is different now, the request is refused
                with a `409` and code `PRICE_CHANGED`. Nothing is charged and nothing is sent to the
                network; list the bundles again and retry with the new price.

                With an API key you act as your team. Signed in to the Ponitor web app, any
                member of the team can buy for one number at a time; bulk purchases need an
                owner or manager.
            operationId: createAirtimePurchase
            tags: [airtime]
            security:
                - apiKeyAuth: []
                - oauth2: []
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/AirtimePurchaseRequest'
                        examples:
                            orange:
                                summary: Top up an Orange number
                                value:
                                    msisdn: '231770000000'
                                    amount: 5
                                    externalId: order-8842
                            dataById:
                                summary: Buy a data bundle by its id
                                value:
                                    msisdn: '231880000000'
                                    productId: prod_p4nzx9xp335h
                                    externalId: order-8843
                            dataByCode:
                                summary: Buy a data bundle by its code
                                value:
                                    msisdn: '231880000000'
                                    productCode: mtn-data-15gb-30d
                                    externalId: order-8844
                            dataByBoth:
                                summary: Both, naming the same bundle
                                value:
                                    msisdn: '231880000000'
                                    productId: prod_p4nzx9xp335h
                                    productCode: mtn-data-15gb-30d
                                    externalId: order-8845
                            dataAtPrice:
                                summary: A data bundle, only at the price you showed
                                value:
                                    msisdn: '231880000000'
                                    productId: prod_p4nzx9xp335h
                                    expectedPrice: 9
                                    externalId: order-8846
            responses:
                '201':
                    description: Purchase created
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/AirtimePurchase'
                '200':
                    description: An `externalId` you had already used; this is the original purchase
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/AirtimePurchase'
                '400':
                    description: |-
                        Invalid input; `amount` together with a bundle, or neither; a `productId` and
                        `productCode` that name different bundles (`"productId prod_p4nzx9xp335h and
                        productCode mtn-data-500mb-3d are different products; send one, or both for the
                        same product"`); an unsupported network; an amount under $1.00; an amount or
                        bundle price over your team's limit per recipient (`"$80.00 exceeds your team's
                        $50.00 per-recipient limit"`); a bundle that is unknown or no longer sold; a
                        bundle for the other network
                        (`"Product mtn-data-15gb-30d is for Lonestar Cell MTN numbers"`), or not enough wallet balance
                        (`"Insufficient wallet balance. Top up under Billing to continue."`).
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                '401':
                    $ref: '#/components/responses/401Unauthorized'
                '403':
                    description: |-
                        Your team has not been verified yet, or you are signed in to a team you
                        don't belong to.
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                '409':
                    description: |-
                        Nothing was charged. Either the bundle's price isn't your `expectedPrice`
                        (code `PRICE_CHANGED`: `"Product prod_p4nzx9xp335h now costs $9.50, not
                        $9.00. Nothing was charged. Check the price and try again."`), or a request
                        with the same `externalId` is still being processed (retry it in a moment).
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                '500':
                    $ref: '#/components/responses/500ServerError'

    /purchases/{id}:
        parameters:
            - $ref: '#/components/parameters/idParam'
        get:
            summary: Get a purchase
            description: Returns the current state of a purchase. Poll this for a `PENDING` purchase until it becomes `SUCCESS` or `FAILED`.
            operationId: getAirtimePurchase
            tags: [airtime]
            security:
                - apiKeyAuth: []
                - oauth2: []
            responses:
                '200':
                    description: The purchase
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/AirtimePurchase'
                '400':
                    $ref: '#/components/responses/400BadRequest'
                '401':
                    $ref: '#/components/responses/401Unauthorized'
                '404':
                    $ref: '#/components/responses/404NotFound'
                '500':
                    $ref: '#/components/responses/500ServerError'

components:
    parameters:
        idParam:
            name: id
            in: path
            required: true
            description: Purchase ID returned when the purchase was created
            schema:
                type: string
                format: uuid

    schemas:
        Msisdn:
            type: string
            description: |-
                Liberian mobile number, either international (`231` + 9 digits) or local
                (`0` + 9 digits). Orange numbers start with `2317`; Lonestar Cell MTN with `23188` or `23155`.
            pattern: '^(231[0-9]{9}|0[0-9]{9})$'
            example: '231770000000'

        Carrier:
            type: string
            enum: [ORANGE, LONESTAR]
            example: ORANGE

        PurchaseStatus:
            type: string
            enum: [SUCCESS, PENDING, FAILED]
            example: SUCCESS

        ProductId:
            type: string
            description: |-
                Ponitor's id for a bundle: `prod_` and 12 characters. It never changes, even if the
                bundle's name or code does.
            pattern: '^prod_[0-9a-hjkmnp-tv-z]{12}$'
            example: prod_p4nzx9xp335h

        ProductCode:
            type: string
            description: A bundle's readable code, starting with its network. Never contains `_`.
            maxLength: 64
            pattern: '^[a-z][a-z0-9]*(-[a-z0-9]+)*$'
            example: mtn-data-15gb-30d

        ProductData:
            type: string
            nullable: true
            description: The bundle's data, in MB, GB or TB (1 GB = 1024 MB).
            example: 15GB

        ProductValidity:
            type: string
            nullable: true
            description: How long the bundle lasts.
            example: 30 days

        Product:
            type: object
            properties:
                id:
                    $ref: '#/components/schemas/ProductId'
                code:
                    $ref: '#/components/schemas/ProductCode'
                type:
                    type: string
                    enum: [DATA]
                carrier:
                    $ref: '#/components/schemas/Carrier'
                name:
                    type: string
                    example: Lonestar Cell MTN 15GB, 30 days
                data:
                    $ref: '#/components/schemas/ProductData'
                validity:
                    $ref: '#/components/schemas/ProductValidity'
                price:
                    type: number
                    format: double
                    description: What your wallet is charged, USD.
                    example: 9
                currency:
                    type: string
                    example: USD

        PurchaseProduct:
            type: object
            nullable: true
            description: The bundle bought, as it was at purchase time. Null for Airtime.
            properties:
                id:
                    $ref: '#/components/schemas/ProductId'
                code:
                    $ref: '#/components/schemas/ProductCode'
                name:
                    type: string
                    example: Lonestar Cell MTN 15GB, 30 days
                data:
                    $ref: '#/components/schemas/ProductData'
                validity:
                    $ref: '#/components/schemas/ProductValidity'
                price:
                    type: number
                    format: double
                    example: 9
                currency:
                    type: string
                    example: USD

        AirtimePurchaseRequest:
            type: object
            required: [msisdn, externalId]
            description: |-
                Send `amount` (Airtime) or a data bundle (`productId`, `productCode`, or both naming
                the same bundle), not both.
            properties:
                msisdn:
                    $ref: '#/components/schemas/Msisdn'
                amount:
                    type: number
                    format: double
                    minimum: 1
                    description: |-
                        The Airtime the subscriber receives, in USD, with at most 2 decimal places.
                        No added fees, so this is also what you pay.
                        At least 1.00 and at most your team's limit per recipient ($50 unless
                        an owner or manager has changed it); anything outside that is refused with a
                        400 before any money moves. Leave out when you buy a bundle.
                    example: 5
                productId:
                    allOf:
                        - $ref: '#/components/schemas/ProductId'
                    description: |-
                        A data bundle's `id` from `GET /products`. Must be for the number's network and
                        priced within your team's limit per recipient. Leave out when you send `amount`.
                productCode:
                    allOf:
                        - $ref: '#/components/schemas/ProductCode'
                    description: |-
                        A data bundle's `code` from `GET /products`, instead of or with `productId`.
                        With both, they must name the same bundle. Leave out when you send `amount`.
                expectedPrice:
                    type: number
                    format: double
                    minimum: 0.01
                    description: |-
                        Optional, for a bundle only. The price you expect to pay, in USD, as listed
                        by `GET /products`. If the bundle costs anything else now, the purchase is
                        refused with a `409` (`PRICE_CHANGED`) and nothing is charged.
                    example: 9
                externalId:
                    type: string
                    minLength: 1
                    maxLength: 30
                    pattern: '^[A-Za-z0-9_.-]+$'
                    description: |-
                        Your own reference for this purchase (order number, job id…). Unique per
                        team. Reusing one returns the original purchase, so you can retry
                        safely after a timeout.
                    example: order-8842

        AirtimePurchase:
            type: object
            properties:
                id:
                    type: string
                    format: uuid
                    example: 9b178243-9189-45df-8681-5de76ab1e6fe
                externalId:
                    type: string
                    nullable: true
                    example: order-8842
                type:
                    type: string
                    enum: [AIRTIME, DATA]
                    example: AIRTIME
                msisdn:
                    type: string
                    description: Normalised to international format.
                    example: '231770000000'
                carrier:
                    $ref: '#/components/schemas/Carrier'
                product:
                    $ref: '#/components/schemas/PurchaseProduct'
                amount:
                    type: number
                    format: double
                    description: Airtime delivered, USD (a bundle's price for data).
                    example: 5
                cost:
                    type: number
                    format: double
                    description: |-
                        What your wallet was charged, USD. No added fees: for Airtime it's the
                        amount, and for data the bundle's price. Refunded if the purchase fails.
                    example: 5
                status:
                    $ref: '#/components/schemas/PurchaseStatus'
                failureReason:
                    type: string
                    nullable: true
                    description: |-
                        Why a FAILED purchase failed. A problem with the number carries the network's
                        wording (e.g. "Destination is barred"); a network or provider problem is
                        reported neutrally as "Network temporarily unavailable — refunded" or
                        "Service temporarily unavailable — refunded".
                    example: null
                instructions:
                    type: string
                    nullable: true
                    description: Text the network asks to be passed on to the subscriber, when it sends any.
                    example: null
                createdAt:
                    type: string
                    format: date-time
                    example: '2026-09-21T19:44:03.000Z'

        ErrorResponse:
            type: object
            properties:
                message:
                    type: string
                    example: Insufficient wallet balance. Top up under Billing to continue.
                code:
                    type: string
                    description: A stable code for errors you may want to handle, such as `PRICE_CHANGED`.
                    example: PRICE_CHANGED
                errors:
                    type: array
                    description: Present on validation failures
                    items:
                        type: object
                        properties:
                            message:
                                type: string
                                example: msisdn must be 12 digits starting with 231 or 10 digits starting with 0

    securitySchemes:
        oauth2:
            type: oauth2
            description: |-
                A bearer token from your team's OAuth client, with the client credentials grant.
                POST your client ID and secret (HTTP Basic) with `grant_type=client_credentials` to
                `/oauth2/token` on the same host you call: `https://sandbox-api.ponitor.com` for a
                sandbox client, `https://api.ponitor.com` for a live one. Send the token as
                `Authorization: Bearer <token>` until it expires (`expires_in`, in seconds), then
                get another.
            flows:
                clientCredentials:
                    tokenUrl: https://api.ponitor.com/oauth2/token
                    scopes: {}
        apiKeyAuth:
            type: apiKey
            in: header
            name: apiKey

    responses:
        400BadRequest:
            description: Bad request
            content:
                application/json:
                    schema:
                        $ref: '#/components/schemas/ErrorResponse'
        401Unauthorized:
            description: Missing or invalid authentication credentials
            content:
                application/json:
                    schema:
                        $ref: '#/components/schemas/ErrorResponse'
        404NotFound:
            description: Resource not found
            content:
                application/json:
                    schema:
                        $ref: '#/components/schemas/ErrorResponse'
        500ServerError:
            description: Internal server error
            content:
                application/json:
                    schema:
                        $ref: '#/components/schemas/ErrorResponse'

security:
    - apiKeyAuth: []
    - oauth2: []
