openapi: 3.0.3
info:
  title: Zendit Account eSIM 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: eSIM
  description: eSIM plans and activation
paths:
  /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:
                    - {}
                    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:
                    - {}
                    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: {}
      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: {}
      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:
                    - {}
      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
components:
  schemas:
    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'
    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'
    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: {}
    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'
    PurchaseList:
      type: object
      description: Paginated purchase list.
      properties:
        list:
          type: array
          items:
            $ref: '#/components/schemas/Purchase'
          example:
          - {}
        offset:
          type: integer
          example: 0
        limit:
          type: integer
          example: 100
        total:
          type: integer
          example: 50
    Price:
      type: object
      description: Monetary amount with currency.
      properties:
        amount:
          type: number
          example: 10.0
        currency:
          type: string
          example: USD
    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:
          - {}
    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'
    OfferList:
      type: object
      description: Paginated offer list.
      properties:
        list:
          type: array
          items:
            $ref: '#/components/schemas/Offer'
          example:
          - {}
        offset:
          type: integer
          example: 0
        limit:
          type: integer
          example: 100
        total:
          type: integer
          example: 1500
  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
    OfferId:
      name: offerId
      in: path
      required: true
      description: Offer identifier.
      schema:
        type: string
      example: offer-12345
    Offset:
      name: _offset
      in: query
      required: true
      description: Pagination offset.
      schema:
        type: integer
        minimum: 0
        default: 0
      example: 0
    TransactionId:
      name: transactionId
      in: path
      required: true
      description: Transaction identifier.
      schema:
        type: string
      example: txn-abc123
    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
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: Bearer token authentication using your Zendit API key.