Maya Mobile Usage and Topup API

openapi: 3.0.1
info:
  title: Maya Mobile Connect+ Connectivity API
  description: >-
    Maya Mobile (Mobile Maya Inc) Connect+ Connectivity REST API for provisioning
    eSIMs and data packages, monitoring activation status and data usage, processing
    top-ups, and receiving lifecycle events via webhooks across 400+ roaming
    networks in 200+ destinations.


    NOTE: Maya Mobile distributes the full Connectivity API reference under NDA to
    onboarded resellers and partners. This document models the publicly described
    capabilities of the Connect+ API (eSIM provisioning, data packages/plans,
    status and usage, top-ups, orders, and webhooks). Exact endpoint paths,
    request/response schemas, and authentication parameters are confirmed against
    the partner documentation during onboarding and are not fully published.
    Paths below reflect the documented capability surface and are marked as
    unreconciled where exact shapes are not public.
  termsOfService: https://maya.net/terms
  contact:
    name: Maya Mobile Partnerships
    url: https://maya.net/business
  version: '1.0'
servers:
  - url: https://api.maya.net/connectivity/v1
    description: >-
      Connect+ Connectivity API base URL (representative; confirm exact host and
      version path against partner documentation during onboarding).
security:
  - bearerAuth: []
tags:
  - name: Plans
    description: Pre-made data plans and the catalog of countries, regions, and networks.
  - name: eSIMs
    description: eSIM provisioning, activation codes/QR, suspend and reactivate.
  - name: Usage
    description: Real-time eSIM status and data-usage reporting.
  - name: Orders
    description: Placing and assigning data-package orders, including top-ups.
  - name: Webhooks
    description: Lifecycle and usage event callbacks.
paths:
  /plans:
    get:
      operationId: listPlans
      tags:
        - Plans
      summary: List available data plans and products
      description: >-
        Returns the catalog of pre-made data plans and the countries, regions,
        and roaming networks available for building eSIM data packages.
      parameters:
        - name: country
          in: query
          required: false
          schema:
            type: string
          description: ISO country code to filter the available plans/packages.
        - name: region
          in: query
          required: false
          schema:
            type: string
          description: Region identifier to filter the available plans/packages.
      responses:
        '200':
          description: A list of available plans/products.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Plan'
  /esims:
    post:
      operationId: createEsim
      tags:
        - eSIMs
      summary: Provision a new eSIM
      description: >-
        Requests an eSIM with the selected roaming profile and returns the
        activation code and QR code ready to install.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEsimRequest'
      responses:
        '201':
          description: The provisioned eSIM with activation details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Esim'
  /esims/{esimId}:
    get:
      operationId: getEsim
      tags:
        - eSIMs
      summary: Get an eSIM
      description: Returns the current state and installation status of a single eSIM.
      parameters:
        - name: esimId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The requested eSIM.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Esim'
  /esims/{esimId}/suspend:
    post:
      operationId: suspendEsim
      tags:
        - eSIMs
      summary: Suspend an eSIM
      description: Suspends an active eSIM anywhere in the world.
      parameters:
        - name: esimId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The eSIM after suspension.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Esim'
  /esims/{esimId}/reactivate:
    post:
      operationId: reactivateEsim
      tags:
        - eSIMs
      summary: Reactivate an eSIM
      description: Reactivates a previously suspended eSIM.
      parameters:
        - name: esimId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The eSIM after reactivation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Esim'
  /esims/{esimId}/usage:
    get:
      operationId: getEsimUsage
      tags:
        - Usage
      summary: Get eSIM data usage
      description: >-
        Returns real-time data-usage and installation status for an eSIM.
      parameters:
        - name: esimId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Usage and status for the eSIM.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Usage'
  /esims/{esimId}/topup:
    post:
      operationId: topupEsim
      tags:
        - Orders
      summary: Top up an eSIM
      description: >-
        Adds (tops up) an additional data package to an existing eSIM for the
        specified country, region, or network.
      parameters:
        - name: esimId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TopupRequest'
      responses:
        '201':
          description: The resulting order/top-up.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
  /orders:
    post:
      operationId: createOrder
      tags:
        - Orders
      summary: Create a data-package order
      description: >-
        Places a data-package order and assigns it to an eSIM for specific
        countries, regions, and networks. Supports one or multiple packages.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrderRequest'
      responses:
        '201':
          description: The created order.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
    get:
      operationId: listOrders
      tags:
        - Orders
      summary: List orders
      description: Lists previously placed data-package orders.
      responses:
        '200':
          description: A list of orders.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Order'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Bearer token / API key supplied in the Authorization header
        (`Authorization: Bearer <token>`). Credentials are issued to onboarded
        Maya Mobile resellers/partners.
  schemas:
    Plan:
      type: object
      description: A pre-made data plan or data-package template.
      properties:
        id:
          type: string
        name:
          type: string
        type:
          type: string
          description: Traffic policy, e.g. fixed-limit, time-limited, unlimited, or throttled.
        data_amount:
          type: string
          description: Included data allowance (e.g. in MB/GB) where applicable.
        validity_days:
          type: integer
          description: Validity period in days where applicable.
        countries:
          type: array
          items:
            type: string
          description: ISO country codes covered by the plan.
    CreateEsimRequest:
      type: object
      properties:
        plan_id:
          type: string
          description: Identifier of the plan/roaming profile to provision.
        region:
          type: string
        country:
          type: string
      required:
        - plan_id
    Esim:
      type: object
      properties:
        id:
          type: string
        iccid:
          type: string
        status:
          type: string
          description: Lifecycle status (e.g. provisioned, installed, active, suspended).
        activation_code:
          type: string
          description: Manual activation code for the eSIM profile.
        qr_code_url:
          type: string
          description: URL of the QR code used to install the eSIM.
    Usage:
      type: object
      properties:
        esim_id:
          type: string
        status:
          type: string
        data_used:
          type: number
          description: Data consumed.
        data_remaining:
          type: number
          description: Data remaining where the policy is metered.
        unit:
          type: string
          description: Unit for the usage values (e.g. MB).
    TopupRequest:
      type: object
      properties:
        plan_id:
          type: string
        country:
          type: string
        region:
          type: string
      required:
        - plan_id
    CreateOrderRequest:
      type: object
      properties:
        esim_id:
          type: string
          description: Target eSIM to assign the package(s) to.
        items:
          type: array
          items:
            type: object
            properties:
              plan_id:
                type: string
              quantity:
                type: integer
      required:
        - items
    Order:
      type: object
      properties:
        id:
          type: string
        esim_id:
          type: string
        status:
          type: string
        items:
          type: array
          items:
            type: object
            properties:
              plan_id:
                type: string
              quantity:
                type: integer