Payments

An app takes payments into its owner's Stripe account — no Stripe key in the code. Ask the agent ("add a checkout for the courses") and it builds the payment flow with totalum.payments (SDK). These calls are the account owner's.

1. Try it in the preview right away. The preview always takes Stripe test cards, with no setup: pay with 4242 4242 4242 4242, any future date and any CVC. No real money moves.
2. Publish, then connect your Stripe to receive real payments — one click in the project's Payments window, or Create Payments Onboarding Link: Stripe asks for your business and bank details on its own page and the money goes to your Stripe account.
3. Switch the published site to real payments when you are ready (Set Payments Mode). The preview stays in test mode.

Payment events arrive by themselves. Renewals, cancellations, failed payments and refunds reach the app's own /api/webhooks/stripe route with nothing to set up, on the site where the checkout was made: test payments made in the preview go to the preview, test payments made on the published site (before it takes real payments) and real payments go to the published site (on its custom domain if it has one). They are signed by Totalum, and the app checks them with totalum.webhooks.verify (SDK). To also send them to another address (your own server, Zapier…), set the optional project webhook (in the platform: Payments → Advanced).

Checkout opens in a new tab. Stripe's payment page cannot run inside the platform's preview frame, so the app opens Checkout and the customer portal in a new tab unless you ask otherwise.

Already have a Stripe account and prefer your own keys? Add your secret key as a project secret named STRIPE_SECRET_KEY and ask the agent to use it ("take payments with my own Stripe key"). The agent then calls Stripe from the app's server only, never from the browser. To receive Stripe's events, also add your endpoint's signing secret as STRIPE_WEBHOOK_SECRET and add https://<your site>/api/webhooks/stripe as an endpoint in your Stripe Dashboard: with your own keys that route checks Stripe's signature instead of Totalum's. Whether it charges test or real cards is up to the key (sk_test_… or sk_live_…).

curl -H "api-key: tlm_sk_your_key" \
  "https://builder-api.totalum.app/api/v1/vcaas/projects/barber-bookings/payments/status?mode=live"

const res = await fetch("https://builder-api.totalum.app/api/v1/vcaas/projects/barber-bookings/payments/status?mode=live", {
  headers: {
    "api-key": process.env.TOTALUM_API_KEY,
  },
});
const { errors, data } = await res.json();

{ "errors": null, "data": { "enabled": true, "mode": "connect", "accountId": "acct_1Q2w3E4r", "livemode": true, "chargesEnabled": true, "payoutsEnabled": true, "detailsSubmitted": true, "requirements": { "currentlyDue": [], "pastDue": [], "eventuallyDue": [] }, "liveEnabled": false, "disconnectedAt": null } }

curl -X POST \
  -H "api-key: tlm_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"returnUrl":"https://yourapp.com/payments/done","refreshUrl":"https://yourapp.com/payments/retry","country":"ES"}' \
  "https://builder-api.totalum.app/api/v1/vcaas/projects/barber-bookings/payments/onboarding-link"

const res = await fetch("https://builder-api.totalum.app/api/v1/vcaas/projects/barber-bookings/payments/onboarding-link", {
  method: "POST",
  headers: {
    "api-key": process.env.TOTALUM_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "returnUrl": "https://yourapp.com/payments/done",
    "refreshUrl": "https://yourapp.com/payments/retry",
    "country": "ES"
  }),
});
const { errors, data } = await res.json();

{ "errors": null, "data": { "url": "https://connect.stripe.com/setup/e/acct_1Q2w3E4r/…", "expiresAt": "2026-10-08T13:10:00.000Z" } }

curl -X PUT \
  -H "api-key: tlm_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"mode":"live"}' \
  https://builder-api.totalum.app/api/v1/vcaas/projects/barber-bookings/payments/mode

const res = await fetch("https://builder-api.totalum.app/api/v1/vcaas/projects/barber-bookings/payments/mode", {
  method: "PUT",
  headers: {
    "api-key": process.env.TOTALUM_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "mode": "live"
  }),
});
const { errors, data } = await res.json();

{ "errors": null, "data": { "mode": "live" } }