Overview
@elata-biosciences/app-payments lets your app open Elata’s checkout and
check what the user owns. Elata runs checkout, takes payment in USDC, and
records ownership. Your app never touches wallets or payment details.
Create your catalog
Open My Apps → your app → Edit → Commerce → Products. Owners and authorized team members can create and manage the catalog themselves.
Save the product, then copy its assigned
contentId into your integration. The identifier is stable and cannot be edited. Products can be edited or deactivated rather than deleted. Deactivation stops new sales; keep applying existing owners’ benefits, including when the item no longer appears in the active catalog.
The dashboard accepts ordinary amounts such as 1.00. Product APIs and catalog responses use integer USDC base units: "1000000" means 1 USDC. Creating a catalog entry does not implement its benefit in your app.
Checkout must be configured for the deployment. The app checkout described here pays USDC on Base through the splitter. See What’s live before testing payments.
The correct flow
Gate your UI on ownership first, then purchase, then apply the benefit.requestPurchase records that the user owns an item. Your app decides what
owning it does.
Things to know
Branch on status, never on txHash
Branch on status, never on txHash
If the user already owns the item, Elata skips payment and returns
{ status: "success", txHash: "" }. Code that checks if (result.txHash) will mishandle this.Two price formats
Two price formats
CatalogItem.priceUsdc is in USDC base units (6 decimals): "50000" is $0.05. RequestPurchaseInput.priceUsdc is a free-form display hint Elata ignores. Elata always charges the catalog price.Items are one-time unlocks
Items are one-time unlocks
Each item is bought once. Consumables (spend-per-use balances) and recurring billing aren’t supported through items. For recurring revenue use a subscription plan.
Timeouts
Timeouts
requestPurchase waits up to 5 minutes for the user to finish checkout. getCatalog, getOwnedItems, and hasItem default to 10 seconds. Outside Elata, use a mock host for local tests. Treat an ownership-query failure as unknown ownership: offer a retry or sign-in action, and never grant a paid benefit merely because the query timed out.Errors
Calls reject only withAppPaymentsError, which has a code:
A normal
cancelled or error purchase outcome resolves; it doesn’t reject.
Security model
- Elata’s purchase records are created after server-side payment verification. Your UI should use host ownership queries as its source of truth.
- Your app never sees payment details, wallet keys, or session tokens.
- Replaying a recording request with the same
requestIdis idempotent. This does not make sending a second on-chain payment safe. - The splitter deducts the configured platform fee and sends the creator’s share to the payout wallet. See Revenue and payouts.
Try it
examples/iap-demo: one self-contained HTML file with a built-in mock store, so you can run the full flow locally.- Package README on npm
Payment and UI states
Handle success, cancellation, and errors separately. Prevent overlapping purchase attempts. A successful payment and a recorded entitlement are separate steps; unlock only after Elata reports success. If a payment settles but recording fails, keep the transaction details and direct the user to billing help. Do not automatically send another payment. The checkout retries temporary indexing delays, but recovery from every recording failure is not guaranteed. Ownership queries can require authentication. Onnot_authenticated, ask the user to sign in; on a lookup failure, show a retry state. Do not silently treat unknown ownership as a confirmed non-owner.
The app does not connect wallets itself. Elata checkout manages wallet connection and payment confirmation, including the embedded-wallet interface when used. Credits for metered features are not an alternative payment balance for these items.
Test your integration
- Reopen the app and restore already-owned benefits from host ownership.
- Show Use or Owned for purchased items and Buy for available unowned items.
- Handle a successful already-owned response with an empty transaction hash.
- Handle signed-out, cancelled, insufficient-funds, unavailable-checkout, and lookup-error states.
- Deactivate an item and verify that existing owners can still use its benefit.