openapi: 3.1.0
info:
  title: PyDart Pay v2.0 — Multi-PA Payment Orchestration & Partner API
  version: 2.0.0
  summary: RBI-compliant TSP payment link, Hosted Checkout, 19-app UPI Intent, Sub-Merchant Linked Account, Idempotent Refund, and Double-Entry Prepaid Credits API by Pydart Intelli Corp Private Limited (100% CoFee v1/v2 wire-compatible).
  contact:
    name: PyDart Engineering & Partner Support
    email: api-support@pydart.com
    url: https://pydart.com/developers
servers:
  - url: https://pydart.com/api/v1
    description: Production Edge & Clearing API (India D1 + Multi-PA Smart Router)
security:
  - PartnerApiKey: []
components:
  securitySchemes:
    PartnerApiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: Scoped live (`sk_live_...`) or sandbox (`sk_test_...`) Partner API key (stored solely as SHA-256 digest). Also accepts `Authorization: Bearer <key>`.
  schemas:
    CustomerDetails:
      type: object
      required: [name, mobile]
      properties:
        name:
          type: string
          example: Aarav Nair
        mobile:
          type: string
          example: "+919847012345"
        email:
          type: string
          format: email
        customer_reference_id:
          type: string
          example: STU-2026-418
        is_minor:
          type: boolean
          default: false
        guardian_consent_verified:
          type: boolean
          default: false
    CreatePaymentOrderRequest:
      type: object
      required: [merchant_order_id, customer_details]
      properties:
        branch_id:
          type: string
          example: br_smartup_kochi
        amount_paise:
          type: integer
          minimum: 200
          example: 2450000
        amount:
          type: number
          minimum: 2
          description: CoFee v1/v2 compatible Rupee amount (converted deterministically to integer paise).
          example: 24500
        currency:
          type: string
          default: INR
          enum: [INR, AED, SAR, QAR, KWD, OMR, BHD, USD, EUR, GBP]
        merchant_order_id:
          type: string
          example: INV-202611-00418
        order_purpose:
          type: string
          example: Grade 10 Tuition — Term 2
        redirect_url:
          type: string
          format: uri
        customer_details:
          $ref: "#/components/schemas/CustomerDetails"
paths:
  /payment-orders:
    post:
      summary: Create Idempotent Payment Order (PyDart Native v1)
      parameters:
        - in: header
          name: Idempotency-Key
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreatePaymentOrderRequest"
      responses:
        "201":
          description: Smart-routed payment order created.
        "200":
          description: Idempotent replay of existing order.
        "402":
          description: Prepaid Platform Credits and Grace Overdraft buffer exhausted.
    get:
      summary: List Paginated Payment Orders
      responses:
        "200":
          description: Bounded order list (`limit <= 100`).
  /payment-order:
    post:
      summary: Create Payment Order (100% CoFee v1 Drop-In Alias)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreatePaymentOrderRequest"
      responses:
        "200":
          description: Created or returned active CoFee-compatible order payload.
  /payment-order/{order_id}:
    get:
      summary: Fetch Authoritative Order Status & Bank UTR
      parameters:
        - in: path
          name: order_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Order state, receipt number, and settlement UTR.
  /payment-order/by-reference/{reference_id}:
    get:
      summary: Lookup Order by Merchant Invoice Reference
      parameters:
        - in: path
          name: reference_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Matching order details.
  /payment-order/{order_id}/disable:
    patch:
      summary: Cancel / Expire Unpaid Payment Link
      parameters:
        - in: path
          name: order_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Order transitioned to `expired`.
  /refunds:
    post:
      summary: Issue Idempotent Full or Partial Refund
      parameters:
        - in: header
          name: Idempotency-Key
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Refund processed atomically.
  /accounts:
    post:
      summary: Provision Sub-Merchant Linked Settlement Account
      responses:
        "201":
          description: Linked settlement MID registered.
  /wallet/balance:
    get:
      summary: Query Closed B2B Prepaid Credits & AutoCollect VAN
      responses:
        "200":
          description: Current paise balance, grace overdraft buffer, and zero-fee NEFT top-up VAN.
