{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://www.aggreghiamoci.online/gateway/api/schemas/payment-request.json",
  "title": "Aggreghiamoci Common Gateway Payment Request",
  "description": "Schema documentale della futura richiesta pagamento normalizzata. Non abilita incassi e non invoca provider.",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "sourceModule",
    "sourceRequestId",
    "operationType",
    "amount",
    "currency",
    "description",
    "returnUrls"
  ],
  "properties": {
    "sourceModule": {
      "type": "string",
      "examples": ["associativa"]
    },
    "sourceRequestId": {
      "type": "string",
      "description": "Identificativo pratica del verticale chiamante.",
      "examples": ["AGG-20260519-054130-E340"]
    },
    "operationType": {
      "type": "string",
      "examples": ["membership_fee_checkout"]
    },
    "subject": {
      "type": ["string", "null"],
      "description": "Subject SSO normalizzato, se disponibile."
    },
    "organizationId": {
      "type": ["string", "null"],
      "examples": ["aggreghiamoci-online"]
    },
    "serviceKey": {
      "type": ["string", "null"],
      "examples": ["membership-2026"]
    },
    "amount": {
      "type": "string",
      "pattern": "^[0-9]+\\.[0-9]{2}$",
      "examples": ["25.00"]
    },
    "currency": {
      "type": "string",
      "enum": ["EUR"]
    },
    "description": {
      "type": "string",
      "examples": ["Quota associativa 2026 - Socio ordinario"]
    },
    "returnUrls": {
      "type": "object",
      "additionalProperties": false,
      "required": ["success", "cancel", "pending"],
      "properties": {
        "success": {"type": "string"},
        "cancel": {"type": "string"},
        "pending": {"type": "string"}
      }
    },
    "metadata": {
      "type": "object",
      "additionalProperties": {
        "type": ["string", "number", "boolean", "null"]
      },
      "examples": [{
        "enrollmentCode": "AGG-20260519-054130-E340",
        "membershipYear": "2026",
        "membershipType": "socio-ordinario"
      }]
    }
  },
  "x-safety": {
    "mode": "documentation_only",
    "live_payments_enabled": false,
    "real_provider_calls_enabled": false,
    "provider_target": "nexi",
    "proxy_required": true
  }
}