F3_Payment / Payment

金額の権威をサーバーへ置き、決済と返金を別々に承認する器官。

server authorityが確定した minor units でcheckoutを計画し、承認後にtest-modeのprovider sessionを作る。

入力 → 状態 → 出力

線形テキスト代替: Action Registryが検証したpayloadをengineへ渡す。engineはこの器官のdurable state sliceを更新し、resultまたはerrorをAction Coreへ返す。光は実行中、琥珀の境界はarmed状態、外縁はこの器官の作用半径を表す。

入力validated JSON payload
状態engine-owned durable slice
承認必要な外部 / 不可逆操作だけ
出力result / receipt / explicit error
回復webhookは署名とevent IDで検証する。返金はcheckoutと別の plan → arm → execute である。

8 registered actionsnone dependenciesstripe binding reference

保存状態はAction Coreのfilesystem state store内の capabilities sliceとして再起動可能なplain dataで保持される。functionや秘密値をstateへ保存しない。

全Action

以下はAction Registryに実在するF3_Paymentの全actionである。クリックでpayload境界、状態、出力、回復を開ける。

capability.payment.bindBind paymentlocal or validated transition

payload: provider mode
状態: unbound → configured / ready
result: Capability engine の ok result、または明示的な validation / provider error。plan・receipt・stateは持続sliceへ返る。
recovery: error codeと状態を残し、必要に応じて再計画・再承認・retryへ戻る。

capability.payment.plan_checkoutPlan payment checkoutreversible preparation

payload: orderId productId amountMinor currency
状態: durable plan → approval_required
result: Capability engine の ok result、または明示的な validation / provider error。plan・receipt・stateは持続sliceへ返る。
recovery: error codeと状態を残し、必要に応じて再計画・再承認・retryへ戻る。

capability.payment.arm_checkoutArm payment checkoutreversible preparation

payload: checkoutId
状態: approval_required → armed
result: Capability engine の ok result、または明示的な validation / provider error。plan・receipt・stateは持続sliceへ返る。
recovery: error codeと状態を残し、必要に応じて再計画・再承認・retryへ戻る。

capability.payment.execute_checkoutExecute payment checkoutapproval boundary / external effect

payload: checkoutId
状態: armed → visible provider/result state
result: Capability engine の ok result、または明示的な validation / provider error。plan・receipt・stateは持続sliceへ返る。
recovery: 実行前にarm状態を要求する。失敗はengineが保持し、同一keyは重複実行を防ぐ。

capability.payment.plan_refundPlan payment refundapproval boundary / external effect

payload: checkoutId amountMinor currency reason
状態: durable plan → approval_required
result: Capability engine の ok result、または明示的な validation / provider error。plan・receipt・stateは持続sliceへ返る。
recovery: error codeと状態を残し、必要に応じて再計画・再承認・retryへ戻る。

capability.payment.arm_refundArm payment refundapproval boundary / external effect

payload: refundId
状態: approval_required → armed
result: Capability engine の ok result、または明示的な validation / provider error。plan・receipt・stateは持続sliceへ返る。
recovery: error codeと状態を残し、必要に応じて再計画・再承認・retryへ戻る。

capability.payment.execute_refundExecute payment refundapproval boundary / external effect

payload: refundId
状態: armed → visible provider/result state
result: Capability engine の ok result、または明示的な validation / provider error。plan・receipt・stateは持続sliceへ返る。
recovery: 実行前にarm状態を要求する。失敗はengineが保持し、同一keyは重複実行を防ぐ。

capability.payment.apply_webhook_eventApply payment webhook eventlocal or validated transition

payload: eventId type checkoutId signature
状態: state transition defined by the capability engine
result: Capability engine の ok result、または明示的な validation / provider error。plan・receipt・stateは持続sliceへ返る。
recovery: error codeと状態を残し、必要に応じて再計画・再承認・retryへ戻る。

Capability Spec

F3 Payment — Capability Spec

Provider-independent payment capability with Stripe test-mode binding contract, checkout intent lifecycle, server-only amount authority, webhook replay protection, and separate approval-required refunds. No card data handling.

Checkout States

State	Meaning
`draft`	Intent created locally.
`planned`	Checkout plan recorded.
`approval_required`	Awaiting human approval before provider call.
`session_created`	Provider session created (visible boundary crossed).
`pending`	Awaiting provider completion.
`paid`	Payment confirmed.
`failed`	Provider or validation failure.
`refunded`	Refund completed (separate approval path).
`cancelled`	Cancelled before provider execute.

Money Contract

Amounts are integer minor units (e.g. cents)
Currency is ISO 4217 alpha-3
Server-only product/amount authority via MIKAAIR_PAYMENT_ORDER_AUTHORITY
Idempotency key required for checkout and refund execute

Actions

Action	Flow
`bind`	Configure Stripe binding (test mode default)
`plan_checkout`	Create checkout plan with visible preview
`arm_checkout`	Human approval → armed
`execute_checkout`	Armed → provider session (mock adapter)
`plan_refund`	Separate approval-required refund plan
`arm_refund`	Human approval → armed
`execute_refund`	Armed → provider refund (mock adapter)
`apply_webhook_event`	Verify signature, replay-protect, update checkout state

Live Mode

Live mode permanently requires G4 human approval and cannot be entered by Worker/test automation. live_mode_blocked is non-recoverable without G4 gate.

Webhook Contract

Signature verification against STRIPE_WEBHOOK_SECRET env name
Event IDs recorded for replay protection
Provider state returned visibly in result

Environment Names (values never in repo)

Name	Role
`STRIPE_SECRET_KEY`	Server-only API key
`STRIPE_PUBLISHABLE_KEY`	Client-safe key
`STRIPE_WEBHOOK_SECRET`	Webhook signature secret
`MIKAAIR_PAYMENT_MODE`	`test` or `live`
`MIKAAIR_PAYMENT_ORDER_AUTHORITY`	Server product/amount authority JSON

Provider Binding

Reference adapter: Stripe contract mock at binding/adapter_contract.mjs. No live charges or card data.

binding / secret boundary

provider設定はbinding templateから参照する。環境変数は名前だけを扱い、値はsource repository・画面・reportに書かない。

環境変数名	扱い
`STRIPE_SECRET_KEY`	secret reference — 値は表示・保存しない
`STRIPE_PUBLISHABLE_KEY`	configuration reference — 値は表示・保存しない
`STRIPE_WEBHOOK_SECRET`	secret reference — 値は表示・保存しない
`MIKAAIR_PAYMENT_MODE`	configuration reference — 値は表示・保存しない
`MIKAAIR_PAYMENT_ORDER_AUTHORITY`	configuration reference — 値は表示・保存しない

webhookは署名とevent IDで検証する。返金はcheckoutと別の plan → arm → execute である。

source trace

../MikaAir LIGHTNESS/F_BUS_Capability/F3_Payment/spec/capability_spec.md 05fd10569a5a
../MikaAir LIGHTNESS/F_BUS_Capability/F3_Payment/binding/binding_manifest.template.json b4fb5763713e
../MikaAir LIGHTNESS/F_BUS_Capability/F3_Payment/agent.md 547e5e50ef0f
../MikaAir LIGHTNESS/F_BUS_Capability/runtime_bridge.mjs 7e7384638a41
../MikaAir LIGHTNESS/F_BUS_Capability/action_surface.mjs e5bae5f48648
../MikaAir LIGHTNESS/A_BUS_Action_Core/A2_State_Store/filesystem_store.mjs b1cc32d3f456
../MikaAir LIGHTNESS/F_BUS_Capability/F3_Payment/contract/index.mjs 3a283f667576
../MikaAir LIGHTNESS/F_BUS_Capability/F3_Payment/engine.mjs 3224a5bf86f4