Paymob

Paymob Subscriptions API

The Subscriptions Module manages subscription plans (create, list, update, suspend, resume) and per-customer subscriptions billed against tokenised cards. Lifecycle operations cover suspend, resume, cancel, secondary card attachment, and transaction inspection. Initial subscription creation flows through /v1/intention/ for card capture.

Paymob Subscriptions API is one of 5 APIs that Paymob publishes on the APIs.io network, described by a machine-readable OpenAPI specification.

This API exposes 1 machine-runnable capability that can be deployed as REST, MCP, or Agent Skill surfaces via Naftiko.

Tagged areas include Payments, Subscriptions, and Recurring Billing. The published artifact set on APIs.io includes API documentation, an OpenAPI specification, and 1 Naftiko capability spec.

Documentation GitHub OpenAPI

OpenAPI Specification

openapi: 3.0.3
info:
  title: Paymob Subscriptions API
  version: "1.0"
  description: >-
    The Paymob Subscriptions Module manages subscription plans and recurring
    subscriptions billed against tokenised cards. Plans define amount, interval,
    and frequency; subscriptions attach a customer card to a plan. Lifecycle
    operations include suspend, resume, cancel, secondary card attachment, and
    transaction inspection.
  contact:
    name: Paymob Developers
    url: https://developers.paymob.com
servers:
- url: https://accept.paymob.com
  description: Egypt production
- url: https://ksa.paymob.com
  description: Saudi Arabia production
- url: https://uae.paymob.com
  description: UAE production
security:
- BearerAuth: []
paths:
  /api/acceptance/subscription-plans:
    post:
      summary: Create Subscription Plan
      operationId: createSubscriptionPlan
      tags: [Subscription Plans]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriptionPlanRequest'
      responses:
        '201':
          description: Plan created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionPlan'
    get:
      summary: List Subscription Plans
      operationId: listSubscriptionPlans
      tags: [Subscription Plans]
      responses:
        '200':
          description: List of plans
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SubscriptionPlan'
  /api/acceptance/subscription-plans/{subscription_plan_id}:
    put:
      summary: Update Subscription Plan
      operationId: updateSubscriptionPlan
      tags: [Subscription Plans]
      parameters:
      - $ref: '#/components/parameters/PlanId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriptionPlanRequest'
      responses:
        '200':
          description: Plan updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionPlan'
  /api/acceptance/subscription-plans/{subscription_plan_id}/suspend:
    post:
      summary: Suspend Subscription Plan
      operationId: suspendSubscriptionPlan
      tags: [Subscription Plans]
      parameters:
      - $ref: '#/components/parameters/PlanId'
      responses:
        '200':
          description: Plan suspended
  /api/acceptance/subscription-plans/{subscription_plan_id}/resume:
    post:
      summary: Resume Subscription Plan
      operationId: resumeSubscriptionPlan
      tags: [Subscription Plans]
      parameters:
      - $ref: '#/components/parameters/PlanId'
      responses:
        '200':
          description: Plan resumed
  /api/acceptance/subscriptions/{subscription_id}:
    get:
      summary: Retrieve Subscription
      operationId: retrieveSubscription
      tags: [Subscriptions]
      parameters:
      - $ref: '#/components/parameters/SubscriptionId'
      responses:
        '200':
          description: Subscription details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
    put:
      summary: Update Subscription
      operationId: updateSubscription
      tags: [Subscriptions]
      parameters:
      - $ref: '#/components/parameters/SubscriptionId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
  /api/acceptance/subscriptions/{subscription_id}/suspend:
    post:
      summary: Suspend Subscription
      operationId: suspendSubscription
      tags: [Subscriptions]
      parameters:
      - $ref: '#/components/parameters/SubscriptionId'
      responses:
        '200':
          description: Suspended
  /api/acceptance/subscriptions/{subscription_id}/resume:
    post:
      summary: Resume Subscription
      operationId: resumeSubscription
      tags: [Subscriptions]
      parameters:
      - $ref: '#/components/parameters/SubscriptionId'
      responses:
        '200':
          description: Resumed
  /api/acceptance/subscriptions/{subscription_id}/cancel:
    post:
      summary: Cancel Subscription
      operationId: cancelSubscription
      tags: [Subscriptions]
      parameters:
      - $ref: '#/components/parameters/SubscriptionId'
      responses:
        '200':
          description: Cancelled
  /api/acceptance/subscriptions/{subscription_id}/last-transaction:
    get:
      summary: Get Last Subscription Transaction
      operationId: getLastSubscriptionTransaction
      tags: [Subscriptions]
      parameters:
      - $ref: '#/components/parameters/SubscriptionId'
      responses:
        '200':
          description: Last transaction
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
  /api/acceptance/subscriptions/{subscription_id}/transactions:
    get:
      summary: List Subscription Transactions
      operationId: listSubscriptionTransactions
      tags: [Subscriptions]
      parameters:
      - $ref: '#/components/parameters/SubscriptionId'
      responses:
        '200':
          description: Transactions
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  additionalProperties: true
  /api/acceptance/subscriptions/{subscription_id}/card-tokens:
    get:
      summary: List Subscription Card Tokens
      operationId: listSubscriptionCardTokens
      tags: [Subscriptions]
      parameters:
      - $ref: '#/components/parameters/SubscriptionId'
      responses:
        '200':
          description: Card tokens
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  additionalProperties: true
components:
  parameters:
    PlanId:
      name: subscription_plan_id
      in: path
      required: true
      schema:
        type: string
    SubscriptionId:
      name: subscription_id
      in: path
      required: true
      schema:
        type: string
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
  schemas:
    SubscriptionPlanRequest:
      type: object
      required: [frequency, amount_cents, name]
      properties:
        name:
          type: string
        amount_cents:
          type: integer
        frequency:
          type: string
          enum: [day, week, month, year]
        integration:
          type: integer
        reminder_days:
          type: integer
        retrial_days:
          type: integer
        number_of_deductions:
          type: integer
        plan_type:
          type: string
          enum: [renew, installment]
    SubscriptionPlan:
      allOf:
      - $ref: '#/components/schemas/SubscriptionPlanRequest'
      - type: object
        properties:
          id:
            type: string
          status:
            type: string
            enum: [active, suspended]
          created_at:
            type: string
            format: date-time
    Subscription:
      type: object
      properties:
        id:
          type: string
        plan_id:
          type: string
        status:
          type: string
          enum: [active, suspended, cancelled, expired]
        starts_at:
          type: string
          format: date-time
        next_billing_date:
          type: string
          format: date-time
        card_token:
          type: string
        primary_email:
          type: string
        first_name:
          type: string
        last_name:
          type: string

Paymob Subscriptions API

Documentation

Specifications

Other Resources

OpenAPI Specification