{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://www.aggreghiamoci.online/gateway/api/schemas/payment-response.json",
  "title": "Aggreghiamoci Common Gateway Payment Response",
  "description": "Schema documentale della futura risposta pagamento normalizzata. Non abilita incassi e non invoca provider.",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "ok",
    "gatewayTransactionId",
    "state",
    "provider",
    "providerMode",
    "livePaymentsEnabled",
    "realProviderCallsEnabled"
  ],
  "properties": {
    "ok": {
      "type": "boolean"
    },
    "gatewayTransactionId": {
      "type": ["string", "null"],
      "description": "Identificativo transazione interno del gateway comune.",
      "examples": ["gw_agg_20260519_000001"]
    },
    "state": {
      "type": "string",
      "enum": [
        "draft",
        "pending_provider",
        "authorized",
        "captured",
        "paid",
        "failed",
        "cancelled",
        "expired",
        "refunded",
        "disputed",
        "live_disabled"
      ],
      "examples": ["pending_provider", "live_disabled"]
    },
    "provider": {
      "type": "string",
      "enum": ["nexi"]
    },
    "providerMode": {
      "type": "string",
      "enum": ["mock", "sandbox", "live_disabled", "live"]
    },
    "redirectUrl": {
      "type": ["string", "null"],
      "description": "URL di redirect checkout, se disponibile. In live_disabled resta null."
    },
    "expiresAt": {
      "type": ["string", "null"],
      "format": "date-time"
    },
    "sourceModule": {
      "type": ["string", "null"],
      "examples": ["associativa"]
    },
    "sourceRequestId": {
      "type": ["string", "null"],
      "examples": ["AGG-20260519-054130-E340"]
    },
    "amount": {
      "type": ["string", "null"],
      "pattern": "^[0-9]+\\.[0-9]{2}$",
      "examples": ["25.00"]
    },
    "currency": {
      "type": ["string", "null"],
      "enum": ["EUR", null]
    },
    "livePaymentsEnabled": {
      "type": "boolean",
      "const": false
    },
    "realProviderCallsEnabled": {
      "type": "boolean",
      "const": false
    },
    "message": {
      "type": ["string", "null"]
    },
    "error": {
      "type": ["string", "null"],
      "examples": ["payment_gateway_live_disabled"]
    }
  },
  "x-safety": {
    "mode": "documentation_only",
    "live_payments_enabled": false,
    "real_provider_calls_enabled": false,
    "provider_target": "nexi",
    "proxy_required": true
  }
}