MERCHANT STATE
Keep order authority in your own database.
PBE proves a signed transfer. Your application still owns product identity, customer state, fulfilment state, refunds, shipping, entitlements and every other business rule.
Minimum order fields
| Field | Purpose |
|---|---|
| reference | Unique merchant order/payment reference. |
| recipient | Expected merchant PBE address. |
| amount_base_units | Exact expected PBE amount in integer base units. |
| required_confirmations | Merchant settlement policy for this order. |
| payment_txid | Matched canonical transaction once observed. |
| payment_state | Unpaid / pending / confirming / confirmed / reorged policy state. |
| fulfilled_at | Idempotency guard; null until the business action is committed. |
Fulfil atomically
For automatic fulfilment, lock the order row or use an equivalent atomic update. Re-check that the exact PBE tuple matches, ensure fulfilled_at is still null, apply the business grant, set the paid/fulfilled state, and commit together.
How the included examples differ
The Coffee Mug example intentionally uses a PHP session so the browser/server trust boundary is easy to inspect and ships a no-op database.sql. The Golden Sword example demonstrates automatic fulfilment using merchant-owned MySQL tables and ships the required schema for manual import.
PBE node database is separateThis page describes your store/order database. The node's own chain database is documented under Node Operators → Database architecture.