{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://tools.press.zone/schemas/billing-ledger-case.schema.json", "title": "Billing ledger fixture case", "type": "object", "additionalProperties": false, "required": [ "caseId", "category", "description", "evidenceMetadata", "initial", "events", "expected" ], "properties": { "caseId": { "type": "string", "pattern": "^BL-[0-9]{3}$" }, "category": { "enum": [ "purchase", "provider", "conversion", "reversal", "tax", "adjustment", "ordering", "malformed" ] }, "description": { "type": "string", "minLength": 1 }, "initial": { "$ref": "#/$defs/initial" }, "events": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/event" } }, "expected": { "$ref": "#/$defs/expected" }, "evidenceMetadata": { "$ref": "#/$defs/evidenceMetadata" } }, "$defs": { "decimal": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "signedDecimal": { "type": "string", "pattern": "^-?(0|[1-9][0-9]*)$" }, "id": { "type": "string", "pattern": "^[a-z][a-z0-9_.:-]{2,127}$" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "jurisdiction": { "type": "string", "pattern": "^[A-Z]{2}(?:-[A-Z0-9]{1,3})?$" }, "hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "purchase": { "type": "object", "additionalProperties": false, "required": [ "purchaseId", "ownerId", "quantity", "unitAmountCents", "itemSubtotalCents", "currency", "jurisdiction", "registrationVersion", "taxAmountCents", "registrationAuthorizationVersion" ], "properties": { "purchaseId": { "$ref": "#/$defs/id" }, "ownerId": { "$ref": "#/$defs/id" }, "quantity": { "$ref": "#/$defs/decimal" }, "unitAmountCents": { "$ref": "#/$defs/decimal" }, "itemSubtotalCents": { "$ref": "#/$defs/decimal" }, "currency": { "$ref": "#/$defs/currency" }, "jurisdiction": { "$ref": "#/$defs/jurisdiction" }, "registrationVersion": { "$ref": "#/$defs/decimal" }, "taxAmountCents": { "$ref": "#/$defs/decimal" }, "registrationAuthorizationVersion": { "$ref": "#/$defs/decimal" } } }, "receipt": { "type": "object", "additionalProperties": false, "required": [ "eventId", "payloadHash", "objectId", "eventType" ], "properties": { "eventId": { "$ref": "#/$defs/id" }, "payloadHash": { "$ref": "#/$defs/hash" }, "objectId": { "$ref": "#/$defs/id" }, "eventType": { "enum": [ "payment_webhook", "refund_webhook" ] } } }, "claim": { "type": "object", "additionalProperties": false, "required": [ "objectId", "purchaseId", "effect" ], "properties": { "objectId": { "$ref": "#/$defs/id" }, "purchaseId": { "$ref": "#/$defs/id" }, "effect": { "enum": [ "payment_grant", "refund_reversal", "adjustment" ] } } }, "registration": { "type": "object", "additionalProperties": false, "required": [ "jurisdiction", "version", "expiresAt", "taxEvidenceId", "authenticatedBy", "validFrom", "evaluatedAt", "databaseNow", "authorizationSourceVersion" ], "properties": { "jurisdiction": { "$ref": "#/$defs/jurisdiction" }, "version": { "$ref": "#/$defs/decimal" }, "expiresAt": { "$ref": "#/$defs/decimal" }, "taxEvidenceId": { "$ref": "#/$defs/id" }, "authenticatedBy": { "$ref": "#/$defs/id" }, "validFrom": { "$ref": "#/$defs/decimal" }, "evaluatedAt": { "$ref": "#/$defs/decimal" }, "databaseNow": { "$ref": "#/$defs/decimal" }, "authorizationSourceVersion": { "$ref": "#/$defs/decimal" } } }, "cycle": { "type": "object", "additionalProperties": false, "required": [ "cycleId", "ownerId", "fundingKind", "state", "debit", "compensationEligible" ], "properties": { "cycleId": { "$ref": "#/$defs/id" }, "ownerId": { "$ref": "#/$defs/id" }, "fundingKind": { "enum": [ "customer", "goodwill" ] }, "state": { "enum": [ "active", "succeeded", "failed", "compensated" ] }, "debit": { "$ref": "#/$defs/decimal" }, "compensationEligible": { "type": "boolean" } } }, "entry": { "type": "object", "additionalProperties": false, "required": [ "key", "delta", "reason", "ref" ], "properties": { "key": { "$ref": "#/$defs/id" }, "delta": { "$ref": "#/$defs/signedDecimal" }, "reason": { "enum": [ "payment_grant", "conversion_debit", "cycle_failure_compensation", "payment_refund_reversal", "payment_dispute_reversal", "operator_adjustment" ] }, "ref": { "type": "object", "additionalProperties": false, "required": [ "kind", "id" ], "properties": { "kind": { "enum": [ "purchase", "cycle", "reversal", "adjustment" ] }, "id": { "$ref": "#/$defs/id" } } } } }, "adjustment": { "type": "object", "additionalProperties": false, "required": [ "adjustmentId", "ownerId", "delta", "authorizedBy", "reasonCode", "auditRecordId", "idempotencyKey", "authorizationId", "authorizationVersion", "authorizationSourceVersion", "requestedAt", "payloadHash", "auditOutcome" ], "properties": { "adjustmentId": { "$ref": "#/$defs/id" }, "ownerId": { "$ref": "#/$defs/id" }, "delta": { "$ref": "#/$defs/signedDecimal" }, "authorizedBy": { "$ref": "#/$defs/id" }, "reasonCode": { "enum": [ "support_credit", "fraud_correction", "billing_correction" ] }, "auditRecordId": { "$ref": "#/$defs/id" }, "idempotencyKey": { "$ref": "#/$defs/id" }, "authorizationId": { "$ref": "#/$defs/id" }, "authorizationVersion": { "$ref": "#/$defs/decimal" }, "authorizationSourceVersion": { "$ref": "#/$defs/decimal" }, "requestedAt": { "$ref": "#/$defs/decimal" }, "payloadHash": { "$ref": "#/$defs/hash" }, "auditOutcome": { "enum": [ "accepted", "replay_same_hash_noop" ] } } }, "initial": { "type": "object", "additionalProperties": false, "required": [ "ledgerBefore", "purchases", "receipts", "claims", "registrations", "cycles", "adjustments", "refundStates", "operatorAuthorizations", "evaluationAt", "databaseNow", "authoritativeJurisdictionTime" ], "properties": { "ledgerBefore": { "type": "array", "items": { "$ref": "#/$defs/entry" } }, "purchases": { "type": "array", "items": { "$ref": "#/$defs/purchase" } }, "receipts": { "type": "array", "items": { "$ref": "#/$defs/receipt" } }, "claims": { "type": "array", "items": { "$ref": "#/$defs/claim" } }, "registrations": { "type": "array", "items": { "$ref": "#/$defs/registration" } }, "cycles": { "type": "array", "items": { "$ref": "#/$defs/cycle" } }, "adjustments": { "type": "array", "items": { "$ref": "#/$defs/adjustment" } }, "refundStates": { "type": "array", "items": { "$ref": "#/$defs/refundState" } }, "operatorAuthorizations": { "type": "array", "items": { "$ref": "#/$defs/authorization" } }, "evaluationAt": { "$ref": "#/$defs/decimal" }, "databaseNow": { "$ref": "#/$defs/decimal" }, "authoritativeJurisdictionTime": { "$ref": "#/$defs/decimal" } } }, "event": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "type", "purchaseId", "ownerId", "quantity", "unitAmountCents", "currency", "jurisdiction", "registrationVersion", "taxAmountCents", "registrationAuthorizationVersion" ], "properties": { "type": { "const": "create_purchase" }, "purchaseId": { "$ref": "#/$defs/id" }, "ownerId": { "$ref": "#/$defs/id" }, "quantity": { "$ref": "#/$defs/decimal" }, "unitAmountCents": { "$ref": "#/$defs/decimal" }, "currency": { "$ref": "#/$defs/currency" }, "jurisdiction": { "$ref": "#/$defs/jurisdiction" }, "registrationVersion": { "$ref": "#/$defs/decimal" }, "taxAmountCents": { "$ref": "#/$defs/decimal" }, "registrationAuthorizationVersion": { "$ref": "#/$defs/decimal" } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "eventId", "payloadHash", "objectId", "purchaseId", "ownerId", "quantity", "amountCents", "currency", "jurisdiction", "paymentState", "signatureVerified", "taxAmountCents", "providerTruth" ], "properties": { "type": { "const": "payment_webhook" }, "eventId": { "$ref": "#/$defs/id" }, "payloadHash": { "$ref": "#/$defs/hash" }, "objectId": { "$ref": "#/$defs/id" }, "purchaseId": { "$ref": "#/$defs/id" }, "ownerId": { "$ref": "#/$defs/id" }, "quantity": { "$ref": "#/$defs/decimal" }, "amountCents": { "$ref": "#/$defs/decimal" }, "currency": { "$ref": "#/$defs/currency" }, "jurisdiction": { "$ref": "#/$defs/jurisdiction" }, "paymentState": { "enum": [ "paid", "failed" ] }, "signatureVerified": { "type": "boolean" }, "taxAmountCents": { "$ref": "#/$defs/decimal" }, "providerTruth": { "$ref": "#/$defs/providerTruth" } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "eventId", "payloadHash", "objectId", "purchaseId", "cumulativeRefundedItemSubtotalCents", "kind", "signatureVerified", "ownerId", "quantity", "amountCents", "taxAmountCents", "currency", "jurisdiction", "taxRefundedCents", "providerTruth" ], "properties": { "type": { "const": "refund_webhook" }, "eventId": { "$ref": "#/$defs/id" }, "payloadHash": { "$ref": "#/$defs/hash" }, "objectId": { "$ref": "#/$defs/id" }, "purchaseId": { "$ref": "#/$defs/id" }, "cumulativeRefundedItemSubtotalCents": { "$ref": "#/$defs/decimal" }, "kind": { "enum": [ "refund", "dispute" ] }, "signatureVerified": { "type": "boolean" }, "ownerId": { "$ref": "#/$defs/id" }, "quantity": { "$ref": "#/$defs/decimal" }, "amountCents": { "$ref": "#/$defs/decimal" }, "taxAmountCents": { "$ref": "#/$defs/decimal" }, "currency": { "$ref": "#/$defs/currency" }, "jurisdiction": { "$ref": "#/$defs/jurisdiction" }, "taxRefundedCents": { "$ref": "#/$defs/decimal" }, "providerTruth": { "$ref": "#/$defs/providerTruth" } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "cycleId", "ownerId", "fundingKind", "debit", "idempotencyKey" ], "properties": { "type": { "const": "conversion_accept" }, "cycleId": { "$ref": "#/$defs/id" }, "ownerId": { "$ref": "#/$defs/id" }, "fundingKind": { "enum": [ "customer", "goodwill" ] }, "debit": { "$ref": "#/$defs/decimal" }, "idempotencyKey": { "$ref": "#/$defs/id" } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "cycleId" ], "properties": { "type": { "const": "cycle_failed" }, "cycleId": { "$ref": "#/$defs/id" } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "registration" ], "properties": { "type": { "const": "register_jurisdiction" }, "registration": { "$ref": "#/$defs/registration" } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "adjustmentId", "ownerId", "delta", "authorizedBy", "reasonCode", "auditRecordId", "idempotencyKey", "authorizationId", "authorizationVersion", "authorizationSourceVersion", "requestedAt", "payloadHash" ], "properties": { "type": { "const": "operator_adjustment" }, "adjustmentId": { "$ref": "#/$defs/id" }, "ownerId": { "$ref": "#/$defs/id" }, "delta": { "$ref": "#/$defs/signedDecimal" }, "authorizedBy": { "$ref": "#/$defs/id" }, "reasonCode": { "enum": [ "support_credit", "fraud_correction", "billing_correction" ] }, "auditRecordId": { "$ref": "#/$defs/id" }, "idempotencyKey": { "$ref": "#/$defs/id" }, "authorizationId": { "$ref": "#/$defs/id" }, "authorizationVersion": { "$ref": "#/$defs/decimal" }, "authorizationSourceVersion": { "$ref": "#/$defs/decimal" }, "requestedAt": { "$ref": "#/$defs/decimal" }, "payloadHash": { "$ref": "#/$defs/hash" } } } ] }, "winner": { "type": "object", "additionalProperties": false, "required": [ "constraint", "alternatives", "matchingWinner", "jobId", "effectKey" ], "properties": { "constraint": { "const": "exactly_one_correlated_winner" }, "alternatives": { "type": "array", "minItems": 2, "items": { "type": "object", "additionalProperties": false, "required": [ "label", "outcome", "cycleId", "submissionId", "jobId", "effectKey" ], "properties": { "label": { "$ref": "#/$defs/id" }, "outcome": { "enum": [ "accepted", "rejected", "noop", "reconcile" ] }, "cycleId": { "oneOf": [ { "$ref": "#/$defs/id" }, { "type": "null" } ] }, "submissionId": { "$ref": "#/$defs/id" }, "jobId": { "oneOf": [ { "$ref": "#/$defs/id" }, { "type": "null" } ] }, "effectKey": { "oneOf": [ { "$ref": "#/$defs/id" }, { "type": "null" } ] } } } }, "matchingWinner": { "$ref": "#/$defs/id" }, "jobId": { "$ref": "#/$defs/id" }, "effectKey": { "$ref": "#/$defs/id" } } }, "state": { "type": "object", "additionalProperties": false, "required": [ "purchases", "receipts", "claims", "cycles", "adjustments", "refundStates" ], "properties": { "purchases": { "type": "array", "items": { "$ref": "#/$defs/purchase" } }, "receipts": { "type": "array", "items": { "$ref": "#/$defs/receipt" } }, "claims": { "type": "array", "items": { "$ref": "#/$defs/claim" } }, "cycles": { "type": "array", "items": { "$ref": "#/$defs/cycle" } }, "adjustments": { "type": "array", "items": { "$ref": "#/$defs/adjustment" } }, "refundStates": { "type": "array", "items": { "$ref": "#/$defs/refundState" } } } }, "expected": { "type": "object", "additionalProperties": false, "required": [ "outcome", "error", "ledgerAppends", "ledgerNet", "spendableBalance", "deficit", "state", "winner", "assertions", "providerCalls", "auditOutcome" ], "properties": { "outcome": { "enum": [ "accepted", "rejected", "noop", "reconcile", "correlated" ] }, "error": { "oneOf": [ { "enum": [ "INVALID_QUANTITY", "AMOUNT_MISMATCH", "CURRENCY_MISMATCH", "JURISDICTION_MISMATCH", "OWNER_MISMATCH", "PURCHASE_NOT_FOUND", "UNVERIFIED_EVENT", "EVENT_PAYLOAD_CONFLICT", "OBJECT_IDENTITY_CONFLICT", "REGISTRATION_INVALID", "REGISTRATION_EXPIRED", "INSUFFICIENT_CREDITS", "CYCLE_NOT_ELIGIBLE", "ADJUSTMENT_UNAUTHORIZED", "ADJUSTMENT_INVALID", "INVALID_BIGINT" ] }, { "type": "null" } ] }, "ledgerAppends": { "type": "array", "items": { "$ref": "#/$defs/entry" } }, "ledgerNet": { "$ref": "#/$defs/signedDecimal" }, "spendableBalance": { "$ref": "#/$defs/decimal" }, "deficit": { "$ref": "#/$defs/decimal" }, "state": { "$ref": "#/$defs/state" }, "winner": { "oneOf": [ { "$ref": "#/$defs/winner" }, { "type": "null" } ] }, "assertions": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "enum": [ "canonical_purchase", "provider_event", "provider_object", "payload_hash", "currency", "owner", "quantity", "amount", "tax", "jurisdiction", "signature", "claim", "effect", "rollback", "provider_calls", "registration", "cumulative_allocation", "authorization", "audit" ] } }, "providerCalls": { "$ref": "#/$defs/decimal" }, "auditOutcome": { "enum": [ "none", "accepted", "unauthorized_rejected", "expired_rejected", "malformed_rejected", "replay_same_hash_noop", "replay_different_hash_rejected" ] } } }, "authorization": { "type": "object", "additionalProperties": false, "required": [ "authorizationId", "operatorId", "version", "validFrom", "expiresAt", "scopes", "source", "sourceVersion" ], "properties": { "authorizationId": { "$ref": "#/$defs/id" }, "operatorId": { "$ref": "#/$defs/id" }, "version": { "$ref": "#/$defs/decimal" }, "validFrom": { "$ref": "#/$defs/decimal" }, "expiresAt": { "$ref": "#/$defs/decimal" }, "scopes": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "enum": [ "support_credit", "fraud_correction", "billing_correction" ] } }, "source": { "const": "operator_authorization_registry" }, "sourceVersion": { "$ref": "#/$defs/decimal" } } }, "refundState": { "type": "object", "additionalProperties": false, "required": [ "purchaseId", "cumulativeRefundedItemSubtotalCents", "reversedCredits" ], "properties": { "purchaseId": { "$ref": "#/$defs/id" }, "cumulativeRefundedItemSubtotalCents": { "$ref": "#/$defs/decimal" }, "reversedCredits": { "$ref": "#/$defs/decimal" } } }, "evidenceMetadata": { "type": "object", "additionalProperties": false, "required": [ "observedAt", "sourceUri", "ownerEmail", "traceId" ], "properties": { "observedAt": { "type": "string", "format": "date-time" }, "sourceUri": { "type": "string", "format": "uri" }, "ownerEmail": { "type": "string", "format": "email" }, "traceId": { "type": "string", "format": "uuid" } } }, "providerTruth": { "type": "object", "additionalProperties": false, "required": [ "eventId", "objectId", "purchaseId", "ownerId", "quantity", "amountCents", "currency", "jurisdiction", "paymentState", "taxAmountCents" ], "properties": { "eventId": { "$ref": "#/$defs/id" }, "objectId": { "$ref": "#/$defs/id" }, "purchaseId": { "$ref": "#/$defs/id" }, "ownerId": { "$ref": "#/$defs/id" }, "quantity": { "$ref": "#/$defs/decimal" }, "amountCents": { "$ref": "#/$defs/decimal" }, "currency": { "$ref": "#/$defs/currency" }, "jurisdiction": { "$ref": "#/$defs/jurisdiction" }, "taxAmountCents": { "$ref": "#/$defs/decimal" }, "paymentState": { "enum": [ "paid", "failed", "refunded", "disputed" ] } } } } }