How it works
The objects involved and the lifecycle of a payment, end to end.
Core objects
- Wallet — a Stellar address you own that we monitor for incoming payments.
- Product — what a customer pays for, tied to a wallet, an asset, and a price (fixed or customer-chosen).
- Payment link — a hosted page for a product with a unique
memoused to match payments. - Payment — a confirmed on-chain payment recorded against a product.
- Webhook — your endpoint that receives signed events.
Payment lifecycle
Pay
with memo
Detect
poll Horizon
Match
by memo
Verify
asset + amount
Notify
payment.completed
When a customer opens a payment link, they send a normal Stellar payment to your wallet address, including the memo shown on the page. From there:
- 1We continuously poll Stellar Horizon for incoming payments to your monitored wallets.
- 2Each incoming payment is matched to a payment link by its
memo. - 3We verify the wallet, asset, and amount (for fixed-price products), then record a
PaymentasPENDING→CONFIRMED. - 4A signed
payment.completedwebhook is delivered to your endpoint, with automatic retries on failure.
Because payments are matched by memo, customers must include the memo exactly. The hosted payment page makes this automatic (QR + copy), so prefer payment links over sharing a raw address.
Matching & verification
- Wallet— the payment must arrive at the product's configured wallet.
- Asset — asset code (and issuer for non-XLM) must match the product.
- Amount — fixed-price products require at least the price; custom products accept any amount above the optional minimum.
- Idempotency — each transaction is recorded at most once.
Non-custodial. Funds never touch StellarHooks — they settle directly into your wallet. We only generate payment requests and verify them on-chain.
Next
Explore the API reference to start building.