VirtualAccount

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/curlec/json-schema/curlec-virtual-account-schema.json",
  "title": "VirtualAccount",
  "description": "A virtual bank account or VPA that accepts NEFT/RTGS/IMPS/UPI payments (Smart Collect). Each payment creates a BankTransfer entity. Auto-closes after 90 days of inactivity. Prefix: va_",
  "x-generated": "2026-11-04",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/curlec-virtual-accounts-api-openapi.yml#/components/schemas/VirtualAccount",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Virtual account ID. Prefix: va_"
    },
    "name": {
      "type": "string",
      "description": "Display name of the virtual account."
    },
    "entity": {
      "type": "string",
      "enum": [
        "virtual_account"
      ]
    },
    "description": {
      "type": "string",
      "description": "Purpose or description of the virtual account."
    },
    "amount_expected": {
      "type": "integer",
      "description": "Expected payment amount in paise. 0 means any amount is accepted."
    },
    "amount_paid": {
      "type": "integer",
      "description": "Total amount received so far in paise."
    },
    "status": {
      "type": "string",
      "enum": [
        "active",
        "closed"
      ],
      "description": "active = accepting payments; closed = no longer accepting payments."
    },
    "receivers": {
      "type": "array",
      "description": "Payment receivers assigned to this virtual account. Can include bank_account (ba_*) and/or vpa (vpa_*) receivers.",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Receiver ID. Prefix: ba_ for bank account, vpa_ for VPA."
          },
          "entity": {
            "type": "string",
            "enum": [
              "bank_account",
              "vpa"
            ]
          },
          "ifsc": {
            "type": "string",
            "description": "IFSC code (bank accounts only)."
          },
          "bank_name": {
            "type": "string",
            "description": "Bank name (bank accounts only)."
          },
          "name": {
            "type": "string",
            "description": "Account holder name (bank accounts) or VPA address (VPAs)."
          },
          "notes": {
            "$ref": "#/$defs/Notes"
          },
          "account_number": {
            "type": "string",
            "description": "Virtual account number (bank accounts only)."
          },
          "username": {
            "type": "string",
            "description": "UPI username part of the VPA (VPAs only)."
          },
          "handle": {
            "type": "string",
            "description": "UPI handle (e.g., razorpay) (VPAs only)."
          },
          "flow": {
            "type": "string",
            "enum": [
              "upi_qr"
            ],
            "description": "Flow type for VPA receivers."
          }
        }
      }
    },
    "close_by": {
      "type": "integer",
      "description": "Unix timestamp by which the account will auto-close. Maximum value: 2147483647."
    },
    "closed_at": {
      "type": "integer",
      "description": "Unix timestamp when the account was closed."
    },
    "customer_id": {
      "type": "string",
      "description": "Customer ID linked to this virtual account (cust_*)."
    },
    "notes": {
      "$ref": "#/$defs/Notes"
    },
    "created_at": {
      "type": "integer"
    }
  },
  "$defs": {
    "Notes": {
      "type": "object",
      "description": "Key-value pairs for storing custom metadata. Maximum 15 pairs. Each key and value must not exceed 256 characters.",
      "additionalProperties": {
        "type": "string"
      },
      "maxProperties": 15
    }
  }
}