Atlas wallet

One buyer account, saved cards across participating merchants, and explicit confirmation for every purchase.

Developer preview, prepared by Kyle Campbell. Apply migrations through 0021 and configure Stripe and the signed frontend context before enabling checkout. New catalog orders use authorization and capture on delivery; saved-card setup itself never makes a purchase. See Checkout & security for Elements and fraud controls. No live-card, issuer, cross-country or production-capacity certification is implied.

Scan a merchant QR and pay with your wallet

Scan the merchant’s Atlas Pay QR to open checkout.atlaspay.sh/m/test/{workspace} or /m/live/{workspace}. Enter the amount agreed with the merchant, then choose Sign in to use your Atlas wallet and continue with Google or email. Google returns you to that QR payment; the amount is kept in this browser for up to 30 minutes. If you are already signed in on the checkout site, your wallet loads automatically.

Choose one of your saved cards, continue to Stripe Elements, review the currency and total, and confirm the payment. Your bank may require additional verification. Signing in, choosing a card, or opening checkout does not charge it. You can also select Use a new payment method or pay as a guest. Expired cards cannot be selected.

Manage saved cards or Add a card to your wallet opens the wallet in the QR’s environment. After saving a card, use Return to your QR payment. Test and live wallets are separate; a test QR never uses a live card. Google sign-in is available at the checkout origin and does not require merchant onboarding.

Each saved-card attempt is bound to its buyer, merchant, amount, environment, and selected card. To change the amount or card after opening Elements, select Change amount or payment method, which first closes the earlier checkout. Retry an uncertain attempt using its original reference. Removing a wallet card also closes its open QR checkouts where possible; a payment already submitted may still complete. The temporary merchant card copy is cleaned up after cancellation or expiry, and the original saved card remains in your wallet.

QR payments collect the agreed amount immediately after confirmation; they do not use the catalog delivery-authorization flow.

For buyers

Open Your Atlas wallet. Sign in with an Atlas Pay account or create one there. Buying does not require business onboarding or a Stripe merchant account. Your buyer wallet is separate from the merchant workspace, and a bot workspace link code does not grant wallet access.

In Atlas chat, tap Add a card in the bot menu or say “add my card.” The bot opens the dedicated add-card page, with a clickable link as a fallback. Sign in only if needed, agree to save the card, then enter its details on Stripe. The add-card page skips the wallet-management list and keeps one primary action in view. After Stripe returns you to your wallet and the card appears, return to the chat. The bot does not claim success from a chat message or return URL.

Read and select the card-saving consent, then choose Add card with Stripe. Where Elements is enabled, Stripe's secure fields appear inside Atlas Pay; otherwise the existing Stripe-hosted page opens. Enter card details only in those Stripe fields. After setup, return to your wallet or select Refresh. Atlas retrieves and verifies the completed Checkout Session, its successful SetupIntent, buyer Customer, environment and payment-method ownership before displaying the card. Closing the browser does not lose the setup: reopening the wallet reconciles outstanding sessions. There is no platform setup webhook dependency in this preview.

The wallet displays only brand, last four digits and expiry, alongside an internal card reference. It is a list of saved payment methods, not a bank account or cash balance. Test and live wallets are separate. The dashboard's display toggle cannot turn a test wallet into a live one.

Pay for a merchant order

1. Open the merchant's complete Atlas wallet order link.
2. Sign in to your own buyer account. Review the merchant name, exact item/variant, quantity, shipping, tax and currency.
3. Select a saved card and agree to use it for this order.
4. Continue to the secure payment form and confirm there. Elements stays inside Atlas Pay; existing hosted checkouts open Stripe. Stripe may request bank authentication or let you choose another card within the same session.
5. Return to the order and refresh payment status. New catalog orders show funds authorized, not captured, until trusted delivery confirmation. A redirect, timeout or chat message is not proof of payment.

The first accepted selection binds that order to one buyer and one wallet card. A second browser tab resumes the same checkout; it does not create another payment. To use another card after selection, use the available payment controls in that same Stripe checkout. If it has closed or expired, ask the merchant to reconcile the old order before issuing another reference. The review expires after 23 hours; an already-created Stripe session lasts no longer than 24 hours from order creation.

Physical orders collect shipping details on Stripe for the countries the merchant supplied. Shipping and tax are merchant-calculated fixed amounts, not automatic carrier or tax quotes.

Declines and bank verification

Stripe displays authentication challenges and payment declines through its secure form. Atlas does not infer insufficient funds from a generic failure: only the processor/issuer can supply that reason. The order remains unconfirmed until Atlas verifies payment. Processing, failure, expiry, fraud review, refunds and disputes must not trigger automatic fulfillment.

This version does not charge directly from chat, attempt unattended purchases, or guarantee a card works with every merchant worldwide. Additional issuer checks and regional restrictions still apply.

Remove a card

Choose Remove and confirm. Atlas disables future use immediately in its database, then detaches the platform payment reference and closes open wallet checkouts where possible. Merchant-specific copies are detached as well. Payments already in progress may still complete; removing a card is not a refund or a subscription cancellation.

Cleanup failures remain recorded for scheduled retry. A removal request attempts up to five related copies immediately; the minute job retries up to two platform removals and two connected copies. Copies also become eligible for cleanup after their order's 24-hour window. Cleanup can be delayed by backlog or processor downtime; monitor it before live use. Keep at most 10 active cards or pending setups combined. Current security policy permits at most five new setups per buyer per hour, with supplementary IP/browser limits and same-wallet card deduplication. See Checkout & security.

For merchants and integrations

Create products and a server-priced catalog order using the existing orders:write permission. Add payment_flow: "atlas_wallet" to the order request. The default is still "hosted", preserving existing integrations.

{
  "payment_flow": "atlas_wallet",
  "reference": "shirt-order-1042",
  "items": [{"product_id":"prod_0123456789abcdef0123456789abcdef","quantity":1}],
  "shipping_amount": 500,
  "tax_amount": 0,
  "shipping_countries": ["US"],
  "success_url": "https://shop.example.com/thanks",
  "cancel_url": "https://shop.example.com/cart"
}

Replace the example product and website values. POST /api/v1/orders requires a server-side merchant key and a stable Idempotency-Key. Persist data.id. data.checkout_url is now an Atlas order-review link, and checkout_id remains null until the buyer continues. Do not remove the link's # fragment, put it in analytics, or log it. Treat the link as confidential: before it is claimed, its holder can review the quoted items and elect to pay. It is not an invoice identity-verification mechanism.

The merchant return URLs remain required and validated for contract compatibility; wallet payments return to the Atlas order-review page instead. Creating the quote alone neither clones a card nor creates a Stripe payment session. The buyer's private Stripe Checkout URL is never returned by merchant order/checkout readers or their callbacks. Revoked/expired merchant keys and changed/disabled connected accounts block new buyer confirmation.

For new on_delivery orders, order.authorized is the dispatch signal. Retrieve the current order and verify the expected amount/currency/reference, valid unexpired authorization and no settlement action before dispatch. Confirm actual delivery using a dedicated orders:deliver key; capture produces order.paid only after Stripe verification. Cancel an uncaptured hold using orders:cancel. See Delivery & payment holds. Existing automatic orders still require verified paid status with no refund/dispute before fulfillment. Deduplicate all shipment work by order ID.

WordPress and Wix gateway packages continue using their own catalogs and ordinary hosted checkout. They do not automatically gain the wallet flow or catalog synchronization.

How it connects

Buyer account       --owns--> Atlas wallet in D1
Atlas wallet        --uses--> Platform Stripe Customer / saved card
Merchant API        --creates--> Immutable catalog order
Buyer order review  --authorizes--> One order-specific card copy
Connected account   --authorizes--> Stripe-hosted card hold
Verified hold       --notifies--> Merchant dispatch webhook
Delivery confirmed  --triggers--> Capture of the existing hold

1. Buyer -> Atlas Pay: Consent to save a card
2. Atlas Pay -> Stripe platform: Create hosted setup session
3. Buyer -> Stripe: Enter card and complete bank verification
4. Atlas Pay -> Stripe: Verify session, SetupIntent and ownership
5. Atlas Pay -> D1: Save payment reference and consent record

6. Merchant -> Atlas Pay: Create priced wallet order with retry key
7. Buyer -> Atlas Pay: Review order and select own saved card
8. Atlas Pay -> D1: Atomically claim order for buyer and card
9. Atlas Pay -> Stripe Connect: Clone card for this order
10. Atlas Pay -> Stripe Connect: Create one hosted payment session
11. Buyer -> Stripe: Confirm payment or resolve a decline/challenge
12. Stripe -> Atlas Pay: Send signed connected-account event
13. Atlas Pay -> Stripe: Verify current checkout and authorization
14. Atlas Pay -> Merchant: Send signed order.authorized event
15. Merchant -> Atlas Pay: Recheck authorization before dispatch
16. Delivery service -> Atlas Pay: Attest actual delivery
17. Atlas Pay -> Stripe: Capture the existing authorization
18. Atlas Pay -> Merchant: Send order.paid after capture verification

Payments remain direct charges on the original connected account. This does not introduce destination charges, a platform cash balance, or a change of merchant-of-record model. Stripe stores a separate card copy and Customer in that connected account for the approved order. The copy is not continuously synchronized with the platform card. Atlas tracks it for revocation/expiry cleanup; the merchant retains its payment records.

Buyer API boundary

These same-origin web endpoints use the signed-in buyer's session cookie, not a merchant API key. Mutation requests require the configured frontend Origin and are limited to 8 KiB. They are application endpoints, not public money-moving MCP tools.

The Worker paths replace /api/atlas with /api. Missing session returns 401, wrong origin 403, invalid consent/body 400, unavailable/foreign resources 404, and unsafe state changes 409. An unavailable processor returns a sanitized 503. Retry setup with the same request UUID and payment with the same order/card. Never treat a failed HTTP response as evidence that no payment was created. Unknown operations older than 23 hours require reconciliation, not a new processor request using an aged idempotency key.

Bot entry points

/addcard, “add my card,” “save my debit card,” and similar setup requests open the secure add-card page. /wallet shows the wallet link and an Add a card button. /buy <complete Atlas wallet order link> opens a validated order review. These commands require the SDK to positively identify a private chat. They neither accept card details nor call a charge API. Native opening always uses the configured HTTPS frontend, never an arbitrary URL supplied in the message. Older clients keep a clickable fallback. Natural-language buying requests ask for a merchant order link; product discovery, variant negotiation and native Atlas app checkout are follow-up work. The public documentation MCP remains read-only, including this guide and its Markdown export.

Setup and launch checklist

1. Back up D1 and apply migrations 0006 through 0021 in order, then deploy the updated Worker and frontend to staging. No migrations are applied by a frontend build. Follow the separate delivery launch checklist for STRIPE_DELIVERY_PAYMENT_METHOD_CONFIGURATION, capture/cancel permissions and authorization event handling.
2. In each platform Stripe environment, create a dedicated payment-method configuration for wallet setup with cards enabled and unsupported non-card methods disabled. Set its pmc_... ID as STRIPE_TEST_WALLET_PAYMENT_METHOD_CONFIGURATION or STRIPE_LIVE_WALLET_PAYMENT_METHOD_CONFIGURATION in the backend, matching that environment’s key. Single-mode deployments can use STRIPE_WALLET_PAYMENT_METHOD_CONFIGURATION. Without a matching configuration, card setup and wallet-order creation fail closed. The source does not hardcode payment_method_types.
3. Review the restricted backend key permissions for platform Customers, Checkout Sessions and PaymentMethods, plus connected-account payment/refund/review access. Add only the required permissions. Keep secret keys server-side. Elements needs the matching NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY; both frontend server and Worker need the same server-only ATLAS_CHECKOUT_CONTEXT_SECRET. Enable NEXT_PUBLIC_ATLAS_ELEMENTS_ENABLED=true only after all backend settings are ready.
4. Keep BETTER_AUTH_SECRET, FRONTEND_URL, the connected-account webhook secret and existing minute cron correct. Signing-secret rotation invalidates old wallet review links as well as affecting existing auth/callback encryption; coordinate it deliberately.
5. Set ATLAS_PAY_WEB_URL on the bot to the same deployed frontend origin. Deploy the bot commands separately. Native Atlas mobile source is outside this repository.
6. Complete Stripe test-mode acceptance with two connected merchants: setup, redisplay of the cloned card, explicit payment confirmation, 3DS, insufficient-funds decline, cancellation, network loss, duplicate submission, shipping capture, refund/dispute, card removal during an open checkout and cleanup recovery.
7. Review consent/privacy text and regional SCA behavior, monitor cleanup backlog and callback backlog, then separately authorize live readiness. Automated fixtures are not substitutes for these checks.

References: Stripe hosted setup, saved-card redisplay, direct-charge card sharing.