{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://futa.invalid/contracts/payment-event.v1.json",
  "title": "Payment event v1",
  "description": "A payment changed state: one event per state the payment reaches, its type payment. and the state in lower case. A notice, not the record: GET /v1/payments/{id} is authoritative.",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "id",
    "type",
    "occurred_at",
    "schema_version",
    "data"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "description": "The event's id. The same event may arrive more than once (a retry or a replay): deduplicate on it."
    },
    "schema_version": {
      "const": 1
    },
    "type": {
      "type": "string",
      "pattern": "^payment\\.(created|pending_approval|uncertain|approved|declined|expired)$"
    },
    "occurred_at": {
      "type": "string",
      "format": "date-time"
    },
    "data": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "id",
        "merchant_id",
        "reference",
        "amount",
        "currency",
        "state",
        "sequence",
        "sandbox",
        "reason"
      ],
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid",
          "description": "The payment's id, as POST /v1/payments answered it: map the order by it, never by reference."
        },
        "merchant_id": {
          "type": "string"
        },
        "reference": {
          "type": "string",
          "description": "Futa's FT- reference for the payment, not the merchant's order reference."
        },
        "amount": {
          "type": "integer",
          "minimum": 1,
          "description": "ISO minor units (scale 2 for USD and CDF): compare it and currency with the order."
        },
        "currency": {
          "enum": [
            "USD",
            "CDF"
          ]
        },
        "state": {
          "enum": [
            "CREATED",
            "PENDING_APPROVAL",
            "UNCERTAIN",
            "APPROVED",
            "DECLINED",
            "EXPIRED"
          ]
        },
        "sequence": {
          "type": "integer",
          "minimum": 0,
          "description": "The payment's version at this state, rising with each change: apply an event only when its sequence is above the last one applied for that payment."
        },
        "sandbox": {
          "const": true
        },
        "reason": {
          "type": [
            "string",
            "null"
          ],
          "description": "Futa's code for the state, or null (for example ISSUER_APPROVED, ISSUER_DECLINED)."
        }
      }
    }
  }
}