openapi: 3.1.0
info:
  title: Jodo ERP Integrations API
  version: v1
  summary: Fee collection, flexible instalment plans and education credit for Indian educational institutes.
  description: |
    Jodo's ERP Integrations API lets an institute's ERP, finance or student-information system
    connect to Jodo fee collection. It covers user registration and hosted-flow access tokens,
    student master data and fee structures, manual/direct payment reconciliation, Flex instalment
    plans, Pay checkout orders and shareable payment links, and webhook subscription management.

    PROVENANCE: Jodo publishes no OpenAPI document. This description was assembled from Jodo's own
    public API reference at https://docs.jodo.in/ (Astro Starlight, server-rendered HTML), one
    documented operation per reference page. Every path, method, path/query parameter, request-body
    field, response field and error code below is transcribed from the corresponding docs page named
    in the operation's `x-source` extension. No operation, parameter or field has been invented.
    Field types are the ones the docs state. Where the docs do not state a constraint, none is asserted.
  contact:
    name: Jodo
    url: https://docs.jodo.in/
  x-provenance:
    method: generated
    generated_by: API Evangelist enrichment pipeline
    generated: '2026-08-23'
    source_docs: https://docs.jodo.in/
    note: >-
      Endpoint paths, methods, parameters, request/response fields and error codes are grounded in
      docs.jodo.in as fetched 2026-08-23 (all reference pages HTTP 200). This is a third-party
      rendering of Jodo's published reference, not a Jodo-published artifact. Reconcile against the
      live API reference before relying on it.
servers:
  - url: https://ext.jodo.in
    description: Production API host. Jodo documents this as base_url on https://docs.jodo.in/getting-started/environments/. https://api.jodo.in is documented as jodo_auth_host and issues an HTTP 301 to https://ext.jodo.in.
  - url: https://ext.devtest1.jodopay.com
    description: UAT / sandbox API host, documented on https://docs.jodo.in/getting-started/environments/. jodopay.com is Jodo's own non-production domain (the company also operates @Jodopay social handles).
security:
  - basicAuth: []
tags:
  - name: Users
    description: Register ERP/institute users and mint short-lived tokens for Jodo-hosted flows.
  - name: Students
    description: Student master data, fee structures and manual payment reconciliation.
  - name: Flex
    description: Flexible instalment plans backed by an auto-debit mandate.
  - name: Pay
    description: Checkout orders and shareable hosted payment links.
  - name: Configuration
    description: Institute reference data (branches, grades, fee components, discounts) and webhook subscriptions.
paths:
  /api/v1/integrations/erp/users/register:
    post:
      operationId: registerUser
      summary: Register User
      description: Register a user uniquely identified by phone number and email. Used for seamless login and redirection into Jodo-hosted flows.
      tags: [Users]
      x-source: https://docs.jodo.in/user/api/register-user/
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/RegisterUserRequest' }
      responses:
        '200':
          description: User registered.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/RegisterUserResponse' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
  /api/v1/integrations/erp/users/{registration_id}/access_token:
    get:
      operationId: getAccessToken
      summary: Get Access Token
      description: Generate a short-lived access token for a registered user so your application can redirect them into Jodo-hosted flows.
      tags: [Users]
      x-source: https://docs.jodo.in/user/api/get-access-token/
      parameters:
        - $ref: '#/components/parameters/RegistrationId'
      responses:
        '200':
          description: Access token issued.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/AccessTokenResponse' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
  /api/v1/integrations/erp/users/{registration_id}/students:
    post:
      operationId: registerStudent
      summary: Register Student
      description: Register a new student for a given user, uniquely identified by registration_id. Creates student profiles associated with specific users within the Jodo system.
      tags: [Students]
      x-source: https://docs.jodo.in/student/api/register-student/
      parameters:
        - $ref: '#/components/parameters/RegistrationId'
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/RegisterStudentRequest' }
      responses:
        '200':
          description: Student registered.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/StatusOnlyResponse' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
  /api/v1/integrations/erp/students/{jodo_student_id}:
    get:
      operationId: getStudent
      summary: Get Student
      description: Returns student details identified by jodo_student_id.
      tags: [Students]
      x-source: https://docs.jodo.in/student/api/get-student/
      parameters:
        - $ref: '#/components/parameters/JodoStudentId'
      responses:
        '200':
          description: Student record.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/StudentResponse' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
    patch:
      operationId: updateStudent
      summary: Update Student
      description: Update the profile details of a student identified by jodo_student_id.
      tags: [Students]
      x-source: https://docs.jodo.in/student/api/update-student/
      parameters:
        - $ref: '#/components/parameters/JodoStudentId'
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/Student' }
      responses:
        '200':
          description: Student updated.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/StudentResponse' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '404': { $ref: '#/components/responses/NotFound' }
  /api/v1/integrations/erp/students/{jodo_student_id}/fee:
    patch:
      operationId: updateStudentFee
      summary: Update Fee
      description: Update the fee components and discounts configured for a student.
      tags: [Students]
      x-source: https://docs.jodo.in/student/api/update-fee/
      parameters:
        - $ref: '#/components/parameters/JodoStudentId'
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/UpdateFeeRequest' }
      responses:
        '200':
          description: Fee updated.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/StatusOnlyResponse' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '404': { $ref: '#/components/responses/NotFound' }
  /api/v1/integrations/erp/students/{jodo_student_id}/products:
    get:
      operationId: listStudentProducts
      summary: List Products
      description: Retrieve Jodo products associated with a student, optionally filtered by product type.
      tags: [Students]
      x-source: https://docs.jodo.in/student/api/list-products/
      parameters:
        - $ref: '#/components/parameters/JodoStudentId'
        - name: product_type
          in: query
          required: false
          description: 'Optional product filter. Possible values: flex, pay, cred.'
          schema:
            type: string
            enum: [flex, pay, cred]
      responses:
        '200':
          description: Products for the student.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ProductListResponse' }
        '404': { $ref: '#/components/responses/NotFound' }
  /api/v1/integrations/erp/students/{jodo_student_id}/payments:
    get:
      operationId: listStudentPayments
      summary: List Payments
      description: Retrieve the payment list for a student identified by jodo_student_id.
      tags: [Students]
      x-source: https://docs.jodo.in/student/api/list-payments/
      parameters:
        - $ref: '#/components/parameters/JodoStudentId'
      responses:
        '200':
          description: Payments recorded for the student.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/PaymentListResponse' }
        '404': { $ref: '#/components/responses/NotFound' }
    post:
      operationId: addStudentPayment
      summary: Add Payment
      description: Record a manual (direct) payment for a student identified by jodo_student_id.
      tags: [Students]
      x-source: https://docs.jodo.in/student/api/add-payment/
      parameters:
        - $ref: '#/components/parameters/JodoStudentId'
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/AddPaymentRequest' }
      responses:
        '200':
          description: Payment recorded.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/StatusOnlyResponse' }
        '400': { $ref: '#/components/responses/BadRequestMAE' }
        '404': { $ref: '#/components/responses/StudentNotFound' }
  /api/v1/integrations/erp/students/{jodo_student_id}/payments/{transaction_id}:
    delete:
      operationId: cancelStudentPayment
      summary: Cancel Payment
      description: Cancel a payment for a student identified by jodo_student_id and transaction_id. Use only for payments recorded through the direct/manual payment API, with the same transaction_id that was sent when the payment was added.
      tags: [Students]
      x-source: https://docs.jodo.in/student/api/cancel-payment/
      parameters:
        - $ref: '#/components/parameters/JodoStudentId'
        - name: transaction_id
          in: path
          required: true
          description: Transaction ID of the payment to cancel.
          schema: { type: string }
      responses:
        '200':
          description: Payment cancelled.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/StatusOnlyResponse' }
        '404': { $ref: '#/components/responses/NotFound' }
  /api/v1/integrations/flex/students/{jodo_student_id}/plans:
    get:
      operationId: getFlexSchedule
      summary: Get Flex Schedule
      description: Fetch the Flex payment schedule configured for a student.
      tags: [Flex]
      x-source: https://docs.jodo.in/flex/api/get-flex-schedule/
      parameters:
        - $ref: '#/components/parameters/JodoStudentId'
      responses:
        '200':
          description: Flex schedule for the student.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/FlexScheduleResponse' }
        '404': { $ref: '#/components/responses/NotFound' }
    post:
      operationId: manageFlexPlan
      summary: Manage Flex Plan
      description: Configure the instalment schedule for a student identified by jodo_student_id.
      tags: [Flex]
      x-source: https://docs.jodo.in/flex/api/manage-flex-plan/
      parameters:
        - $ref: '#/components/parameters/JodoStudentId'
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ManageFlexPlanRequest' }
      responses:
        '200':
          description: Flex plan configured.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/StatusOnlyResponse' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '404': { $ref: '#/components/responses/NotFound' }
  /api/v1/integrations/pay/orders:
    post:
      operationId: createPayOrder
      summary: Create Pay Order
      description: Create a Pay Order to collect an unstructured payment without requiring an existing student record. Returns an order_id and a hosted redirect_url.
      tags: [Pay]
      x-source: https://docs.jodo.in/pay/api/create-order/
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CreatePayOrderRequest' }
      responses:
        '200':
          description: Pay Order created.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/OrderCreatedResponse' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
  /api/v1/integrations/pay/orders/{order_id}:
    get:
      operationId: getPayOrder
      summary: Get Pay Order
      description: Retrieve the current state of a Pay Order after checkout, callback, or webhook processing.
      tags: [Pay]
      x-source: https://docs.jodo.in/pay/api/get-order/
      parameters:
        - $ref: '#/components/parameters/OrderId'
      responses:
        '200':
          description: Pay Order state.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/OrderResponse' }
        '404': { $ref: '#/components/responses/NotFound' }
  /api/v1/integrations/pay/payment_links:
    post:
      operationId: createPaymentLink
      summary: Create Payment Link
      description: Create a payment link when the payer should complete payment from a shareable hosted URL instead of an immediate checkout redirect.
      tags: [Pay]
      x-source: https://docs.jodo.in/pay/api/create-payment-link/
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CreatePaymentLinkRequest' }
      responses:
        '201':
          description: Payment link created.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/OrderCreatedResponse' }
        '400': { $ref: '#/components/responses/BadRequest' }
  /api/v1/integrations/pay/payment_links/{order_id}:
    get:
      operationId: getPaymentLink
      summary: Get Payment Link
      description: Fetch the current state of a payment link using the order_id returned when the link was created.
      tags: [Pay]
      x-source: https://docs.jodo.in/pay/api/get-payment-link/
      parameters:
        - $ref: '#/components/parameters/OrderId'
      responses:
        '200':
          description: Payment link state.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/PaymentLinkResponse' }
        '400': { $ref: '#/components/responses/BadRequest' }
    delete:
      operationId: cancelPaymentLink
      summary: Cancel Payment Link
      description: Cancel a payment link when the payer should no longer be able to complete payment using the hosted URL.
      tags: [Pay]
      x-source: https://docs.jodo.in/pay/api/cancel-payment-link/
      parameters:
        - $ref: '#/components/parameters/OrderId'
      responses:
        '200':
          description: Payment link cancelled.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/MessageResponse' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '404': { $ref: '#/components/responses/NotFound' }
  /api/v1/integrations/erp/branches:
    get:
      operationId: listBranches
      summary: List Branches
      description: Fetch branch names and collector codes configured for the institute.
      tags: [Configuration]
      x-source: https://docs.jodo.in/configuration/api/list-branches/
      responses:
        '200':
          description: Branches configured for the institute.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/GenericListResponse' }
        '401': { $ref: '#/components/responses/Unauthorized' }
  /api/v1/integrations/erp/grades:
    get:
      operationId: listGrades
      summary: List Grades
      description: Fetch grade codes used in student registration and update payloads.
      tags: [Configuration]
      x-source: https://docs.jodo.in/configuration/api/list-grades/
      parameters:
        - $ref: '#/components/parameters/CollectorCode'
      responses:
        '200':
          description: Grade codes.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/GenericListResponse' }
        '401': { $ref: '#/components/responses/Unauthorized' }
  /api/v1/integrations/erp/fee-components:
    get:
      operationId: listFeeComponents
      summary: List Fee Components
      description: Fetch fee component codes used in student fee and payment payloads.
      tags: [Configuration]
      x-source: https://docs.jodo.in/configuration/api/list-fee-components/
      parameters:
        - $ref: '#/components/parameters/CollectorCode'
      responses:
        '200':
          description: Fee component codes.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/GenericListResponse' }
        '401': { $ref: '#/components/responses/Unauthorized' }
  /api/v1/integrations/erp/discounts:
    get:
      operationId: listDiscounts
      summary: List Discounts
      description: Fetch discount codes supported for student fee configuration.
      tags: [Configuration]
      x-source: https://docs.jodo.in/configuration/api/list-discounts/
      parameters:
        - $ref: '#/components/parameters/CollectorCode'
      responses:
        '200':
          description: Discount codes.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/GenericListResponse' }
        '401': { $ref: '#/components/responses/Unauthorized' }
  /api/v1/integrations/erp/webhooks:
    get:
      operationId: listWebhooks
      summary: List Webhooks
      description: Fetch webhook subscriptions configured for the institute.
      tags: [Configuration]
      x-source: https://docs.jodo.in/configuration/api/list-webhooks/
      responses:
        '200':
          description: Webhook subscriptions.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/GenericListResponse' }
        '401': { $ref: '#/components/responses/Unauthorized' }
    post:
      operationId: addWebhook
      summary: Add Webhook
      description: |
        Add or update the webhook destination for a specific event code. A webhook event can be
        subscribed to only one URL; calling this API again for the same event_code updates the
        existing subscription. After creation only secret_key, header_key and header_value can be updated.
      tags: [Configuration]
      x-source: https://docs.jodo.in/configuration/api/add-webhook/
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/AddWebhookRequest' }
      responses:
        '201':
          description: Webhook subscription created or updated.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/WebhookResponse' }
        '400': { $ref: '#/components/responses/BadRequest' }
  /api/v1/integrations/erp/webhooks/{webhook_id}:
    get:
      operationId: getWebhook
      summary: Get Webhook
      description: Fetch details for a webhook subscription identified by webhook_id.
      tags: [Configuration]
      x-source: https://docs.jodo.in/configuration/api/get-webhook/
      parameters:
        - $ref: '#/components/parameters/WebhookId'
      responses:
        '200':
          description: Webhook subscription detail.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/WebhookResponse' }
        '404': { $ref: '#/components/responses/NotFound' }
    delete:
      operationId: disableWebhook
      summary: Disable Webhook
      description: Disable a webhook subscription identified by webhook_id.
      tags: [Configuration]
      x-source: https://docs.jodo.in/configuration/api/disable-webhook/
      parameters:
        - $ref: '#/components/parameters/WebhookId'
      responses:
        '200':
          description: Webhook subscription disabled.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/StatusOnlyResponse' }
        '400': { $ref: '#/components/responses/BadRequest' }
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: >-
        All Jodo APIs are authenticated using HTTP Basic Auth. Jodo shares separate API keys and
        secrets for the UAT and production environments. Documented at
        https://docs.jodo.in/getting-started/authentication/ — keys and secrets must never be
        exposed in browsers, mobile apps or client-side code.
  parameters:
    RegistrationId:
      name: registration_id
      in: path
      required: true
      description: Unique registration ID for the user, returned by Register User.
      schema: { type: string }
    JodoStudentId:
      name: jodo_student_id
      in: path
      required: true
      description: Jodo student ID.
      schema: { type: string }
    OrderId:
      name: order_id
      in: path
      required: true
      description: Jodo Pay Order identifier returned by Create Pay Order or Create Payment Link.
      schema: { type: string }
    WebhookId:
      name: webhook_id
      in: path
      required: true
      description: Webhook subscription ID.
      schema: { type: string }
    CollectorCode:
      name: collector_code
      in: query
      required: false
      description: Branch code. Required when the institute is part of a group or has branch-specific configuration.
      schema: { type: string }
  responses:
    BadRequest:
      description: 'HUE00000 — Bad request. The request contains invalid or missing data.'
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
    BadRequestMAE:
      description: 'MAE00000 — Bad request error.'
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
    Unauthorized:
      description: Unauthorized. Authentication failed or credentials are invalid.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
    NotFound:
      description: 'HUE00001 — Resource not found.'
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
    StudentNotFound:
      description: 'MAE00001 — Student not found.'
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
  schemas:
    Error:
      type: object
      description: Jodo returns an HTTP status code with a user-facing message and a machine-readable error code.
      properties:
        status: { type: string, examples: [error] }
        code:
          type: string
          description: Machine-readable Jodo error code, e.g. HUE00000, HUE00001, MAE00000, MAE00001.
        message: { type: string, description: User-friendly explanation of the error. }
    StatusOnlyResponse:
      type: object
      description: Some write APIs return only a status envelope.
      properties:
        status: { type: string, examples: [success] }
    MessageResponse:
      type: object
      properties:
        status: { type: string, examples: [success] }
        message: { type: string, examples: ['Payment link cancelled successfully!'] }
    GenericListResponse:
      type: object
      description: Configuration list envelope. The docs do not enumerate the item shape for every configuration list.
      properties:
        status: { type: string, examples: [success] }
        data: { type: array, items: { type: object } }
    RegisterUserRequest:
      type: object
      required: [name, phone, email]
      properties:
        name: { type: string, description: Full name of the user. }
        phone: { type: string, description: 10-digit phone number. }
        email: { type: string, format: email, description: Email address. }
    RegisterUserResponse:
      type: object
      properties:
        status: { type: string, examples: [success] }
        data:
          type: object
          properties:
            registration_id: { type: string, description: Unique registration ID generated for the user. }
    AccessTokenResponse:
      type: object
      description: >-
        The access_token is used in the Jodo login redirect
        https://[base_url]/consumer/login-redirect?access_token=<access_token>, optionally with
        jodo_student_id, product_type (flex|pay|cred), callback_url and create_application.
      properties:
        status: { type: string, examples: [success] }
        data:
          type: object
          properties:
            access_token: { type: string, description: Access token used for the Jodo redirect. }
            expires_at: { type: string, format: date-time, description: Expiry time for the token. }
    Student:
      type: object
      required: [fullname, identifier, grade, new_admission, academic_year_start, academic_year_end, date_of_birth, primary_contact_name, primary_contact_number, primary_contact_email]
      properties:
        fullname: { type: string, description: The full name of the student. }
        identifier: { type: string, description: An identifier for the student assigned by the school (enrolment number). }
        custom_identifier: { type: string, description: Student custom identifier. }
        grade: { type: string, description: Unique grade identifier as shared between Jodo and the ERP provider. }
        new_admission: { type: boolean, description: Indicates if it is a new admission. }
        academic_year_start: { type: [string, integer], description: The start year of the academic year. }
        academic_year_end: { type: [string, integer], description: The end year of the academic year. }
        date_of_birth: { type: string, description: Date of birth in YYYY-MM-DD format. }
        primary_contact_name: { type: string, description: The name of the primary contact for the student. }
        primary_contact_number: { type: string, description: The primary contact number. }
        primary_contact_email: { type: string, format: email, description: The primary contact email. }
    FeeComponent:
      type: object
      required: [component_type, fee_amount]
      properties:
        component_type: { type: string, description: 'The type of fee component, e.g. TUITION_FEE, TRANSPORT_FEE.' }
        fee_amount: { type: number, description: The fee amount for the component. }
        discounts:
          type: array
          description: Discounts applied to this component.
          items: { $ref: '#/components/schemas/Discount' }
    Discount:
      type: object
      required: [discount_type, value]
      properties:
        discount_type: { type: string, description: One of the discount types as shared between Jodo and the ERP. }
        value: { type: integer, description: Discount amount in INR. }
    RegisterStudentRequest:
      type: object
      required: [student]
      properties:
        student: { $ref: '#/components/schemas/Student' }
        fee_components:
          type: array
          items: { $ref: '#/components/schemas/FeeComponent' }
        payments:
          type: array
          items: { $ref: '#/components/schemas/HistoricPayment' }
    HistoricPayment:
      type: object
      required: [amount, paid_at, mode, transaction_id, fee_components]
      properties:
        amount: { type: number, description: The payment amount. }
        paid_at: { type: string, format: date-time, description: The date and time of the payment in ISO 8601 format. }
        mode: { type: string, description: 'The payment mode, e.g. cash, credit card.' }
        transaction_id: { type: string, description: The unique transaction ID for the student. }
        settlement_utr: { type: string, description: The settlement UTR (Unique Transaction Reference), if applicable. }
        notes: { type: string, description: Additional notes or comments regarding the payment. }
        fee_components:
          type: array
          description: Fee components included in this payment.
          items: { $ref: '#/components/schemas/PaymentAllocation' }
    PaymentAllocation:
      type: object
      required: [component_type, amount]
      properties:
        component_type: { type: string, description: Fee component for which payment is made. }
        amount: { type: number, description: Amount paid for this fee component. }
    StudentResponse:
      type: object
      properties:
        status: { type: string, examples: [success] }
        data:
          type: object
          properties:
            fullname: { type: string }
            identifier: { type: string, description: Student identifier assigned by the school (enrolment number). }
            custom_identifier: { type: string }
            grade: { type: string, description: Unique grade identifier as shared between Jodo and the ERP provider. }
            new_admission: { type: boolean }
            academic_year_start: { type: integer }
            academic_year_end: { type: integer }
            date_of_birth: { type: string, description: Date of birth in YYYY-MM-DD format. }
            collector_code: { type: string, description: Institute code. }
            joining_year: { type: integer, description: Joining year; present if the student is a new admission. }
            primary_contact_name: { type: string }
            primary_contact_number: { type: string }
            primary_contact_email: { type: string, format: email }
            fee_summary:
              type: object
              properties:
                total_fee: { type: number, description: Total fee for the student. }
                total_discount: { type: number, description: Total discount for the student. }
    UpdateFeeRequest:
      type: object
      required: [fee_components]
      properties:
        fee_components:
          type: array
          items: { $ref: '#/components/schemas/FeeComponent' }
    ProductListResponse:
      type: object
      properties:
        status: { type: string, examples: [success] }
        data:
          type: array
          items:
            type: object
            properties:
              id: { type: integer }
              product_type: { type: string, enum: [flex, pay, cred] }
              status: { type: string, examples: [pending] }
    AddPaymentRequest:
      type: object
      required: [amount, paid_at, fee_components]
      properties:
        amount: { type: number, description: Total amount paid. }
        paid_at: { type: string, format: date-time, description: Paid date and time in ISO 8601 format. }
        mode: { type: string, description: Mode of payment. Defaults to others if not provided. }
        transaction_id: { type: string, description: Unique transaction ID from your system. Reused as the path key when cancelling the payment. }
        settlement_utr: { type: string, description: Settlement UTR, if already available. }
        notes: { type: string, description: Payment notes. }
        fee_components:
          type: array
          description: Fee component level payment allocation.
          items: { $ref: '#/components/schemas/PaymentAllocation' }
    PaymentListResponse:
      type: object
      properties:
        status: { type: string, examples: [success] }
        data: { type: array, items: { type: object } }
    ManageFlexPlanRequest:
      type: object
      required: [payment_schedule]
      properties:
        payment_schedule:
          type: array
          description: Instalments to configure for the student.
          items:
            type: object
            required: [due_date, details]
            properties:
              due_date: { type: string, description: Instalment due date in YYYY-MM-DD format. }
              details:
                type: array
                description: Fee component split for the instalment.
                items:
                  type: object
                  required: [component_type, amount]
                  properties:
                    component_type: { type: string, description: Fee component code. }
                    amount: { type: number, description: Amount for the fee component. }
                    is_downpayment: { type: boolean, description: Set to true when the component is part of a downpayment instalment. }
    FlexScheduleResponse:
      type: object
      properties:
        status: { type: string, examples: [success] }
        data: { type: object, description: Flex payment schedule configured for the student. }
    PayOrderBase:
      type: object
      required: [name, phone, email, details]
      properties:
        name: { type: string, description: Name of the payer. }
        phone: { type: string, description: Phone number of the payer. }
        email: { type: string, format: email, description: Email address of the payer. }
        student_name: { type: string, description: Student name, if relevant. Does not require an existing Jodo student record. }
        grade: { type: string, description: Grade identifier shared between Jodo and the ERP provider. }
        date_of_birth: { type: string }
        identifier: { type: string, description: Student identifier assigned by the institute, if available. }
        new_admission: { type: boolean }
        custom_identifier: { type: string }
        academic_year_start: { type: integer }
        academic_year_end: { type: integer }
        details:
          type: array
          description: Payment line items.
          items: { $ref: '#/components/schemas/OrderLineItem' }
        notes:
          type: array
          description: 'Key-value metadata, for example ERP reference IDs.'
          items: { $ref: '#/components/schemas/Note' }
    OrderLineItem:
      type: object
      required: [component_type, amount]
      properties:
        component_type: { type: string, description: 'Payment detail type, such as Event Fee or Payable Amount.' }
        amount: { type: number, description: Amount to be collected for the line item. }
        settlement_utr: { type: string, description: Settlement UTR, if settled. }
        settled_at: { type: string, format: date-time, description: Settlement time, if settled. }
    Note:
      type: object
      properties:
        key: { type: string, examples: [erp_reference_id] }
        value: { type: string, examples: [REF123] }
    CreatePayOrderRequest:
      allOf:
        - $ref: '#/components/schemas/PayOrderBase'
        - type: object
          properties:
            callback_url: { type: string, format: uri, description: URL used to redirect the payer after checkout. }
    CreatePaymentLinkRequest:
      allOf:
        - $ref: '#/components/schemas/PayOrderBase'
        - type: object
          properties:
            expires_at: { type: string, format: date-time, description: Optional expiry date and time in ISO 8601 format. }
    OrderCreatedResponse:
      type: object
      properties:
        status: { type: string, examples: [success] }
        data:
          type: object
          properties:
            order_id: { type: string, description: Unique Jodo Pay Order identifier. }
            redirect_url: { type: string, format: uri, description: Hosted Jodo checkout URL for the payer. }
    OrderResponse:
      type: object
      properties:
        status: { type: string, examples: [success] }
        data: { $ref: '#/components/schemas/Order' }
    PaymentLinkResponse:
      type: object
      properties:
        status: { type: string, examples: [success] }
        data:
          allOf:
            - $ref: '#/components/schemas/Order'
            - type: object
              properties:
                expires_at: { type: string, format: date-time, description: Payment link expiry date and time. }
    Order:
      type: object
      properties:
        id: { type: string, description: Order ID. }
        name: { type: string }
        phone: { type: string }
        email: { type: string, format: email }
        identifier: { type: string }
        student_name: { type: string }
        grade: { type: string }
        stream: { type: string, description: Student stream name. }
        academic_year_start: { type: integer }
        academic_year_end: { type: integer }
        new_admission: { type: boolean }
        date_of_birth: { type: string }
        custom_identifier: { type: string }
        transaction_id: { type: string, description: Transaction ID for the payment. }
        paid_at: { type: string, format: date-time, description: Time when payment was completed. }
        status:
          type: string
          description: 'Current status. Pay Orders: paid, unpaid. Payment links: paid, unpaid, expired, cancelled.'
        details:
          type: array
          items: { $ref: '#/components/schemas/OrderLineItem' }
        notes:
          type: array
          items: { $ref: '#/components/schemas/Note' }
    AddWebhookRequest:
      type: object
      required: [event_code, url, failure_notification_email]
      properties:
        collector_code: { type: string, description: Branch code. Required if the institute has more than one branch. }
        event_code: { type: string, description: 'Webhook event code, e.g. cred.loan.final_approved.' }
        url: { type: string, format: uri, description: Destination URL where Jodo sends POST requests when the event is triggered. }
        failure_notification_email: { type: string, description: Comma-separated email list for failure notifications. }
        secret_key: { type: string, description: Secret key used to generate the X-Jodo-Signature HMAC SHA-256 signature. }
        header_key: { type: string, description: Custom header key sent with webhook requests. }
        header_value: { type: string, description: Custom header value sent with webhook requests. }
    WebhookResponse:
      type: object
      properties:
        status: { type: string, examples: [success] }
        data:
          type: object
          properties:
            id: { type: string, description: Webhook subscription ID. }
            event_code: { type: string }
            failure_notification_email: { type: string }
            url: { type: string, format: uri }