openapi: 3.1.0
info:
  title: Reloadly Airtime Authentication Orders 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: Orders
  description: Place and manage gift card orders.
paths:
  /orders:
    post:
      operationId: placeOrder
      summary: Place Order
      description: Place a gift card order for a specific product and denomination. Successful orders return an order object with the gift card code, PIN, and redemption instructions. Orders are fulfilled in real-time.
      tags:
      - Orders
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderRequest'
      responses:
        '200':
          description: Order placed and gift card delivered
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /orders/{orderId}:
    get:
      operationId: getOrder
      summary: Get Order
      description: Retrieve the details of a specific gift card order including the gift card code, PIN, redemption instructions, and order status.
      tags:
      - Orders
      parameters:
      - name: orderId
        in: path
        required: true
        description: Unique identifier of the order
        schema:
          type: integer
      responses:
        '200':
          description: Order details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
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
    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'
    Order:
      type: object
      properties:
        transactionId:
          type: integer
          description: Unique transaction identifier
        amount:
          type: number
          format: double
          description: Amount charged for the order
        discount:
          type: number
          format: double
          description: Discount amount applied
        currencyCode:
          type: string
          description: Currency code for the transaction
        fee:
          type: number
          format: double
          description: Processing fee
        recipientEmail:
          type: string
          format: email
          description: Recipient email address
        customIdentifier:
          type: string
          description: Custom identifier provided at order time
        status:
          type: string
          description: Order status
        product:
          $ref: '#/components/schemas/Product'
        smiles:
          type: array
          items:
            $ref: '#/components/schemas/GiftCard'
          description: Array of gift card codes delivered
        date:
          type: string
          format: date-time
          description: Order timestamp
    Brand:
      type: object
      properties:
        brandId:
          type: integer
          description: Unique brand identifier
        brandName:
          type: string
          description: Brand display name (e.g., Amazon, Apple, Netflix)
    OrderRequest:
      type: object
      required:
      - productId
      - quantity
      - unitPrice
      - senderName
      - recipientEmail
      properties:
        productId:
          type: integer
          description: ID of the gift card product to order
        quantity:
          type: integer
          description: Number of gift cards to order
          minimum: 1
          maximum: 100
        unitPrice:
          type: number
          format: double
          description: Price per gift card in sender currency
        customIdentifier:
          type: string
          description: Custom reference identifier for the order
        senderName:
          type: string
          description: Name of the sender
        recipientEmail:
          type: string
          format: email
          description: Email address of the recipient
        preOrder:
          type: boolean
          description: Whether to place a pre-order
    Error:
      type: object
      properties:
        timeStamp:
          type: string
          format: date-time
        message:
          type: string
        path:
          type: string
        errorCode:
          type: string
        infoLink:
          type: string
    GiftCard:
      type: object
      properties:
        code:
          type: string
          description: Gift card redemption code
        pinCode:
          type: string
          description: PIN code if required for redemption
        validity:
          type: string
          description: Expiration date or validity information
  responses:
    Unauthorized:
      description: Missing or invalid authentication token
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Requested resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  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