openapi: 3.0.3
info:
  title: Zendit API
  description: >-
    The Zendit API provides programmatic access to a global prepaid ecosystem,
    enabling mobile credit top-ups, data packages, digital gift cards, prepaid
    utility bill payments, and eSIM products through a unified integration.
  version: '1.0.0'
  x-generated-from: documentation
  x-source-url: https://developers.zendit.io/api/
  contact:
    name: Zendit
    url: https://zendit.io
servers:
  - url: https://api.zendit.io/v1
    description: Zendit Production
tags:
  - name: Account
    description: Wallet balance and account information
  - name: Brands
    description: Brand catalog
  - name: Mobile Top-Up
    description: Mobile credit top-ups, bundles, and data plans
  - name: eSIM
    description: eSIM plans and activation
  - name: Vouchers
    description: Digital gift cards and utility bill payments
  - name: Transactions
    description: Cross-product transaction queries
  - name: Tools
    description: Utility endpoints
  - name: Reports
    description: Transaction reporting
paths:
  /balance:
    get:
      operationId: getBalance
      summary: Zendit Get Balance
      description: Retrieve wallet balance and currency information.
      tags: [Account]
      responses:
        '200':
          description: Wallet balance
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Balance'
              examples:
                GetBalance200Example:
                  summary: Default getBalance 200 response
                  x-microcks-default: true
                  value:
                    amount: 1234.56
                    currency: USD
                    accountId: acc-12345
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                GetBalance401Example:
                  summary: Default getBalance 401 response
                  x-microcks-default: true
                  value:
                    code: INVALID_REQUEST
                    description: The request is missing required parameter offerId.
                    message: offerId is required.
      security:
        - BearerAuth: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /brands:
    get:
      operationId: listBrands
      summary: Zendit List Brands
      description: List available brands with pagination and optional country filtering.
      tags: [Brands]
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
        - $ref: '#/components/parameters/Country'
      responses:
        '200':
          description: List of brands
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrandList'
              examples:
                ListBrands200Example:
                  summary: Default listBrands 200 response
                  x-microcks-default: true
                  value:
                    list: &id005
                      - {}
                    offset: 0
                    limit: 100
                    total: 250
      security:
        - BearerAuth: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /brands/{brand}:
    get:
      operationId: getBrand
      summary: Zendit Get Brand
      description: Get brand details, logos, and metadata.
      tags: [Brands]
      parameters:
        - name: brand
          in: path
          required: true
          schema:
            type: string
          example: rebel-prepaid
      responses:
        '200':
          description: Brand detail
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Brand'
              examples:
                GetBrand200Example:
                  summary: Default getBrand 200 response
                  x-microcks-default: true
                  value:
                    id: rebel-prepaid
                    name: Rebel Prepaid
                    country: US
                    logoUrl: https://cdn.zendit.io/logos/rebel.png
                    types: &id004 [Mobile Top Up, Bundle]
      security:
        - BearerAuth: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /brands/{brand}/redemptionInstructions:
    get:
      operationId: getBrandRedemptionInstructions
      summary: Zendit Get Brand Redemption Instructions
      description: Fetch redemption terms and conditions by delivery type.
      tags: [Brands]
      parameters:
        - name: brand
          in: path
          required: true
          schema:
            type: string
          example: example-value
      responses:
        '200':
          description: Redemption instructions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RedemptionInstructions'
              examples:
                GetBrandRedemptionInstructions200Example:
                  summary: Default getBrandRedemptionInstructions 200 response
                  x-microcks-default: true
                  value:
                    deliveryType: SMS
                    instructions: Dial *123# from your phone to redeem.
                    termsAndConditions: Valid for 30 days from purchase.
      security:
        - BearerAuth: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /topups/offers:
    get:
      operationId: listTopupOffers
      summary: Zendit List Topup Offers
      description: List top-up, bundle, and data offers with filters.
      tags: [Mobile Top-Up]
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
        - $ref: '#/components/parameters/Country'
        - name: brand
          in: query
          schema:
            type: string
          example: example-value
        - name: subType
          in: query
          schema:
            type: string
            enum: [Mobile Top Up, Bundle, Data]
          example: Mobile Top Up
      responses:
        '200':
          description: List of offers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OfferList'
              examples:
                ListTopupOffers200Example:
                  summary: Default listTopupOffers 200 response
                  x-microcks-default: true
                  value:
                    list: &id002
                      - {}
                    offset: 0
                    limit: 100
                    total: 1500
      security:
        - BearerAuth: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /topups/offers/{offerId}:
    get:
      operationId: getTopupOffer
      summary: Zendit Get Topup Offer
      description: Retrieve specific top-up offer details.
      tags: [Mobile Top-Up]
      parameters:
        - $ref: '#/components/parameters/OfferId'
      responses:
        '200':
          description: Offer detail
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Offer'
              examples:
                GetTopupOffer200Example:
                  summary: Default getTopupOffer 200 response
                  x-microcks-default: true
                  value:
                    offerId: offer-12345
                    name: Rebel Prepaid 10 USD
                    brand: rebel-prepaid
                    country: US
                    type: TOPUP
                    subType: Mobile Top Up
                    price:
                      amount: {}
                      currency: {}
                    send:
                      amount: {}
                      currency: {}
                    receive:
                      amount: {}
                      currency: {}
      security:
        - BearerAuth: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /topups/purchases:
    get:
      operationId: listTopupPurchases
      summary: Zendit List Topup Purchases
      description: Query top-up transactions with date and status filters.
      tags: [Mobile Top-Up]
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
        - $ref: '#/components/parameters/Status'
      responses:
        '200':
          description: List of purchases
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PurchaseList'
              examples:
                ListTopupPurchases200Example:
                  summary: Default listTopupPurchases 200 response
                  x-microcks-default: true
                  value:
                    list: &id003
                      - {}
                    offset: 0
                    limit: 100
                    total: 50
      security:
        - BearerAuth: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createTopupPurchase
      summary: Zendit Create Topup Purchase
      description: Create new top-up transaction.
      tags: [Mobile Top-Up]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TopupPurchaseRequest'
            examples:
              CreateTopupPurchaseRequestExample:
                summary: Default createTopupPurchase request
                x-microcks-default: true
                value:
                  transactionId: my-txn-abc123
                  offerId: offer-12345
                  subscriberNumber: '+15555550100'
                  sendValue:
                    amount: {}
                    currency: {}
      responses:
        '201':
          description: Purchase created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Purchase'
              examples:
                CreateTopupPurchase201Example:
                  summary: Default createTopupPurchase 201 response
                  x-microcks-default: true
                  value:
                    transactionId: txn-abc123
                    offerId: offer-12345
                    status: DONE
                    type: TOPUP
                    createdAt: '2026-05-01T12:00:00Z'
                    send:
                      amount: {}
                      currency: {}
                    receive:
                      amount: {}
                      currency: {}
                    details: &id001 {}
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                CreateTopupPurchase400Example:
                  summary: Default createTopupPurchase 400 response
                  x-microcks-default: true
                  value:
                    code: INVALID_REQUEST
                    description: The request is missing required parameter offerId.
                    message: offerId is required.
      security:
        - BearerAuth: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /topups/purchases/{transactionId}:
    get:
      operationId: getTopupPurchase
      summary: Zendit Get Topup Purchase
      description: Fetch top-up transaction status.
      tags: [Mobile Top-Up]
      parameters:
        - $ref: '#/components/parameters/TransactionId'
      responses:
        '200':
          description: Purchase detail
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Purchase'
              examples:
                GetTopupPurchase200Example:
                  summary: Default getTopupPurchase 200 response
                  x-microcks-default: true
                  value:
                    transactionId: txn-abc123
                    offerId: offer-12345
                    status: DONE
                    type: TOPUP
                    createdAt: '2026-05-01T12:00:00Z'
                    send:
                      amount: {}
                      currency: {}
                    receive:
                      amount: {}
                      currency: {}
                    details: *id001
      security:
        - BearerAuth: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /esim/offers:
    get:
      operationId: listEsimOffers
      summary: Zendit List ESIM Offers
      description: Browse eSIM plans by region or country.
      tags: [eSIM]
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
        - $ref: '#/components/parameters/Country'
        - name: regions
          in: query
          schema:
            type: string
            enum: [Global, Africa, Asia, Caribbean, Europe, Americas]
          example: Global
      responses:
        '200':
          description: List of eSIM offers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OfferList'
              examples:
                ListEsimOffers200Example:
                  summary: Default listEsimOffers 200 response
                  x-microcks-default: true
                  value:
                    list: *id002
                    offset: 0
                    limit: 100
                    total: 1500
      security:
        - BearerAuth: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /esim/offers/{offerId}:
    get:
      operationId: getEsimOffer
      summary: Zendit Get ESIM Offer
      description: Get eSIM plan specifications.
      tags: [eSIM]
      parameters:
        - $ref: '#/components/parameters/OfferId'
      responses:
        '200':
          description: eSIM offer detail
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Offer'
              examples:
                GetEsimOffer200Example:
                  summary: Default getEsimOffer 200 response
                  x-microcks-default: true
                  value:
                    offerId: offer-12345
                    name: Rebel Prepaid 10 USD
                    brand: rebel-prepaid
                    country: US
                    type: TOPUP
                    subType: Mobile Top Up
                    price:
                      amount: {}
                      currency: {}
                    send:
                      amount: {}
                      currency: {}
                    receive:
                      amount: {}
                      currency: {}
      security:
        - BearerAuth: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /esim/purchases:
    get:
      operationId: listEsimPurchases
      summary: Zendit List ESIM Purchases
      description: List eSIM transactions.
      tags: [eSIM]
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
        - $ref: '#/components/parameters/Status'
      responses:
        '200':
          description: List of eSIM purchases
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PurchaseList'
              examples:
                ListEsimPurchases200Example:
                  summary: Default listEsimPurchases 200 response
                  x-microcks-default: true
                  value:
                    list: *id003
                    offset: 0
                    limit: 100
                    total: 50
      security:
        - BearerAuth: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createEsimPurchase
      summary: Zendit Create ESIM Purchase
      description: Purchase new eSIM or add plan to existing eSIM.
      tags: [eSIM]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EsimPurchaseRequest'
            examples:
              CreateEsimPurchaseRequestExample:
                summary: Default createEsimPurchase request
                x-microcks-default: true
                value:
                  transactionId: my-txn-abc123
                  offerId: esim-offer-001
                  iccId: '8901260000000000001'
      responses:
        '201':
          description: Purchase created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Purchase'
              examples:
                CreateEsimPurchase201Example:
                  summary: Default createEsimPurchase 201 response
                  x-microcks-default: true
                  value:
                    transactionId: txn-abc123
                    offerId: offer-12345
                    status: DONE
                    type: TOPUP
                    createdAt: '2026-05-01T12:00:00Z'
                    send:
                      amount: {}
                      currency: {}
                    receive:
                      amount: {}
                      currency: {}
                    details: *id001
      security:
        - BearerAuth: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /esim/purchases/{transactionId}:
    get:
      operationId: getEsimPurchase
      summary: Zendit Get ESIM Purchase
      description: Check eSIM transaction status.
      tags: [eSIM]
      parameters:
        - $ref: '#/components/parameters/TransactionId'
      responses:
        '200':
          description: eSIM purchase
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Purchase'
              examples:
                GetEsimPurchase200Example:
                  summary: Default getEsimPurchase 200 response
                  x-microcks-default: true
                  value:
                    transactionId: txn-abc123
                    offerId: offer-12345
                    status: DONE
                    type: TOPUP
                    createdAt: '2026-05-01T12:00:00Z'
                    send:
                      amount: {}
                      currency: {}
                    receive:
                      amount: {}
                      currency: {}
                    details: *id001
      security:
        - BearerAuth: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /esim/purchases/{transactionId}/qrcode:
    get:
      operationId: getEsimQrCode
      summary: Zendit Get ESIM QR Code
      description: Retrieve activation QR code as PNG image.
      tags: [eSIM]
      parameters:
        - $ref: '#/components/parameters/TransactionId'
      responses:
        '200':
          description: QR code image
          content:
            image/png:
              schema:
                type: string
                format: binary
      security:
        - BearerAuth: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /esim/{iccId}/plans:
    get:
      operationId: getEsimPlans
      summary: Zendit Get ESIM Plans
      description: Monitor active/queued plans and data usage.
      tags: [eSIM]
      parameters:
        - name: iccId
          in: path
          required: true
          schema:
            type: string
          example: '8901260000000000001'
      responses:
        '200':
          description: List of eSIM plans
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EsimPlanList'
              examples:
                GetEsimPlans200Example:
                  summary: Default getEsimPlans 200 response
                  x-microcks-default: true
                  value:
                    iccId: '8901260000000000001'
                    plans: &id009
                      - {}
      security:
        - BearerAuth: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /esim/purchases/{transactionId}/refund:
    get:
      operationId: getEsimRefund
      summary: Zendit Get ESIM Refund
      description: Check refund status for eSIM purchase.
      tags: [eSIM]
      parameters:
        - $ref: '#/components/parameters/TransactionId'
      responses:
        '200':
          description: Refund status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Refund'
              examples:
                GetEsimRefund200Example:
                  summary: Default getEsimRefund 200 response
                  x-microcks-default: true
                  value:
                    transactionId: '500123'
                    refundId: refund-abc123
                    status: APPROVED
                    amount:
                      amount: {}
                      currency: {}
                    createdAt: '2026-05-01T12:00:00Z'
      security:
        - BearerAuth: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createEsimRefund
      summary: Zendit Create ESIM Refund
      description: Initiate refund request for eSIM purchase.
      tags: [eSIM]
      parameters:
        - $ref: '#/components/parameters/TransactionId'
      responses:
        '200':
          description: Refund initiated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Refund'
              examples:
                CreateEsimRefund200Example:
                  summary: Default createEsimRefund 200 response
                  x-microcks-default: true
                  value:
                    transactionId: '500123'
                    refundId: refund-abc123
                    status: APPROVED
                    amount:
                      amount: {}
                      currency: {}
                    createdAt: '2026-05-01T12:00:00Z'
      security:
        - BearerAuth: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /vouchers/offers:
    get:
      operationId: listVoucherOffers
      summary: Zendit List Voucher Offers
      description: List gift card and utility offers.
      tags: [Vouchers]
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
        - $ref: '#/components/parameters/Country'
      responses:
        '200':
          description: List of voucher offers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OfferList'
              examples:
                ListVoucherOffers200Example:
                  summary: Default listVoucherOffers 200 response
                  x-microcks-default: true
                  value:
                    list: *id002
                    offset: 0
                    limit: 100
                    total: 1500
      security:
        - BearerAuth: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /vouchers/offers/{offerId}:
    get:
      operationId: getVoucherOffer
      summary: Zendit Get Voucher Offer
      description: Get voucher offer details with required fields.
      tags: [Vouchers]
      parameters:
        - $ref: '#/components/parameters/OfferId'
      responses:
        '200':
          description: Voucher offer detail
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Offer'
              examples:
                GetVoucherOffer200Example:
                  summary: Default getVoucherOffer 200 response
                  x-microcks-default: true
                  value:
                    offerId: offer-12345
                    name: Rebel Prepaid 10 USD
                    brand: rebel-prepaid
                    country: US
                    type: TOPUP
                    subType: Mobile Top Up
                    price:
                      amount: {}
                      currency: {}
                    send:
                      amount: {}
                      currency: {}
                    receive:
                      amount: {}
                      currency: {}
      security:
        - BearerAuth: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /vouchers/purchases:
    get:
      operationId: listVoucherPurchases
      summary: Zendit List Voucher Purchases
      description: Query voucher transactions.
      tags: [Vouchers]
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: List of voucher purchases
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PurchaseList'
              examples:
                ListVoucherPurchases200Example:
                  summary: Default listVoucherPurchases 200 response
                  x-microcks-default: true
                  value:
                    list: *id003
                    offset: 0
                    limit: 100
                    total: 50
      security:
        - BearerAuth: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createVoucherPurchase
      summary: Zendit Create Voucher Purchase
      description: Create gift card or utility payment transaction.
      tags: [Vouchers]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VoucherPurchaseRequest'
            examples:
              CreateVoucherPurchaseRequestExample:
                summary: Default createVoucherPurchase request
                x-microcks-default: true
                value:
                  transactionId: my-txn-abc123
                  offerId: voucher-offer-001
                  sendValue:
                    amount: {}
                    currency: {}
                  recipient: &id006
                    email: recipient@example.com
                    firstName: Jane
                    lastName: Smith
      responses:
        '201':
          description: Voucher purchase created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Purchase'
              examples:
                CreateVoucherPurchase201Example:
                  summary: Default createVoucherPurchase 201 response
                  x-microcks-default: true
                  value:
                    transactionId: txn-abc123
                    offerId: offer-12345
                    status: DONE
                    type: TOPUP
                    createdAt: '2026-05-01T12:00:00Z'
                    send:
                      amount: {}
                      currency: {}
                    receive:
                      amount: {}
                      currency: {}
                    details: *id001
      security:
        - BearerAuth: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /vouchers/purchases/{transactionId}:
    get:
      operationId: getVoucherPurchase
      summary: Zendit Get Voucher Purchase
      description: Retrieve voucher transaction with receipt data.
      tags: [Vouchers]
      parameters:
        - $ref: '#/components/parameters/TransactionId'
      responses:
        '200':
          description: Voucher purchase detail
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Purchase'
              examples:
                GetVoucherPurchase200Example:
                  summary: Default getVoucherPurchase 200 response
                  x-microcks-default: true
                  value:
                    transactionId: txn-abc123
                    offerId: offer-12345
                    status: DONE
                    type: TOPUP
                    createdAt: '2026-05-01T12:00:00Z'
                    send:
                      amount: {}
                      currency: {}
                    receive:
                      amount: {}
                      currency: {}
                    details: *id001
      security:
        - BearerAuth: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /transactions:
    get:
      operationId: listTransactions
      summary: Zendit List Transactions
      description: List all transactions across product types.
      tags: [Transactions]
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
        - $ref: '#/components/parameters/Status'
      responses:
        '200':
          description: List of transactions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionList'
              examples:
                ListTransactions200Example:
                  summary: Default listTransactions 200 response
                  x-microcks-default: true
                  value:
                    list: &id008
                      - {}
                    offset: 100
                    limit: 100
                    total: 100
      security:
        - BearerAuth: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /transactions/{transactionId}:
    get:
      operationId: getTransaction
      summary: Zendit Get Transaction
      description: Get transaction with full history log.
      tags: [Transactions]
      parameters:
        - $ref: '#/components/parameters/TransactionId'
      responses:
        '200':
          description: Transaction detail
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Transaction'
              examples:
                GetTransaction200Example:
                  summary: Default getTransaction 200 response
                  x-microcks-default: true
                  value:
                    transactionId: txn-abc123
                    type: TOPUP
                    status: DONE
                    createdAt: '2026-05-01T12:00:00Z'
                    history: &id007
                      - status: PENDING
                        timestamp: '2026-05-01T12:00:00Z'
      security:
        - BearerAuth: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /tools/phonenumberlookup/{msisdn}:
    get:
      operationId: lookupPhoneNumber
      summary: Zendit Lookup Phone Number
      description: Identify carrier from phone number in E.164 format. BETA endpoint.
      tags: [Tools]
      parameters:
        - name: msisdn
          in: path
          required: true
          schema:
            type: string
          example: '+15555550100'
      responses:
        '200':
          description: Lookup result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhoneLookup'
              examples:
                LookupPhoneNumber200Example:
                  summary: Default lookupPhoneNumber 200 response
                  x-microcks-default: true
                  value:
                    msisdn: '+15555550100'
                    country: US
                    carrier: Example Mobile
                    brand: rebel-prepaid
                    type: MOBILE
      security:
        - BearerAuth: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /reports:
    post:
      operationId: createReport
      summary: Zendit Create Report
      description: Generate transaction report (CSV) asynchronously.
      tags: [Reports]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReportRequest'
            examples:
              CreateReportRequestExample:
                summary: Default createReport request
                x-microcks-default: true
                value:
                  dateFrom: '2026-04-01'
                  dateTo: '2026-04-30'
                  type: TRANSACTIONS
      responses:
        '202':
          description: Report job accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Report'
              examples:
                CreateReport202Example:
                  summary: Default createReport 202 response
                  x-microcks-default: true
                  value:
                    reportId: report-abc123
                    status: READY
                    downloadUrl: https://api.zendit.io/v1/reports/report-abc123/download
                    createdAt: '2026-05-01T12:00:00Z'
      security:
        - BearerAuth: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /reports/{reportId}:
    get:
      operationId: getReport
      summary: Zendit Get Report
      description: Check report generation status.
      tags: [Reports]
      parameters:
        - name: reportId
          in: path
          required: true
          schema:
            type: string
          example: '500123'
      responses:
        '200':
          description: Report detail
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Report'
              examples:
                GetReport200Example:
                  summary: Default getReport 200 response
                  x-microcks-default: true
                  value:
                    reportId: report-abc123
                    status: READY
                    downloadUrl: https://api.zendit.io/v1/reports/report-abc123/download
                    createdAt: '2026-05-01T12:00:00Z'
      security:
        - BearerAuth: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /reports/{reportId}/download:
    get:
      operationId: downloadReport
      summary: Zendit Download Report
      description: Download completed report file (CSV).
      tags: [Reports]
      parameters:
        - name: reportId
          in: path
          required: true
          schema:
            type: string
          example: '500123'
      responses:
        '200':
          description: CSV report file
          content:
            text/csv:
              schema:
                type: string
                format: binary
      security:
        - BearerAuth: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: Bearer token authentication using your Zendit API key.
  parameters:
    Limit:
      name: _limit
      in: query
      required: true
      description: Items per page (1-1024).
      schema:
        type: integer
        minimum: 1
        maximum: 1024
        default: 100
      example: 100
    Offset:
      name: _offset
      in: query
      required: true
      description: Pagination offset.
      schema:
        type: integer
        minimum: 0
        default: 0
      example: 0
    Country:
      name: country
      in: query
      description: Two-letter ISO country code.
      schema:
        type: string
        minLength: 2
        maxLength: 2
      example: US
    Status:
      name: status
      in: query
      description: Transaction status filter.
      schema:
        type: string
        enum: [DONE, FAILED, PENDING, ACCEPTED, AUTHORIZED, IN_PROGRESS]
      example: DONE
    OfferId:
      name: offerId
      in: path
      required: true
      description: Offer identifier.
      schema:
        type: string
      example: offer-12345
    TransactionId:
      name: transactionId
      in: path
      required: true
      description: Transaction identifier.
      schema:
        type: string
      example: txn-abc123
  schemas:
    Balance:
      type: object
      description: Wallet balance and currency information.
      properties:
        amount:
          type: number
          description: Available balance amount.
          example: 1234.56
        currency:
          type: string
          description: ISO 4217 currency code.
          example: USD
        accountId:
          type: string
          description: Account identifier.
          example: acc-12345
    Brand:
      type: object
      description: Brand catalog entry.
      properties:
        id:
          type: string
          description: Brand identifier.
          example: rebel-prepaid
        name:
          type: string
          description: Brand name.
          example: Rebel Prepaid
        country:
          type: string
          description: Country code.
          example: US
        logoUrl:
          type: string
          format: uri
          description: Brand logo URL.
          example: https://cdn.zendit.io/logos/rebel.png
        types:
          type: array
          description: Product types offered.
          items:
            type: string
          example: *id004
    BrandList:
      type: object
      description: Paginated brand list.
      properties:
        list:
          type: array
          items:
            $ref: '#/components/schemas/Brand'
          example: *id005
        offset:
          type: integer
          example: 0
        limit:
          type: integer
          example: 100
        total:
          type: integer
          example: 250
    RedemptionInstructions:
      type: object
      description: Brand redemption terms by delivery type.
      properties:
        deliveryType:
          type: string
          example: SMS
        instructions:
          type: string
          example: Dial *123# from your phone to redeem.
        termsAndConditions:
          type: string
          example: Valid for 30 days from purchase.
    Offer:
      type: object
      description: Product offer (top-up, eSIM, voucher).
      properties:
        offerId:
          type: string
          description: Unique offer identifier.
          example: offer-12345
        name:
          type: string
          description: Offer display name.
          example: Rebel Prepaid 10 USD
        brand:
          type: string
          description: Brand identifier.
          example: rebel-prepaid
        country:
          type: string
          description: Country code.
          example: US
        type:
          type: string
          description: Offer type.
          example: TOPUP
        subType:
          type: string
          description: Offer sub-type.
          example: Mobile Top Up
        price:
          $ref: '#/components/schemas/Price'
        send:
          $ref: '#/components/schemas/Price'
        receive:
          $ref: '#/components/schemas/Price'
    OfferList:
      type: object
      description: Paginated offer list.
      properties:
        list:
          type: array
          items:
            $ref: '#/components/schemas/Offer'
          example: *id002
        offset:
          type: integer
          example: 0
        limit:
          type: integer
          example: 100
        total:
          type: integer
          example: 1500
    Price:
      type: object
      description: Monetary amount with currency.
      properties:
        amount:
          type: number
          example: 10.00
        currency:
          type: string
          example: USD
    TopupPurchaseRequest:
      type: object
      description: Top-up purchase request.
      required:
        - offerId
        - subscriberNumber
      properties:
        transactionId:
          type: string
          description: Client-provided idempotency key.
          example: my-txn-abc123
        offerId:
          type: string
          description: Offer to purchase.
          example: offer-12345
        subscriberNumber:
          type: string
          description: Recipient phone number in E.164 format.
          example: '+15555550100'
        sendValue:
          $ref: '#/components/schemas/Price'
    EsimPurchaseRequest:
      type: object
      description: eSIM purchase request.
      required:
        - offerId
      properties:
        transactionId:
          type: string
          example: my-txn-abc123
        offerId:
          type: string
          example: esim-offer-001
        iccId:
          type: string
          description: ICC ID of existing eSIM (for adding plan to existing eSIM).
          example: '8901260000000000001'
    VoucherPurchaseRequest:
      type: object
      description: Voucher purchase request.
      required:
        - offerId
      properties:
        transactionId:
          type: string
          example: my-txn-abc123
        offerId:
          type: string
          example: voucher-offer-001
        sendValue:
          $ref: '#/components/schemas/Price'
        recipient:
          type: object
          description: Recipient details.
          properties:
            email:
              type: string
              format: email
              example: recipient@example.com
            firstName:
              type: string
              example: Jane
            lastName:
              type: string
              example: Smith
          example: *id006
    Purchase:
      type: object
      description: Purchase transaction.
      properties:
        transactionId:
          type: string
          example: txn-abc123
        offerId:
          type: string
          example: offer-12345
        status:
          type: string
          enum: [DONE, FAILED, PENDING, ACCEPTED, AUTHORIZED, IN_PROGRESS]
          example: DONE
        type:
          type: string
          example: TOPUP
        createdAt:
          type: string
          format: date-time
          example: '2026-05-01T12:00:00Z'
        send:
          $ref: '#/components/schemas/Price'
        receive:
          $ref: '#/components/schemas/Price'
        details:
          type: object
          additionalProperties: true
          description: Product-specific details (top-up subscriber, voucher recipient, eSIM activation code, etc).
          example: *id001
    PurchaseList:
      type: object
      description: Paginated purchase list.
      properties:
        list:
          type: array
          items:
            $ref: '#/components/schemas/Purchase'
          example: *id003
        offset:
          type: integer
          example: 0
        limit:
          type: integer
          example: 100
        total:
          type: integer
          example: 50
    Transaction:
      type: object
      description: Transaction with history log.
      properties:
        transactionId:
          type: string
          example: txn-abc123
        type:
          type: string
          example: TOPUP
        status:
          type: string
          example: DONE
        createdAt:
          type: string
          format: date-time
          example: '2026-05-01T12:00:00Z'
        history:
          type: array
          description: Transaction status history.
          items:
            type: object
            properties:
              status:
                type: string
                example: PENDING
              timestamp:
                type: string
                format: date-time
                example: '2026-05-01T12:00:00Z'
          example: *id007
    TransactionList:
      type: object
      description: Paginated transaction list.
      properties:
        list:
          type: array
          items:
            $ref: '#/components/schemas/Transaction'
          example: *id008
        offset:
          type: integer
          example: 100
        limit:
          type: integer
          example: 100
        total:
          type: integer
          example: 100
    EsimPlan:
      type: object
      description: Active or queued eSIM plan.
      properties:
        planId:
          type: string
          example: plan-abc123
        status:
          type: string
          example: ACTIVE
        dataUsed:
          type: number
          description: Data used in MB.
          example: 1024.5
        dataTotal:
          type: number
          description: Total data in MB.
          example: 5120.0
        validUntil:
          type: string
          format: date-time
          example: '2026-06-01T00:00:00Z'
    EsimPlanList:
      type: object
      description: List of eSIM plans for an ICC ID.
      properties:
        iccId:
          type: string
          example: '8901260000000000001'
        plans:
          type: array
          items:
            $ref: '#/components/schemas/EsimPlan'
          example: *id009
    Refund:
      type: object
      description: Refund status for an eSIM purchase.
      properties:
        transactionId:
          type: string
          example: '500123'
        refundId:
          type: string
          example: refund-abc123
        status:
          type: string
          enum: [REQUESTED, APPROVED, COMPLETED, REJECTED]
          example: APPROVED
        amount:
          $ref: '#/components/schemas/Price'
        createdAt:
          type: string
          format: date-time
          example: '2026-05-01T12:00:00Z'
    PhoneLookup:
      type: object
      description: Phone number carrier lookup result.
      properties:
        msisdn:
          type: string
          example: '+15555550100'
        country:
          type: string
          example: US
        carrier:
          type: string
          example: Example Mobile
        brand:
          type: string
          example: rebel-prepaid
        type:
          type: string
          example: MOBILE
    ReportRequest:
      type: object
      description: Asynchronous report generation request.
      required:
        - dateFrom
        - dateTo
      properties:
        dateFrom:
          type: string
          format: date
          example: '2026-04-01'
        dateTo:
          type: string
          format: date
          example: '2026-04-30'
        type:
          type: string
          enum: [TRANSACTIONS, BALANCE, COMMISSION]
          example: TRANSACTIONS
    Report:
      type: object
      description: Asynchronous report job.
      properties:
        reportId:
          type: string
          example: report-abc123
        status:
          type: string
          enum: [PENDING, IN_PROGRESS, READY, FAILED]
          example: READY
        downloadUrl:
          type: string
          format: uri
          example: https://api.zendit.io/v1/reports/report-abc123/download
        createdAt:
          type: string
          format: date-time
          example: '2026-05-01T12:00:00Z'
    Error:
      type: object
      description: Error response.
      properties:
        code:
          type: string
          example: INVALID_REQUEST
        description:
          type: string
          example: The request is missing required parameter offerId.
        message:
          type: string
          example: offerId is required.