Top-up
POST /api/wallet/paypal/create
Creates a bounded $1–$250 provider order. Send dollars as form data. The server derives the canonical Perutah amount.
B"H · Wallet integration
One treasury. Explicit contracts.
Use the shared Wallet for account Perutahs. Never promote local game coins, browser counters, or save-file currency into purchased account value.
Balance provenance
Total = promotional + purchased.
balance remains the backwards-compatible total. promotionalBalance receives welcome grants, daily refill, rewards, and development credit. purchasedBalance receives verified paid top-ups.
The promotional cap applies only to promotional value. Spending consumes promotional value first and records the exact bucket split in ledger metadata.
Read
GET /api/wallet/balance
Requires an authenticated Awtsmoos account. Returns total and provenance balances, promotional refill/cap state, coin decomposition, and recent ledger entries.
{ "wallet": { "balance": 1600, "promotionalBalance": 600, "purchasedBalance": 1000 } }
Capture
POST /api/wallet/paypal/capture
Send orderId. The server binds provider evidence to the authenticated account, verifies captured USD, and credits purchased value idempotently.
Mutation header
X-Awtsmoos-Wallet-Action: 1
PayPal create/capture and commerce purchase require POST plus this custom header. Ordinary navigation and cross-origin HTML forms cannot become Wallet mutations.
Roadmap
GET /api/wallet/commerce/catalog
Returns twenty game/app SKU proposals. Every current entry is unavailable until its receiving product implements real fulfillment.
Ownership
GET /api/wallet/commerce/entitlements
Returns the authenticated account's durable entitlements and recent commerce receipts without mutating Wallet value.
Purchase boundary
POST /api/wallet/commerce/purchase
Submit only server-known skuId and stable idempotencyKey plus the Wallet action header. Price and availability come only from the server catalog.
skuId=example.server.sku&idempotencyKey=stable-operation-key
Development boundary
Mock purchases are not a production feature.
The internal mock route is disabled by default and requires explicit development/test opt-in. Customer interfaces never depend on it.
Game law
Local gameplay currency never becomes paid account value.
Merkava Prutahs, Shema Strike coins, Sulam Shefa, Brick Blast Perutas, and other game-state currencies remain inside their gameplay systems.