openapi: 3.1.0
info:
  title: Reloadly Airtime Authentication Transactions API
  description: The Reloadly Airtime API enables businesses to programmatically deliver mobile airtime top-ups and data bundles to phones across 170+ countries and 800+ mobile operators. The API supports both operator-specific and auto-detect top-ups, with real-time fulfillment and detailed transaction reporting. Authentication uses OAuth 2.0 client credentials with separate sandbox and production environments.
  version: 1.0.0
  contact:
    name: Reloadly Support
    url: https://support.reloadly.com
  termsOfService: https://www.reloadly.com/terms
servers:
- url: https://topups.reloadly.com
  description: Production Server
- url: https://topups-sandbox.reloadly.com
  description: Sandbox Server
security:
- bearerAuth: []
tags:
- name: Transactions
  description: List and retrieve top-up transaction history.
paths:
  /topups/transactions:
    get:
      operationId: listTopUpTransactions
      summary: List Top-Up Transactions
      description: Retrieve a paginated list of all airtime top-up transactions. Supports filtering by date range, phone number, and status.
      tags:
      - Transactions
      parameters:
      - $ref: '#/components/parameters/PageParam'
      - $ref: '#/components/parameters/SizeParam'
      - name: startDate
        in: query
        description: Filter from this date (YYYY-MM-DD)
        schema:
          type: string
          format: date
      - name: endDate
        in: query
        description: Filter to this date (YYYY-MM-DD)
        schema:
          type: string
          format: date
      responses:
        '200':
          description: Paginated list of top-up transactions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionsPage'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /topups/transactions/{transactionId}:
    get:
      operationId: getTopUpTransaction
      summary: Get Top-Up Transaction
      description: Retrieve details for a specific airtime top-up transaction.
      tags:
      - Transactions
      parameters:
      - name: transactionId
        in: path
        required: true
        description: Unique transaction identifier
        schema:
          type: integer
      responses:
        '200':
          description: Transaction details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TopUpTransaction'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /transactions:
    get:
      operationId: listTransactions
      summary: List Transactions
      description: Retrieve a paginated list of all transactions on the account including gift card orders, balance top-ups, and refunds. Supports filtering by date range and transaction type.
      tags:
      - Transactions
      parameters:
      - $ref: '#/components/parameters/PageParam'
      - $ref: '#/components/parameters/SizeParam'
      - name: startDate
        in: query
        description: Filter transactions from this date (YYYY-MM-DD)
        schema:
          type: string
          format: date
      - name: endDate
        in: query
        description: Filter transactions to this date (YYYY-MM-DD)
        schema:
          type: string
          format: date
      responses:
        '200':
          description: Paginated list of transactions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionsPage_2'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    RedeemInstruction:
      type: object
      properties:
        concise:
          type: string
          description: Brief redemption instructions
        verbose:
          type: string
          description: Detailed redemption instructions
    Country:
      type: object
      properties:
        isoName:
          type: string
          description: ISO 3166-1 alpha-2 country code
        name:
          type: string
          description: Country display name
        flagUrl:
          type: string
          format: uri
          description: URL to the country flag image
    Transaction:
      type: object
      properties:
        transactionId:
          type: integer
          description: Unique transaction identifier
        amount:
          type: number
          format: double
          description: Transaction amount
        discount:
          type: number
          format: double
          description: Discount applied
        currencyCode:
          type: string
          description: Currency code
        fee:
          type: number
          format: double
          description: Processing fee
        status:
          type: string
          description: Transaction status
        product:
          $ref: '#/components/schemas/Product'
        date:
          type: string
          format: date-time
          description: Transaction timestamp
    Brand:
      type: object
      properties:
        brandId:
          type: integer
          description: Unique brand identifier
        brandName:
          type: string
          description: Brand display name (e.g., Amazon, Apple, Netflix)
    TopUpTransaction:
      type: object
      properties:
        transactionId:
          type: integer
        status:
          type: string
          enum:
          - SUCCESSFUL
          - REFUNDED
          - FAILED
        operatorTransactionId:
          type: string
          description: Transaction ID from the mobile operator
        customIdentifier:
          type: string
        recipientPhone:
          type: string
        recipientEmail:
          type: string
        senderPhone:
          type: string
        countryCode:
          type: string
        operatorId:
          type: integer
        operatorName:
          type: string
        discount:
          type: number
        discountCurrencyCode:
          type: string
        requestedAmount:
          type: number
        requestedAmountCurrencyCode:
          type: string
        deliveredAmount:
          type: number
        deliveredAmountCurrencyCode:
          type: string
        transactionDate:
          type: string
          format: date-time
    TransactionsPage:
      type: object
      properties:
        content:
          type: array
          items:
            $ref: '#/components/schemas/TopUpTransaction'
        totalElements:
          type: integer
        totalPages:
          type: integer
        last:
          type: boolean
        number:
          type: integer
        size:
          type: integer
    TransactionsPage_2:
      type: object
      properties:
        content:
          type: array
          items:
            $ref: '#/components/schemas/Transaction'
        totalElements:
          type: integer
        totalPages:
          type: integer
        last:
          type: boolean
        number:
          type: integer
        size:
          type: integer
    Error:
      type: object
      properties:
        timeStamp:
          type: string
          format: date-time
        message:
          type: string
        path:
          type: string
        errorCode:
          type: string
    Product:
      type: object
      properties:
        productId:
          type: integer
          description: Unique product identifier
        productName:
          type: string
          description: Display name of the gift card product
        global:
          type: boolean
          description: Whether the product is redeemable globally
        supportsPreOrder:
          type: boolean
          description: Whether pre-ordering is supported
        senderFee:
          type: number
          format: double
          description: Fee charged to the sender
        discountPercentage:
          type: number
          format: double
          description: Discount percentage applied to the face value
        denominationType:
          type: string
          enum:
          - FIXED
          - RANGE
          description: Whether the product has fixed or range denominations
        recipientCurrencyCode:
          type: string
          description: Currency code for the recipient
        minRecipientDenomination:
          type: number
          description: Minimum denomination for range products
        maxRecipientDenomination:
          type: number
          description: Maximum denomination for range products
        senderCurrencyCode:
          type: string
          description: Currency code for the sender
        minSenderDenomination:
          type: number
          description: Minimum sender denomination for range products
        maxSenderDenomination:
          type: number
          description: Maximum sender denomination for range products
        fixedRecipientDenominations:
          type: array
          items:
            type: number
          description: Available fixed denomination amounts for the recipient
        fixedSenderDenominations:
          type: array
          items:
            type: number
          description: Available fixed denomination amounts for the sender
        brand:
          $ref: '#/components/schemas/Brand'
        country:
          $ref: '#/components/schemas/Country'
        redeemInstruction:
          $ref: '#/components/schemas/RedeemInstruction'
  responses:
    Unauthorized:
      description: Missing or invalid authentication token
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Requested resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    PageParam:
      name: page
      in: query
      description: Page number (1-based)
      schema:
        type: integer
        minimum: 1
        default: 1
    SizeParam:
      name: size
      in: query
      description: Number of results per page
      schema:
        type: integer
        minimum: 1
        maximum: 200
        default: 25
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: OAuth 2.0 bearer token obtained via the /oauth/token endpoint using client credentials grant.
externalDocs:
  description: Reloadly Airtime API Reference
  url: https://docs.reloadly.com/airtime