Integrator acceptance checklist - R1-R9
Not in the preview yet. This feature is built in the repository but is off in the v2.2.6 preview (test mode). Do not treat this page as available on a preview core. See ../preview.md and the release notes.
The acceptance bar for any integration that touches Dynamo settlement. Every item is testable, and most are enforced by machinery you can run yourself. Integration happens in Control Mode, on a local or test chain and in Stripe TEST mode. Real money is release-gated in this release: live credit card keys are refused, and a stablecoin mode off a local chain starts only when the operator allows that mode and the vault's owner and fee collector are Safe multisigs with a threshold of two or more.
| # | Requirement | Where it bites | Verify with |
|---|---|---|---|
| R1 | Idempotent event handling - dedupe on the stable event id (Dynamo-Event-Id; x-dynamo-event-id on merchant API subscriptions) | Your webhook consumer | make demo-webhook-dupes |
| R2 | Credit on settlement.final only - checkpointed is pending, never a credit signal | Consumer + polling logic | Webhooks · Merchant API |
| R3 | Duplicate/reorder tolerance - delivery is at-least-once; treat settlement amounts as cumulative monotone values | Your webhook consumer | make demo-webhook-dupes |
| R4 | Conformance-tested x402 surface - the full catalog including merchant protection, with the pinned report artifact | Any 402-speaking endpoint you expose | make conformance |
| R5 | Use the serviceNode verification surface - verify allowances aimed at you; never trust a caller's self-report | Your service | Merchant API |
| R6 | Self-contained onboarding per funding mode - Control needs nothing; escrow needs a wallet; card needs one Stripe TEST/platform onboarding | Your ops runbook | Quickstarts |
| R7 | Asset-denominated amounts - settled amounts are micro units of the funding asset; units price work, not money | Your ledger mapping | Merchant API |
| R8 | Versioned-interface discipline - pin schema versions; additive changes arrive as minor bumps with CHANGELOG entries; breaking changes carry deprecation notes | Your parsers | Package CHANGELOGs |
| R9 | Sandbox/testnet parity - the surfaces answer the same shapes whichever rail is behind them; keep keys and endpoints in configuration, not code (production rails are release-gated) | Your deployment config | Testnet · Card sandbox |
The shape of a passing integration
- Verify offline, serve, meter async. Allowance credentials verify
in-process against pinned signers; the request path never blocks on a network call; failed verification is a 402, not a fallback.
- Never bill failed work. A failed call, failed delivery, or SLA-failed
unit costs the buyer nothing - use free pre-checks (the stream's headroom(); the MCP adapter's estimateUnits) and two-phase metering (reserve/confirm/cancel on a stream) where delivery can fail.
- Reconcile to the unit. Every session ends with the engine's billed
total equal to the settlement layer's record. If your integration cannot produce that line, it is not done.
- Keep evidence. The evidence export gives you an
offline-verifiable file per budget - the artifact you want already assembled when a counterparty dispute or card-network inquiry arrives.