openapi: 3.1.1
info:
  title: UBC Network Extensions (v1)
  version: 1.0.0
  x-profile-id: profiles/ubc-extensions/v1/ubc-network
  description: >
    UBC Network-specific schema extensions for India. These attributes extend
    the core Beckn Protocol schemas with India-specific constructs like UPI
    transaction IDs, buyer VPAs, and other network-specific features.
    
    This schema is hosted at:
    https://raw.githubusercontent.com/bhim/ubc-tsd/main/beckn-schemas/UBCExtensions/v1/
  contact:
    name: UBC Network
    url: https://github.com/bhim/ubc-tsd
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

components:
  schemas:
    ########################################################################
    # BUYER.ATTRIBUTES — BuyerUPI
    ########################################################################
    BuyerUPI:
      type: object
      required: ["vpa"]
      additionalProperties: false
      x-jsonld:
        "@context": ./context.jsonld
        "@type": BuyerUPI
      description: >
        India-specific buyer payment information for UBC network.
        Attached to Buyer.buyerAttributes to provide UPI/VPA details
        for refunds and buyer identification.
      properties:
        vpa:
          type: [string, "null"]
          description: Virtual Payment Address (UPI ID) of the buyer for refunds.
          example: "ravikumar@upi"
          x-jsonld: { "@id": vpa }

    ########################################################################
    # PAYMENT.ATTRIBUTES — UBCPaymentAttributes
    ########################################################################
    UBCPaymentAttributes:
      type: object
      additionalProperties: false
      x-jsonld:
        "@context": ./context.jsonld
        "@type": UBCPaymentAttributes
      description: >
        UBC Network-specific payment attributes. Extends PaymentSettlement
        with India-specific fields like UPI transaction IDs. Attached to
        Payment.paymentAttributes alongside settlementAccounts.
      properties:
        upiTransactionId:
          type: [string, "null"]
          description: UPI transaction reference ID returned by the payment gateway.
          example: "UPI123456789012"
          x-jsonld: { "@id": upiTransactionId }
        settlementAccounts:
          type: array
          description: List of settlement details (Bank, VPA, etc.) for beneficiaries.
          items:
            $ref: '#/components/schemas/SettlementAccount'
          x-jsonld: { "@id": settlementAccounts }

    ########################################################################
    # SETTLEMENT ACCOUNT
    ########################################################################
    SettlementAccount:
      type: object
      additionalProperties: false
      description: Bank or UPI account details for settlement.
      properties:
        beneficiaryId:
          type: string
          description: Identifier for the beneficiary (BAP/BPP domain).
          example: "example-bap.com"
        accountHolderName:
          type: string
          description: Account holder name.
          example: "Example BAP Solutions Pvt Ltd"
        accountNumber:
          type: string
          description: Bank account number.
          example: "9876543210123"
        ifscCode:
          type: string
          description: Bank IFSC code.
          example: "HDFC0009876"
        bankName:
          type: string
          description: Name of the bank.
          example: "HDFC Bank"
        vpa:
          type: string
          description: Virtual Payment Address (UPI ID) for settlement.
          example: "example-bap@paytm"

    ########################################################################
    # INVOICE — UBCInvoice
    ########################################################################
    UBCInvoice:
      type: object
      required: ["invoiceId"]
      additionalProperties: false
      x-jsonld:
        "@context": ./context.jsonld
        "@type": UBCInvoice
      description: >
        UBC Network-specific invoice object. Carried as the value of
        beckn:orderAttributes on the Order when the network needs to
        attach full invoice details (totals, invoice URL, etc.) alongside
        the order.
      properties:
        invoiceId:
          type: string
          description: Stable invoice identifier (system ID).
          example: "invoice-ev-charging-001"
          x-jsonld: { "@id": "schema:identifier" }
        totals:
          type: object
          description: Invoice total amount.
          properties:
            currency:
              type: string
              description: ISO 4217 currency code.
              example: "INR"
            value:
              type: number
              description: Total invoice amount.
              example: 143.95
          x-jsonld: { "@id": "schema:totalPrice" }
        invoiceAttributes:
          $ref: '#/components/schemas/UBCInvoiceAttributes'
          x-jsonld: { "@id": "ubc:invoiceAttributes" }

    ########################################################################
    # INVOICE.ATTRIBUTES — UBCInvoiceAttributes
    ########################################################################
    UBCInvoiceAttributes:
      type: object
      required: ["invoiceUrl"]
      additionalProperties: false
      x-jsonld:
        "@context": ./context.jsonld
        "@type": UBCInvoiceAttributes
      description: >
        UBC Network-specific invoice attributes. Attached to
        Invoice.invoiceAttributes to provide a link to the digital
        invoice or charging session fee breakdown.
      properties:
        "@type":
          type: string
          description: JSON-LD type discriminator (e.g. "UBCInvoiceAttributes").
          example: "UBCInvoiceAttributes"
        invoiceUrl:
          type: string
          format: uri
          description: URL to the digital invoice or charging session fee breakdown.
          example: "https://example-bpp.com/charging/session/order-ev-charging-001/fee"
          x-jsonld: { "@id": invoiceUrl }

    ########################################################################
    # SUPPORT.FEEDBACK — SupportFeedback
    ########################################################################
    SupportFeedback:
      type: object
      additionalProperties: false
      x-jsonld:
        "@context": ./context.jsonld
        "@type": SupportFeedback
      description: >
        UBC Network-specific support feedback and grievance tracking.
        Attached to the support message to provide grievance details,
        observability tags, and ticket lifecycle status.
      properties:
        comments:
          type: string
          description: Free-text description of the grievance or support request.
          example: "Charging session stopped at 40% but I was billed full amount"
          x-jsonld: { "@id": comments }
        tags:
          type: array
          description: Tags for observability and categorization of the grievance.
          items:
            type: string
          example: ["charging-interrupted", "billing-dispute"]
          x-jsonld: { "@id": tags }
        supportStatus:
          type: string
          description: Current lifecycle status of the support ticket.
          enum:
            - OPEN
            - ACKNOWLEDGED
            - IN_PROGRESS
            - RESOLVED
            - CLOSED
            - ESCALATED
          example: "OPEN"
          x-jsonld: { "@id": supportStatus }