{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://futa.invalid/contracts/payout-batch-event.v1.json", "title": "PayoutBatchEvent", "description": "A payout batch was validated (its lines judged, ready for the preparer's decisions) or completed (every line final); its lines emit no event of their own. Its data is the batch as switch-core's outbox writes it (payout-batch-event-v1), its key holders reduced to whether all are known, as switch-core's own rules hold them. A notice, not the record: GET /v1/payout-batches/{id} is authoritative. Delivered since 0.59.17 to an endpoint that chose it; switch-core's queued, processing and uncertain states are never sent, nor held.", "type": "object", "additionalProperties": false, "required": [ "id", "type", "schema_version", "occurred_at", "data" ], "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "type": { "enum": [ "payout_batch.validated", "payout_batch.completed" ] }, "schema_version": { "const": 1 }, "occurred_at": { "type": "string", "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\\.[0-9]{1,9})?Z$" }, "data": { "type": "object", "additionalProperties": false, "required": [ "schema_version", "id", "reference", "merchant_id", "currency", "state", "expected_lines", "received_lines", "counts", "totals", "fee_policy", "prepared_by", "preparers", "key_holders", "approval", "retry_of", "version", "created_at", "updated_at", "submitted_at", "finished_at", "sandbox" ], "properties": { "schema_version": { "const": 1 }, "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "reference": { "type": "string", "pattern": "^PB-[0-9A-HJKMNP-TV-Z]{4}-[0-9A-HJKMNP-TV-Z]{4}$" }, "merchant_id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$" }, "currency": { "enum": [ "CDF", "USD" ] }, "state": { "enum": [ "VALIDATED", "COMPLETED" ] }, "expected_lines": { "type": "integer", "minimum": 1, "maximum": 100000 }, "received_lines": { "type": "integer", "minimum": 0, "maximum": 100000 }, "counts": { "description": "How many lines are in each state: lines, never money.", "type": "object", "additionalProperties": false, "required": [ "valid", "review", "excluded", "pending_approval", "queued", "processing", "paid", "failed", "uncertain", "rejected", "expired" ], "properties": { "valid": { "type": "integer", "minimum": 0, "maximum": 100000 }, "review": { "type": "integer", "minimum": 0, "maximum": 100000 }, "excluded": { "type": "integer", "minimum": 0, "maximum": 100000 }, "pending_approval": { "type": "integer", "minimum": 0, "maximum": 100000 }, "queued": { "type": "integer", "minimum": 0, "maximum": 100000 }, "processing": { "type": "integer", "minimum": 0, "maximum": 100000 }, "paid": { "type": "integer", "minimum": 0, "maximum": 100000 }, "failed": { "type": "integer", "minimum": 0, "maximum": 100000 }, "uncertain": { "type": "integer", "minimum": 0, "maximum": 100000 }, "rejected": { "type": "integer", "minimum": 0, "maximum": 100000 }, "expired": { "type": "integer", "minimum": 0, "maximum": 100000 } } }, "totals": { "description": "The batch's money in its one currency: its lines' amounts and fees, then paid, returned to available and still reserved, which add up to the total once submitted.", "type": "object", "additionalProperties": false, "required": [ "currency", "amount", "fee", "total", "paid", "returned", "reserved" ], "properties": { "currency": { "enum": [ "CDF", "USD" ] }, "amount": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "fee": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "total": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "paid": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "returned": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "reserved": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 } }, "allOf": [ { "if": { "properties": { "currency": { "const": "CDF" } }, "required": [ "currency" ] }, "then": { "properties": { "amount": { "multipleOf": 100 }, "fee": { "multipleOf": 100 }, "total": { "multipleOf": 100 }, "paid": { "multipleOf": 100 }, "returned": { "multipleOf": 100 }, "reserved": { "multipleOf": 100 } } } } ] }, "fee_policy": { "const": "synthetic-zero-fee-v1" }, "prepared_by": { "type": "string", "pattern": "^(user|key):[\\x21-\\x2B\\x2D-\\x7E]{1,128}$" }, "preparers": { "type": "array", "minItems": 1, "maxItems": 100, "uniqueItems": true, "items": { "type": "string", "pattern": "^(user|key):[\\x21-\\x2B\\x2D-\\x7E]{1,128}$" } }, "key_holders": { "description": "Whether every holder of the keys that prepared it is a known person: known false means nobody can approve it. The holders themselves are never sent to an endpoint; an authenticated read lists them.", "type": "object", "additionalProperties": false, "required": [ "known" ], "properties": { "known": { "type": "boolean" } } }, "approval": { "anyOf": [ { "type": "null" }, { "description": "The wait for a second person: when it ends, and who decided, when and why; an expiry is no one's decision.", "type": "object", "additionalProperties": false, "required": [ "expires_at", "approved_by", "rejected_by", "decided_at", "reason" ], "properties": { "expires_at": { "type": "string", "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\\.[0-9]{1,9})?Z$" }, "approved_by": { "type": [ "string", "null" ], "pattern": "^user:[\\x21-\\x2B\\x2D-\\x7E]{1,128}$" }, "rejected_by": { "type": [ "string", "null" ], "pattern": "^user:[\\x21-\\x2B\\x2D-\\x7E]{1,128}$" }, "decided_at": { "type": [ "string", "null" ], "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\\.[0-9]{1,9})?Z$" }, "reason": { "type": [ "string", "null" ], "minLength": 10, "maxLength": 500, "pattern": "^[^\\s\\u0000-\\u001F\\u007F-\\u009F]([^\\u0000-\\u001F\\u007F-\\u009F]*[^\\s\\u0000-\\u001F\\u007F-\\u009F])?$" } }, "allOf": [ { "not": { "properties": { "approved_by": { "type": "string" }, "rejected_by": { "type": "string" } } } }, { "if": { "properties": { "decided_at": { "const": null } } }, "then": { "properties": { "approved_by": { "const": null }, "rejected_by": { "const": null }, "reason": { "const": null } } }, "else": { "properties": { "reason": { "type": "string" } }, "anyOf": [ { "properties": { "approved_by": { "type": "string" } } }, { "properties": { "rejected_by": { "type": "string" } } } ] } } ] } ] }, "retry_of": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "version": { "type": "integer", "minimum": 1, "maximum": 2147483647 }, "created_at": { "type": "string", "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\\.[0-9]{1,9})?Z$" }, "updated_at": { "type": "string", "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\\.[0-9]{1,9})?Z$" }, "submitted_at": { "type": [ "string", "null" ], "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\\.[0-9]{1,9})?Z$" }, "finished_at": { "type": [ "string", "null" ], "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\\.[0-9]{1,9})?Z$" }, "sandbox": { "const": true } }, "allOf": [ { "if": { "properties": { "state": { "enum": [ "UPLOADED", "VALIDATING", "VALIDATED" ] } }, "required": [ "state" ] }, "then": { "properties": { "approval": { "const": null }, "submitted_at": { "const": null } } } }, { "if": { "properties": { "state": { "enum": [ "PENDING_APPROVAL", "APPROVED", "PROCESSING", "COMPLETED", "REJECTED", "EXPIRED" ] } }, "required": [ "state" ] }, "then": { "properties": { "approval": { "type": "object" }, "submitted_at": { "type": "string" } } } }, { "if": { "properties": { "state": { "enum": [ "COMPLETED", "REJECTED", "EXPIRED" ] } }, "required": [ "state" ] }, "then": { "properties": { "finished_at": { "type": "string" } } } }, { "if": { "properties": { "state": { "enum": [ "UPLOADED", "VALIDATING", "VALIDATED", "PENDING_APPROVAL", "APPROVED", "PROCESSING" ] } }, "required": [ "state" ] }, "then": { "properties": { "finished_at": { "const": null } } } }, { "if": { "properties": { "preparers": { "contains": { "pattern": "^key:" } } } }, "else": { "properties": { "key_holders": { "properties": { "known": { "const": true } } } } } } ], "description": "The batch as GET /v1/payout-batches/{id} answers it at this state, its key holders reduced to whether all are known; its lines emit no event of their own." } }, "allOf": [ { "if": { "properties": { "type": { "const": "payout_batch.validated" } } }, "then": { "properties": { "data": { "properties": { "state": { "const": "VALIDATED" } } } } } }, { "if": { "properties": { "type": { "const": "payout_batch.completed" } } }, "then": { "properties": { "data": { "properties": { "state": { "const": "COMPLETED" } } } } } } ] }