First real app tutorial

This is the canonical ATM app integration path. At the end, the app has a test environment, a receiver, a successful checkout path, and a redrive-safe event handler that fulfills only from ATM truth.

1. 01

   Register app

   Add the app role to the app DID and keep configuration in test mode.

2. 02

   Configure test

   Enable modules, add a receiver, copy the test secret, and subscribe to events.

3. 03

   Request approval

   Ask the creator to approve this app, environment, fee cap, payment types, and public-record behavior.

4. 04

   Create checkout

   Create an app order, build the private ATM checkout envelope, and redirect the buyer.

5. 05

   Receive event

   Verify payment.completed, deduplicate the delivery id, and store the ATM payment id.

6. 06

   Fulfill

   Mark the app order paid and move toward live only after redrive and refund paths pass.

• An allowlisted app DID with access to app registration.
• A server runtime that can keep app secrets private.
• Optionally, a tunnel or deployed URL if you want signed webhook wake-ups.
• A test recipient that has completed payment setup when testing paid checkout.
• A plan for idempotency keys and delivery id deduplication.

1. 01

   Sign in

   Use the DID that represents the app, not an individual developer's personal account.

2. 02

   Request app role

   ATM adds the app role while preserving payer or creator roles on the same DID.

3. 03

   Complete profile

   Name, avatar, description, and app URL become the app-facing identity in ATM.

4. 04

   Stay in test

   The app dashboard defaults to test configuration for modules, secrets, and receivers.

The starter kit proves local receiver verification and status handling before you wire application-specific order logic.

cd examples/atm-node-app
cp .env.example .env
npm run build --prefix ../../packages/app-node
npm install
npm run typecheck
npm run smoke
npm run dev

curl http://localhost:8787/health

The compact source file at docs/developer/examples/happy-path-app.tsshows the same app-order, checkout, webhook, and fulfillment sequence without the full starter-kit HTTP server.

Before an app can accept payments for a creator, the creator approves that app in ATM. Approval is scoped to app DID, recipient DID, environment, payment types, app fee cap, and public-record behavior.

const approval = await atm.requestRecipientApproval({
  recipientDid,
  environment: "test",
  paymentTypes: ["shop"],
  feeShareBps: 300,
  publicRecords: {
    enabled: true,
    defaults: {
      attestation: "public"
    }
  },
  requestReason: "Enable Example App checkout",
  setupReturnUrl: "https://app.example/settings/payments"
});

if (approval.status !== "approved") {
  return Response.redirect(approval.dashboardUrl);
}

Fee decreases stay within scope. New payment types, fee increases, or changes that make records more public move the approval to needs-review until the creator confirms.

For a real app, create an app order first, then create the ATM checkout envelope from that order. The browser should receive only the returned ATM checkout URL.

const order = await createAppOrder({
  recipientDid,
  amountCents: 1200,
  currency: "usd"
});

const checkout = await atm.initiatePayment({
  environment: "test",
  recipient: order.recipientDid,
  amount: order.amountCents,
  currency: order.currency,
  paymentType: "shop",
  metadata: { appOrderId: order.id },
  returnUrl: "https://app.example/orders/" + order.id,
  cancelUrl: "https://app.example/support"
});

await orders.saveAtmStatusToken(order.id, checkout.token);
return Response.redirect(checkout.url);

Complete a test checkout and verify that a backend worker can load the stored initiation token, poll canonical status, and apply the terminal result idempotently. If you enable push, also verify that a signed event only wakes the same reconciliation path.

• The status token is stored server-side before the browser redirect.
• The worker polls with app service-auth and never uses the browser checkout token.
• Reprocessing the same completed status does not fulfill twice.
• Optional receivers validate signature/service-auth and wake the poller without directly fulfilling.

• Guest and signed-in payer checkout paths pass.
• The configured canonical XRPC receiver or compatibility webhook path passes.
• Failed delivery and redrive pass.
• Refund/cancel/subscription-change paths pass for enabled modules.
• Private data stays off protocol and out of public logs.
• Live secrets are separate from test secrets.