Skip to main content

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

If the user already owns the item, Elata skips payment and returns { status: "success", txHash: "" }. Code that checks if (result.txHash) will mishandle this.
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.
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.
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 with AppPaymentsError, 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 requestId is 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

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. On not_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.
For subscription access, use Subscriptions, rather than simulating recurring billing with repeated item purchases.