{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://mandateshield.com/schemas/gateway-adapter-v2.json",
  "title": "MandateShield Customer-Side Gateway Journal v2/v3-compatible",
  "description": "Backward-compatible customer-controlled compare-and-set journal with pre-consume ownership, recoverable consume ambiguity, provider-intent leases, provider-input binding, and optional v3 signed execution-permit redemption evidence. It must never contain payment credentials, private keys or provider client secrets.",
  "type": "object",
  "additionalProperties": false,
  "$defs": {
    "digest": {
      "type": "string",
      "pattern": "^sha256:[a-f0-9]{64}$"
    },
    "providerBinding": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "profile",
        "environment",
        "account",
        "request_id",
        "payee_destination",
        "method",
        "resource",
        "body_digest"
      ],
      "properties": {
        "profile": {
          "enum": [
            "GENERIC_HTTP_V1",
            "STRIPE_PAYMENT_INTENTS_V1",
            "X402_V2_EXACT",
            "MPP_CHARGE_V1"
          ]
        },
        "environment": {
          "enum": [
            "test",
            "live"
          ]
        },
        "account": {
          "type": "string",
          "minLength": 1,
          "maxLength": 240
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 240
        },
        "payee_destination": {
          "type": "string",
          "minLength": 1,
          "maxLength": 500
        },
        "method": {
          "enum": [
            "GET",
            "POST",
            "PUT",
            "PATCH"
          ]
        },
        "resource": {
          "type": "string",
          "format": "uri",
          "pattern": "^https://",
          "maxLength": 2048
        },
        "body_digest": {
          "$ref": "#/$defs/digest"
        }
      }
    },
    "permitProvider": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "profile",
        "environment",
        "account",
        "request_id",
        "request_digest",
        "idempotency_key"
      ],
      "properties": {
        "profile": {
          "enum": [
            "GENERIC_HTTP_V1",
            "STRIPE_PAYMENT_INTENTS_V1",
            "X402_V2_EXACT",
            "MPP_CHARGE_V1"
          ]
        },
        "environment": {
          "enum": [
            "test",
            "live"
          ]
        },
        "account": {
          "type": "string",
          "minLength": 1,
          "maxLength": 240
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 240
        },
        "request_digest": {
          "$ref": "#/$defs/digest"
        },
        "idempotency_key": {
          "type": "string",
          "minLength": 1,
          "maxLength": 256
        }
      }
    },
    "permitPayee": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "merchant_id",
        "destination",
        "destination_digest"
      ],
      "properties": {
        "merchant_id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 240
        },
        "destination": {
          "type": "string",
          "minLength": 1,
          "maxLength": 500
        },
        "destination_digest": {
          "$ref": "#/$defs/digest"
        }
      }
    },
    "permitAmount": {
      "oneOf": [
        {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "mode",
            "minor_units",
            "currency"
          ],
          "properties": {
            "mode": {
              "const": "ISO_4217"
            },
            "minor_units": {
              "type": "integer",
              "minimum": 1
            },
            "currency": {
              "type": "string",
              "pattern": "^[A-Z]{3}$"
            }
          }
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "mode",
            "atomic_units",
            "asset_decimals",
            "asset_id",
            "network"
          ],
          "properties": {
            "mode": {
              "const": "ATOMIC_ASSET"
            },
            "atomic_units": {
              "type": "string",
              "pattern": "^[1-9][0-9]{0,77}$"
            },
            "asset_decimals": {
              "type": "integer",
              "minimum": 0,
              "maximum": 30
            },
            "asset_id": {
              "type": "string",
              "minLength": 1,
              "maxLength": 500
            },
            "network": {
              "type": "string",
              "minLength": 1,
              "maxLength": 240
            }
          }
        }
      ]
    },
    "permitResource": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "method",
        "uri",
        "body_digest"
      ],
      "properties": {
        "method": {
          "enum": [
            "GET",
            "POST",
            "PUT",
            "PATCH"
          ]
        },
        "uri": {
          "type": "string",
          "format": "uri",
          "pattern": "^https://",
          "maxLength": 2048
        },
        "body_digest": {
          "$ref": "#/$defs/digest"
        }
      }
    },
    "permitExpectedRequest": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "provider",
        "payee",
        "amount",
        "resource"
      ],
      "properties": {
        "provider": {
          "$ref": "#/$defs/permitProvider"
        },
        "payee": {
          "$ref": "#/$defs/permitPayee"
        },
        "amount": {
          "$ref": "#/$defs/permitAmount"
        },
        "resource": {
          "$ref": "#/$defs/permitResource"
        }
      }
    },
    "executionPermit": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "format",
        "compact",
        "permit_id",
        "key_id",
        "jwks_uri",
        "verify_uri",
        "redemption_uri",
        "expires_at",
        "online_redemption_required",
        "offline_one_use_enforced"
      ],
      "properties": {
        "format": {
          "const": "application/mandateshield-execution-permit+jwt"
        },
        "compact": {
          "type": "string",
          "minLength": 1,
          "maxLength": 30000
        },
        "permit_id": {
          "type": "string",
          "pattern": "^msp_[a-f0-9]{32}$"
        },
        "key_id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 240
        },
        "jwks_uri": {
          "const": "https://mandateshield.com/.well-known/jwks.json"
        },
        "verify_uri": {
          "const": "https://mandateshield.com/api/v2/execution-permits/verify"
        },
        "redemption_uri": {
          "const": "https://mandateshield.com/api/v2/execution-permits/redeem"
        },
        "expires_at": {
          "type": "integer",
          "minimum": 1
        },
        "online_redemption_required": {
          "const": true
        },
        "offline_one_use_enforced": {
          "const": false
        }
      }
    },
    "executionReceipt": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "format",
        "compact",
        "execution_receipt_id",
        "key_id",
        "jwks_uri",
        "verify_uri",
        "historical_evidence_only",
        "execution_authorized",
        "evidence_class",
        "independent_verification"
      ],
      "properties": {
        "format": {
          "const": "application/mandateshield-execution-receipt+jwt"
        },
        "compact": {
          "type": "string",
          "minLength": 1,
          "maxLength": 20000
        },
        "execution_receipt_id": {
          "type": "string",
          "pattern": "^mse_[a-f0-9]{32}$"
        },
        "key_id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 240
        },
        "jwks_uri": {
          "const": "https://mandateshield.com/.well-known/jwks.json"
        },
        "verify_uri": {
          "const": "https://mandateshield.com/api/v2/execution-receipts/verify"
        },
        "historical_evidence_only": {
          "const": true
        },
        "execution_authorized": {
          "const": false
        },
        "evidence_class": {
          "enum": [
            "FACILITATOR_SIGNED",
            "PROVIDER_API_VERIFIED",
            "CHAIN_FINALIZED"
          ]
        },
        "independent_verification": {
          "const": true
        }
      }
    }
  },
  "required": [
    "id",
    "version",
    "state",
    "binding_digest",
    "receipt_id",
    "expected_audience",
    "consume_idempotency_key",
    "commit_idempotency_key",
    "release_idempotency_key",
    "provider_create_idempotency_key",
    "provider_confirm_idempotency_key",
    "created_at",
    "updated_at"
  ],
  "properties": {
    "id": {
      "type": "string",
      "pattern": "^msgw_[a-f0-9]{64}$"
    },
    "version": {
      "type": "integer",
      "minimum": 1
    },
    "state": {
      "type": "string",
      "enum": [
        "AWAITING_CONSUME",
        "CONSUME_INTENT",
        "CONSUMED",
        "PROVIDER_INTENT",
        "PROVIDER_PENDING",
        "OUTCOME_UNKNOWN",
        "RECONCILE_INTENT",
        "FINALIZING_COMMIT",
        "FINALIZING_RELEASE",
        "COMMITTED",
        "RELEASED",
        "CONSUME_REJECTED",
        "SUBMISSION_WINDOW_CLOSED"
      ]
    },
    "binding_digest": {
      "type": "string",
      "pattern": "^sha256:[a-f0-9]{64}$"
    },
    "receipt_id": {
      "type": "string",
      "pattern": "^msr_[a-f0-9]{32}$"
    },
    "expected_audience": {
      "type": "string",
      "minLength": 1,
      "maxLength": 240
    },
    "consume_idempotency_key": {
      "type": "string",
      "minLength": 1
    },
    "commit_idempotency_key": {
      "type": "string",
      "minLength": 1
    },
    "release_idempotency_key": {
      "type": "string",
      "minLength": 1
    },
    "provider_create_idempotency_key": {
      "type": "string",
      "minLength": 1
    },
    "provider_confirm_idempotency_key": {
      "type": "string",
      "minLength": 1
    },
    "provider_input_digest": {
      "type": "string",
      "pattern": "^sha256:[a-f0-9]{64}$"
    },
    "execution_mode": {
      "const": "SIGNED_EXECUTION_PERMIT_V1",
      "description": "Presence selects the provider-bound v3 path. Absence is the backward-compatible legacy direct-CONSUME path."
    },
    "provider_binding": {
      "$ref": "#/$defs/providerBinding"
    },
    "provider_binding_digest": {
      "$ref": "#/$defs/digest"
    },
    "permit_redemption_idempotency_key": {
      "type": "string",
      "minLength": 1,
      "maxLength": 256
    },
    "execution_permit": {
      "$ref": "#/$defs/executionPermit"
    },
    "execution_permit_digest": {
      "$ref": "#/$defs/digest"
    },
    "permit_expected_request": {
      "$ref": "#/$defs/permitExpectedRequest"
    },
    "permit_claim_id": {
      "type": "string",
      "pattern": "^mspc_[a-f0-9]{32}$"
    },
    "provider_submission_id": {
      "type": "string",
      "pattern": "^psub_[a-f0-9]{32}$"
    },
    "permit_redeemed_at": {
      "type": "string",
      "format": "date-time"
    },
    "consume_claimed_at": {
      "type": "string",
      "format": "date-time"
    },
    "consume_recovered_at": {
      "type": "string",
      "format": "date-time"
    },
    "consume_transitioned_at": {
      "type": "string",
      "format": "date-time",
      "description": "Hosted CONSUME transition time, or the conservative local receipt time when an older compatible processor omits it. Provider evidence earlier than this boundary is never finalized."
    },
    "settlement_deadline_at": {
      "type": "integer",
      "minimum": 1,
      "description": "Exact epoch-millisecond release and safe first-submission deadline returned by CONSUME. No new provider submission may start afterward. Read-only reconciliation may continue, but only COMMITTED can finalize after the deadline; RELEASE is never attempted late."
    },
    "provider_claimed_at": {
      "type": "string",
      "format": "date-time"
    },
    "provider_intent_abandoned_at": {
      "type": "string",
      "format": "date-time",
      "description": "Durable provenance that an expired provider-intent lease was marked abandoned before recovery. Absence or failure may release only with provider_submission_fenced=true and only before settlement_deadline_at."
    },
    "reconcile_claimed_at": {
      "type": "string",
      "format": "date-time"
    },
    "reconcile_origin_state": {
      "type": "string",
      "enum": [
        "PROVIDER_PENDING",
        "OUTCOME_UNKNOWN"
      ]
    },
    "provider_reference": {
      "type": "string",
      "minLength": 1,
      "maxLength": 240
    },
    "provider_outcome": {
      "type": "string",
      "enum": [
        "COMMITTED",
        "FAILED",
        "NOT_SUBMITTED",
        "PENDING",
        "UNKNOWN"
      ]
    },
    "provider_occurred_at": {
      "type": "string",
      "format": "date-time"
    },
    "provider_submission_fenced": {
      "const": true,
      "description": "The provider adapter proved that every earlier ambiguous submit can no longer commit."
    },
    "provider_submission_locked_at": {
      "type": "string",
      "format": "date-time"
    },
    "provider_evidence_id": {
      "type": "string",
      "pattern": "^pevd_[a-f0-9]{32}$"
    },
    "provider_evidence_class": {
      "enum": [
        "FACILITATOR_SIGNED",
        "PROVIDER_API_VERIFIED",
        "CHAIN_FINALIZED"
      ]
    },
    "provider_independent_verification": {
      "const": true
    },
    "execution_receipt": {
      "$ref": "#/$defs/executionReceipt"
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "updated_at": {
      "type": "string",
      "format": "date-time"
    }
  },
  "allOf": [
    {
      "if": {
        "required": [
          "execution_mode"
        ]
      },
      "then": {
        "required": [
          "provider_binding",
          "provider_binding_digest",
          "permit_redemption_idempotency_key"
        ]
      }
    },
    {
      "if": {
        "required": [
          "execution_mode"
        ],
        "properties": {
          "state": {
            "enum": [
              "CONSUMED",
              "PROVIDER_INTENT",
              "PROVIDER_PENDING",
              "OUTCOME_UNKNOWN",
              "RECONCILE_INTENT",
              "FINALIZING_COMMIT",
              "FINALIZING_RELEASE",
              "COMMITTED",
              "RELEASED",
              "SUBMISSION_WINDOW_CLOSED"
            ]
          }
        }
      },
      "then": {
        "required": [
          "execution_permit",
          "execution_permit_digest",
          "permit_expected_request"
        ]
      }
    },
    {
      "if": {
        "required": [
          "permit_claim_id"
        ]
      },
      "then": {
        "required": [
          "permit_redeemed_at",
          "provider_submission_id"
        ]
      }
    },
    {
      "if": {
        "required": [
          "provider_evidence_id"
        ]
      },
      "then": {
        "required": [
          "provider_evidence_class",
          "provider_independent_verification"
        ]
      }
    },
    {
      "if": {
        "required": [
          "execution_mode"
        ],
        "properties": {
          "state": {
            "enum": [
              "COMMITTED",
              "RELEASED"
            ]
          }
        }
      },
      "then": {
        "required": [
          "provider_evidence_id",
          "provider_evidence_class",
          "provider_independent_verification",
          "execution_receipt"
        ]
      }
    },
    {
      "if": {
        "properties": {
          "state": {
            "enum": [
              "CONSUMED",
              "PROVIDER_INTENT",
              "PROVIDER_PENDING",
              "OUTCOME_UNKNOWN",
              "RECONCILE_INTENT",
              "FINALIZING_COMMIT",
              "FINALIZING_RELEASE",
              "COMMITTED",
              "RELEASED",
              "SUBMISSION_WINDOW_CLOSED"
            ]
          }
        },
        "required": [
          "state"
        ]
      },
      "then": {
        "required": [
          "settlement_deadline_at",
          "consume_transitioned_at"
        ]
      }
    },
    {
      "if": {
        "properties": {
          "state": {
            "enum": [
              "CONSUME_INTENT",
              "CONSUMED",
              "PROVIDER_INTENT",
              "PROVIDER_PENDING",
              "OUTCOME_UNKNOWN",
              "RECONCILE_INTENT",
              "FINALIZING_COMMIT",
              "FINALIZING_RELEASE",
              "COMMITTED",
              "RELEASED",
              "CONSUME_REJECTED",
              "SUBMISSION_WINDOW_CLOSED"
            ]
          }
        },
        "required": [
          "state"
        ]
      },
      "then": {
        "required": [
          "consume_claimed_at"
        ]
      }
    },
    {
      "if": {
        "properties": {
          "state": {
            "enum": [
              "PROVIDER_INTENT",
              "PROVIDER_PENDING",
              "OUTCOME_UNKNOWN",
              "RECONCILE_INTENT",
              "FINALIZING_COMMIT",
              "FINALIZING_RELEASE",
              "COMMITTED",
              "RELEASED"
            ]
          }
        },
        "required": [
          "state"
        ]
      },
      "then": {
        "required": [
          "provider_claimed_at"
        ]
      }
    },
    {
      "if": {
        "properties": {
          "state": {
            "const": "OUTCOME_UNKNOWN"
          }
        },
        "required": [
          "state"
        ]
      },
      "then": {
        "required": [
          "provider_outcome",
          "provider_occurred_at"
        ],
        "properties": {
          "provider_outcome": {
            "const": "UNKNOWN"
          }
        }
      }
    },
    {
      "if": {
        "properties": {
          "state": {
            "const": "RECONCILE_INTENT"
          }
        },
        "required": [
          "state"
        ]
      },
      "then": {
        "required": [
          "reconcile_claimed_at",
          "reconcile_origin_state",
          "provider_outcome",
          "provider_occurred_at"
        ]
      }
    },
    {
      "if": {
        "properties": {
          "state": {
            "const": "SUBMISSION_WINDOW_CLOSED"
          }
        },
        "required": [
          "state"
        ]
      },
      "then": {
        "required": [
          "provider_submission_locked_at",
          "provider_outcome",
          "provider_occurred_at"
        ],
        "properties": {
          "provider_outcome": {
            "const": "UNKNOWN"
          }
        }
      }
    },
    {
      "if": {
        "properties": {
          "state": {
            "enum": [
              "PROVIDER_PENDING",
              "FINALIZING_COMMIT",
              "FINALIZING_RELEASE",
              "COMMITTED",
              "RELEASED"
            ]
          }
        },
        "required": [
          "state"
        ]
      },
      "then": {
        "required": [
          "provider_reference",
          "provider_outcome",
          "provider_occurred_at"
        ]
      }
    },
    {
      "if": {
        "properties": {
          "state": {
            "enum": [
              "FINALIZING_RELEASE",
              "RELEASED"
            ]
          }
        },
        "required": [
          "state",
          "reconcile_claimed_at"
        ]
      },
      "then": {
        "required": [
          "provider_submission_fenced"
        ]
      }
    },
    {
      "if": {
        "properties": {
          "state": {
            "const": "PROVIDER_PENDING"
          }
        },
        "required": [
          "state"
        ]
      },
      "then": {
        "properties": {
          "provider_outcome": {
            "const": "PENDING"
          }
        }
      }
    },
    {
      "if": {
        "properties": {
          "state": {
            "enum": [
              "FINALIZING_COMMIT",
              "COMMITTED"
            ]
          }
        },
        "required": [
          "state"
        ]
      },
      "then": {
        "properties": {
          "provider_outcome": {
            "const": "COMMITTED"
          }
        }
      }
    },
    {
      "if": {
        "properties": {
          "state": {
            "enum": [
              "FINALIZING_RELEASE",
              "RELEASED"
            ]
          }
        },
        "required": [
          "state"
        ]
      },
      "then": {
        "properties": {
          "provider_outcome": {
            "enum": [
              "FAILED",
              "NOT_SUBMITTED"
            ]
          }
        }
      }
    }
  ]
}