openapi: 3.1.0
info:
  title: PyDart Pay Partner & Payment Orchestration API
  version: 1.0.0
  summary: RBI-compliant TSP payment link, embedded checkout, sub-merchant KYB, and prepaid platform credits API by Pydart Intelli Corp Private Limited (100% wire-compatible with CoFee v1).
  contact:
    name: PyDart Engineering & Partner Support
    email: api-support@pydart.com
    url: https://pydart.com/developers
servers:
  - url: https://partner-api.pydart.com/v1
    description: Production Partner API (Mumbai ap-south-1 — RBI Data Localized)
  - url: https://sandbox-api.pydart.com/v1
    description: Sandbox Partner API
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 as SHA-256 digest).
  schemas:
    CustomerDetails:
      type: object
      required: [name, mobile]
      properties:
        name:
          type: string
          example: Aarav Nair
        mobile:
          type: string
          example: "+919847012345"
        email:
          type: string
          format: email
          example: parent@smartuplearning.online
        customer_reference_id:
          type: string
          maxLength: 128
          example: stu_smartup_1042
    CreatePaymentOrderRequest:
      type: object
      required: [branch_id, merchant_order_id, customer_details]
      properties:
        branch_id:
          type: string
          example: br_smartup_kochi
        amount_paise:
          type: integer
          minimum: 200
          description: Exact 64-bit integer amount in paise (preferred over decimal `amount`).
          example: 4850000
        amount:
          type: number
          minimum: 2
          description: CoFee v1 compatible Rupee amount (converted deterministically to integer paise if `amount_paise` omitted).
          example: 48500
        currency:
          type: string
          default: INR
          enum: [INR, AED, SAR, QAR, KWD, OMR, BHD, USD]
        merchant_order_id:
          type: string
          example: INV-202611-00418
        order_purpose:
          type: string
          maxLength: 255
          example: Grade 10 Tuition Fee — Term 2
        redirect_url:
          type: string
          format: uri
        notify_customer:
          type: boolean
          default: false
        send_receipt_to_customer:
          type: boolean
          default: true
        customer_details:
          $ref: "#/components/schemas/CustomerDetails"
    PaymentOrderResponse:
      type: object
      required: [status, data]
      properties:
        status:
          type: string
          enum: [SUCCESS, ERROR]
        data:
          type: object
          properties:
            order_id:
              type: string
              example: ord_01JD9K8M2P4Q6R8S
            branch_id:
              type: string
            merchant_order_id:
              type: string
            amount:
              type: string
              example: "48500.00"
            amount_paise:
              type: integer
              example: 4850000
            currency:
              type: string
              example: INR
            payment_link:
              type: string
              format: uri
              example: https://pay.pydart.com/p/ord_01JD9K8M2P4Q6R8S
            order_status:
              type: string
              enum: [processing, paid, failed, expired, refunded]
            created_at:
              type: string
              format: date-time
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: Created payment order routed to Cashfree Embedded MID or Razorpay Partner MID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaymentOrderResponse"
        "402":
          description: Prepaid Platform Credits and Grace Overdraft buffer exhausted.
  /payment-order:
    post:
      summary: Create Payment Order (CoFee v1 Drop-In Alias)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreatePaymentOrderRequest"
      responses:
        "200":
          description: Order created or active session reused.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaymentOrderResponse"
  /payment-order/{order_id}:
    get:
      summary: Retrieve Authoritative Order Status
      parameters:
        - in: path
          name: order_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Current order state and UTR details.
  /wallet/balance:
    get:
      summary: Query Closed B2B Prepaid Platform Credits Balance & Dedicated AutoCollect Top-Up VAN
      responses:
        "200":
          description: Current paise balance, grace overdraft limit, and zero-fee NEFT/UPI top-up coordinates.
