{
  "openapi": "3.1.0",
  "info": {
    "title": "CamContent Embedded Livecam – Partner Callback",
    "version": "1.0.0",
    "description": "Integration contract for a partner-operated HTTPS backend. One authenticated credential per system. Monetary operations apply atomically to one wallet and reservation."
  },
  "paths": {
    "/verify": {
      "post": {
        "operationId": "verify",
        "summary": "Check account and age eligibility without a debit",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "description": "Opaque identifier. Preserve exactly.",
              "minLength": 1,
              "maxLength": 128
            },
            "description": "Stable logical operation ID. Repeated identical requests return the original result, including after expiry. Reuse with a different payload returns 409."
          }
        ],
        "security": [
          {
            "partnerCallback": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Verify"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Authenticated final result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Access"
                }
              }
            }
          },
          "401": {
            "description": "Callback authentication failed"
          },
          "403": {
            "description": "Partner denies this operation"
          },
          "409": {
            "description": "Idempotency conflict or invalid reservation state"
          },
          "422": {
            "description": "Insufficient funds or rejected terms"
          },
          "503": {
            "description": "Outcome unknown. Reconcile with the same operation ID."
          }
        }
      }
    },
    "/preauthorize": {
      "post": {
        "operationId": "preauthorize",
        "summary": "Reserve the specified coins for one priced service interval",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "description": "Opaque identifier. Preserve exactly.",
              "minLength": 1,
              "maxLength": 128
            },
            "description": "Stable logical operation ID. Repeated identical requests return the original result, including after expiry. Reuse with a different payload returns 409."
          }
        ],
        "security": [
          {
            "partnerCallback": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Reserve"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Authenticated final result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Hold"
                }
              }
            }
          },
          "401": {
            "description": "Callback authentication failed"
          },
          "403": {
            "description": "Partner denies this operation"
          },
          "409": {
            "description": "Idempotency conflict or invalid reservation state"
          },
          "422": {
            "description": "Insufficient funds or rejected terms"
          },
          "503": {
            "description": "Outcome unknown. Reconcile with the same operation ID."
          }
        }
      }
    },
    "/collect": {
      "post": {
        "operationId": "collect",
        "summary": "Capture the confirmed consumption against its reservation",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "description": "Opaque identifier. Preserve exactly.",
              "minLength": 1,
              "maxLength": 128
            },
            "description": "Stable logical operation ID. Repeated identical requests return the original result, including after expiry. Reuse with a different payload returns 409."
          }
        ],
        "security": [
          {
            "partnerCallback": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Collect"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Authenticated final result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Receipt"
                }
              }
            }
          },
          "401": {
            "description": "Callback authentication failed"
          },
          "403": {
            "description": "Partner denies this operation"
          },
          "409": {
            "description": "Idempotency conflict or invalid reservation state"
          },
          "422": {
            "description": "Insufficient funds or rejected terms"
          },
          "503": {
            "description": "Outcome unknown. Reconcile with the same operation ID."
          }
        },
        "description": "Charge measured usage at the confirmed tariff. A partial interval is charged proportionally. Guppy carries fractional coin cents across adjacent intervals at the same tariff; any final sub-cent fraction is rounded down. The capture may not exceed the hold."
      }
    },
    "/removePreauthorize": {
      "post": {
        "operationId": "removePreauthorize",
        "summary": "Release the unused balance of the reservation",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "description": "Opaque identifier. Preserve exactly.",
              "minLength": 1,
              "maxLength": 128
            },
            "description": "Stable logical operation ID. Repeated identical requests return the original result, including after expiry. Reuse with a different payload returns 409."
          }
        ],
        "security": [
          {
            "partnerCallback": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Release"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Authenticated final result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Receipt"
                }
              }
            }
          },
          "401": {
            "description": "Callback authentication failed"
          },
          "403": {
            "description": "Partner denies this operation"
          },
          "409": {
            "description": "Idempotency conflict or invalid reservation state"
          },
          "422": {
            "description": "Insufficient funds or rejected terms"
          },
          "503": {
            "description": "Outcome unknown. Reconcile with the same operation ID."
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "partnerCallback": {
        "type": "http",
        "scheme": "bearer",
        "description": "Partner-specific server credential, separate from the CamContent session API key."
      }
    },
    "schemas": {
      "Verify": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "systemId",
          "sessionId",
          "userId",
          "producerId"
        ],
        "properties": {
          "systemId": {
            "type": "string",
            "description": "Opaque identifier. Preserve exactly.",
            "minLength": 1,
            "maxLength": 128
          },
          "sessionId": {
            "type": "string",
            "description": "Opaque identifier. Preserve exactly.",
            "minLength": 1,
            "maxLength": 128
          },
          "userId": {
            "type": "string",
            "description": "Opaque identifier. Preserve exactly.",
            "minLength": 1,
            "maxLength": 128
          },
          "producerId": {
            "type": "string",
            "description": "Opaque identifier. Preserve exactly.",
            "minLength": 1,
            "maxLength": 128
          }
        }
      },
      "Access": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "decision",
          "expiresAt"
        ],
        "properties": {
          "decision": {
            "enum": [
              "allowed",
              "login_required",
              "age_verification_required",
              "blocked"
            ],
            "type": "string"
          },
          "expiresAt": {
            "type": "string",
            "format": "date-time",
            "description": "UTC expiry of this decision"
          },
          "ageEvidence": {
            "type": "object",
            "description": "Separate age evidence for systems with explicitly approved partner age verification. Valid only for the same system, session and user.",
            "additionalProperties": false,
            "required": [
              "systemId",
              "sessionId",
              "userId",
              "evidenceId",
              "status",
              "expiresAt"
            ],
            "properties": {
              "systemId": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128
              },
              "sessionId": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128
              },
              "userId": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128
              },
              "evidenceId": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128
              },
              "status": {
                "type": "string",
                "enum": [
                  "verified"
                ]
              },
              "expiresAt": {
                "type": "string",
                "format": "date-time"
              }
            }
          }
        },
        "examples": [
          {
            "decision": "allowed",
            "expiresAt": "2030-01-10T12:01:00Z",
            "ageEvidence": {
              "systemId": "level5media",
              "sessionId": "8feb11b29d6a4212af231b4c011735ba",
              "userId": "veegaz-user-example",
              "evidenceId": "avs-example-019",
              "status": "verified",
              "expiresAt": "2030-01-10T12:00:45Z"
            }
          },
          {
            "decision": "age_verification_required",
            "expiresAt": "2030-01-10T12:00:45Z"
          }
        ]
      },
      "Reserve": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "systemId",
          "sessionId",
          "userId",
          "producerId",
          "tariffId",
          "amountCoinCents"
        ],
        "properties": {
          "systemId": {
            "type": "string",
            "description": "Opaque identifier. Preserve exactly.",
            "minLength": 1,
            "maxLength": 128
          },
          "sessionId": {
            "type": "string",
            "description": "Opaque identifier. Preserve exactly.",
            "minLength": 1,
            "maxLength": 128
          },
          "userId": {
            "type": "string",
            "description": "Opaque identifier. Preserve exactly.",
            "minLength": 1,
            "maxLength": 128
          },
          "producerId": {
            "type": "string",
            "description": "Opaque identifier. Preserve exactly.",
            "minLength": 1,
            "maxLength": 128
          },
          "tariffId": {
            "type": "string",
            "description": "Opaque identifier. Preserve exactly.",
            "minLength": 1,
            "maxLength": 128
          },
          "amountCoinCents": {
            "type": "integer",
            "minimum": 0,
            "maximum": 2147483647,
            "description": "Hundredths of a partner coin. 150 represents 1.50 coins."
          }
        }
      },
      "Hold": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "reservationId",
          "amountCoinCents",
          "expiresAt"
        ],
        "properties": {
          "reservationId": {
            "type": "string",
            "description": "Opaque identifier. Preserve exactly.",
            "minLength": 1,
            "maxLength": 128
          },
          "expiresAt": {
            "type": "string",
            "format": "date-time",
            "description": "UTC expiry of this decision"
          },
          "amountCoinCents": {
            "type": "integer",
            "minimum": 0,
            "maximum": 2147483647,
            "description": "Hundredths of a partner coin. 150 represents 1.50 coins."
          }
        }
      },
      "Collect": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "systemId",
          "sessionId",
          "userId",
          "producerId",
          "tariffId",
          "amountCoinCents",
          "reservationId",
          "durationMs"
        ],
        "properties": {
          "systemId": {
            "type": "string",
            "description": "Opaque identifier. Preserve exactly.",
            "minLength": 1,
            "maxLength": 128
          },
          "sessionId": {
            "type": "string",
            "description": "Opaque identifier. Preserve exactly.",
            "minLength": 1,
            "maxLength": 128
          },
          "userId": {
            "type": "string",
            "description": "Opaque identifier. Preserve exactly.",
            "minLength": 1,
            "maxLength": 128
          },
          "producerId": {
            "type": "string",
            "description": "Opaque identifier. Preserve exactly.",
            "minLength": 1,
            "maxLength": 128
          },
          "tariffId": {
            "type": "string",
            "description": "Opaque identifier. Preserve exactly.",
            "minLength": 1,
            "maxLength": 128
          },
          "reservationId": {
            "type": "string",
            "description": "Opaque identifier. Preserve exactly.",
            "minLength": 1,
            "maxLength": 128
          },
          "amountCoinCents": {
            "type": "integer",
            "minimum": 0,
            "maximum": 2147483647,
            "description": "Hundredths of a partner coin. 150 represents 1.50 coins."
          },
          "durationMs": {
            "type": "integer",
            "minimum": 0,
            "maximum": 2147483647,
            "description": "Elapsed billable milliseconds measured by the Guppy server. Requests repeated with the same operation ID contain identical usage."
          }
        }
      },
      "Release": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "systemId",
          "sessionId",
          "userId",
          "producerId",
          "reservationId",
          "amountCoinCents"
        ],
        "properties": {
          "systemId": {
            "type": "string",
            "description": "Opaque identifier. Preserve exactly.",
            "minLength": 1,
            "maxLength": 128
          },
          "sessionId": {
            "type": "string",
            "description": "Opaque identifier. Preserve exactly.",
            "minLength": 1,
            "maxLength": 128
          },
          "userId": {
            "type": "string",
            "description": "Opaque identifier. Preserve exactly.",
            "minLength": 1,
            "maxLength": 128
          },
          "producerId": {
            "type": "string",
            "description": "Opaque identifier. Preserve exactly.",
            "minLength": 1,
            "maxLength": 128
          },
          "reservationId": {
            "type": "string",
            "description": "Opaque identifier. Preserve exactly.",
            "minLength": 1,
            "maxLength": 128
          },
          "amountCoinCents": {
            "type": "integer",
            "minimum": 0,
            "description": "Unused reservation balance, in hundredths of one coin."
          }
        }
      },
      "Receipt": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "operationId",
          "reservationId",
          "amountCoinCents"
        ],
        "properties": {
          "operationId": {
            "type": "string",
            "description": "Opaque identifier. Preserve exactly.",
            "minLength": 1,
            "maxLength": 128
          },
          "reservationId": {
            "type": "string",
            "description": "Opaque identifier. Preserve exactly.",
            "minLength": 1,
            "maxLength": 128
          },
          "amountCoinCents": {
            "type": "integer",
            "minimum": 0,
            "maximum": 2147483647,
            "description": "Hundredths of a partner coin. 150 represents 1.50 coins."
          }
        }
      }
    }
  }
}
