{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://futa.invalid/contracts/payout-event.v1.json", "title": "PayoutEvent", "description": "A payout reached a state a merchant is told of: payout.pending_approval, payout.completed (PAID), payout.failed, payout.rejected and payout.expired; QUEUED, PROCESSING and UNCERTAIN send none. Its data is the payout as switch-core's outbox writes it (payout-event-v1), payout.paid named payout.completed and its key holders reduced to whether all are known, as switch-core's own rules hold them. A notice, not the record: GET /v1/payouts/{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.pending_approval", "payout.completed", "payout.failed", "payout.rejected", "payout.expired" ] }, "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", "kind", "participant", "destination_masked", "name", "amount", "fee", "total", "reserved", "currency", "fee_policy", "message", "merchant_reference", "state", "reason", "prepared_by", "key_holders", "threshold_version", "approval", "escalated", "version", "created_at", "updated_at", "paid_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": "^PO-[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}$" }, "kind": { "enum": [ "WALLET", "BANK" ] }, "participant": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,63}$" }, "destination_masked": { "type": "string", "pattern": "^(\\+243•••••[0-9]{4}|SIM-BANK-••[0-9]{2})$" }, "name": { "description": "The name check the payout was prepared with: never an unknown account; an unavailable name acknowledged.", "type": "object", "additionalProperties": false, "required": [ "enquiry_id", "status", "holder_name_masked", "verdict", "checked_at", "acknowledged_unavailable" ], "properties": { "enquiry_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "status": { "enum": [ "FOUND", "UNAVAILABLE" ] }, "holder_name_masked": { "type": [ "string", "null" ], "maxLength": 80, "pattern": "^[^\\s*]+( [^\\s*]\\*\\*\\*)*$" }, "verdict": { "enum": [ "MATCH", "DIFFERENT", "UNAVAILABLE", null ] }, "checked_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$" }, "acknowledged_unavailable": { "type": "boolean" } }, "allOf": [ { "if": { "properties": { "verdict": { "enum": [ "DIFFERENT", "UNAVAILABLE" ] } }, "required": [ "verdict" ] }, "then": { "properties": { "holder_name_masked": { "const": null } } } }, { "if": { "properties": { "status": { "const": "FOUND" }, "verdict": { "enum": [ "MATCH", null ] } }, "required": [ "status", "verdict" ] }, "then": { "properties": { "holder_name_masked": { "type": "string" } } } }, { "if": { "properties": { "status": { "enum": [ "FOUND" ] } }, "required": [ "status" ] }, "then": { "properties": { "acknowledged_unavailable": { "const": false }, "verdict": { "enum": [ "MATCH", "DIFFERENT", null ] } } } }, { "if": { "properties": { "status": { "enum": [ "UNAVAILABLE" ] } }, "required": [ "status" ] }, "then": { "properties": { "holder_name_masked": { "const": null }, "acknowledged_unavailable": { "const": true }, "verdict": { "enum": [ "UNAVAILABLE", null ] } } } } ] }, "amount": { "type": "integer", "minimum": 1, "maximum": 9000000000000 }, "fee": { "type": "integer", "minimum": 0, "maximum": 9000000000000 }, "total": { "type": "integer", "minimum": 0, "maximum": 18000000000000 }, "reserved": { "type": "integer", "minimum": 0, "maximum": 18000000000000 }, "currency": { "enum": [ "CDF", "USD" ] }, "fee_policy": { "const": "synthetic-zero-fee-v1" }, "message": { "type": [ "string", "null" ], "pattern": "^[^\\u0000-\\u001F\\u007F-\\u009F\\u00AD\\u061C\\u200B-\\u200F\\u2028-\\u202E\\u2060-\\u206F\\uFEFF\\uFFF9-\\uFFFB\\uD800-\\uDFFF]{1,100}$" }, "merchant_reference": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9_./-]{1,64}$" }, "state": { "enum": [ "PENDING_APPROVAL", "PAID", "FAILED", "REJECTED", "EXPIRED" ] }, "reason": { "enum": [ "UNKNOWN_ACCOUNT", "ACCOUNT_SUSPENDED", "CREDIT_REFUSED", "NAME_CHANGED", null ] }, "prepared_by": { "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" } } }, "threshold_version": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "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" } } } ] } } ] } ] }, "escalated": { "type": "boolean" }, "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$" }, "paid_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": { "currency": { "const": "CDF" } }, "required": [ "currency" ] }, "then": { "properties": { "amount": { "multipleOf": 100 }, "fee": { "multipleOf": 100 }, "total": { "multipleOf": 100 }, "reserved": { "multipleOf": 100 } } } }, { "if": { "properties": { "fee_policy": { "const": "synthetic-zero-fee-v1" } } }, "then": { "properties": { "fee": { "const": 0 } } } }, { "if": { "properties": { "kind": { "enum": [ "WALLET" ] } }, "required": [ "kind" ] }, "then": { "properties": { "destination_masked": { "pattern": "^\\+243•••••[0-9]{4}$" } } } }, { "if": { "properties": { "kind": { "enum": [ "BANK" ] } }, "required": [ "kind" ] }, "then": { "properties": { "destination_masked": { "pattern": "^SIM-BANK-••[0-9]{2}$" } } } }, { "if": { "properties": { "state": { "enum": [ "FAILED" ] } }, "required": [ "state" ] }, "then": { "properties": { "reason": { "type": "string" } } } }, { "if": { "properties": { "state": { "enum": [ "PENDING_APPROVAL", "QUEUED", "PROCESSING", "PAID", "UNCERTAIN", "REJECTED", "EXPIRED" ] } }, "required": [ "state" ] }, "then": { "properties": { "reason": { "const": null } } } }, { "if": { "properties": { "state": { "enum": [ "PAID" ] } }, "required": [ "state" ] }, "then": { "properties": { "paid_at": { "type": "string" } } } }, { "if": { "properties": { "state": { "enum": [ "PENDING_APPROVAL", "QUEUED", "PROCESSING", "FAILED", "UNCERTAIN", "REJECTED", "EXPIRED" ] } }, "required": [ "state" ] }, "then": { "properties": { "paid_at": { "const": null } } } }, { "if": { "properties": { "state": { "enum": [ "PENDING_APPROVAL", "REJECTED", "EXPIRED" ] } }, "required": [ "state" ] }, "then": { "properties": { "approval": { "type": "object" } } } }, { "if": { "properties": { "prepared_by": { "pattern": "^user:" } } }, "then": { "properties": { "key_holders": { "properties": { "known": { "const": true } } } } } } ], "description": "The payout as GET /v1/payouts/{id} answers it at this state, its key holders reduced to whether all are known." } }, "allOf": [ { "if": { "properties": { "type": { "const": "payout.pending_approval" } } }, "then": { "properties": { "data": { "properties": { "state": { "const": "PENDING_APPROVAL" } } } } } }, { "if": { "properties": { "type": { "const": "payout.completed" } } }, "then": { "properties": { "data": { "properties": { "state": { "const": "PAID" } } } } } }, { "if": { "properties": { "type": { "const": "payout.failed" } } }, "then": { "properties": { "data": { "properties": { "state": { "const": "FAILED" } } } } } }, { "if": { "properties": { "type": { "const": "payout.rejected" } } }, "then": { "properties": { "data": { "properties": { "state": { "const": "REJECTED" } } } } } }, { "if": { "properties": { "type": { "const": "payout.expired" } } }, "then": { "properties": { "data": { "properties": { "state": { "const": "EXPIRED" } } } } } } ] }