Payments (totalum-sdk/payments)

import … from 'totalum-sdk/payments' — or the same namespace on totalum from 'totalum-sdk'. Install, configuration and errors: Totalum SDK.

Take payments and subscriptions with Stripe on the project owner's own Stripe account (Stripe Connect), without handling card data: create a hosted Checkout, send the buyer to its url, and read the result back. The owner connects Stripe once with onboardingLink(). The preview and the sandbox use Stripe test mode; the published site uses live mode once the owner switched it on. Payment events reach the app's own POST /api/webhooks/stripe with no setup, signed by Totalum (verify them with totalum.webhooks.verify).

const { url } = await totalum.payments.createCheckout({
  mode: 'payment',
  lineItems: [{ name: 'Pro plan', unitAmount: 1900, currency: 'eur', quantity: 1 }],
  successUrl: 'https://acme.totalum.app/thanks?session_id={CHECKOUT_SESSION_ID}',
  cancelUrl: 'https://acme.totalum.app/pricing',
});

#totalumPayments

totalumPayments(options?: TotalumClientOptions): TotalumPayments

Creates the payments namespace (the same object as totalum.payments, scope payments): Stripe Connect charges on the project's own connected account. Card data never passes through here — send buyers to the hosted Checkout url; card fields are refused with CARD_DATA_NOT_ACCEPTED. Stripe test mode on the preview and in the sandbox; live mode only on the published site, once the owner onboarded and switched live on. Payment events (payments.<Stripe type>) reach the app's own POST /api/webhooks/stripe with no setup — test mode's on the preview, live mode's on the published site — signed by Totalum: verify them with totalum.webhooks.verify.

Parameters

Returns TotalumPayments — The payments namespace: the methods below.

Example

import { totalumPayments } from 'totalum-sdk/payments';

const payments = totalumPayments();
const status = await payments.getStatus();

The namespace's type is exported as TotalumPayments (import type { TotalumPayments } from 'totalum-sdk/payments').

#payments.getStatus

payments.getStatus(): Promise<PaymentsStatus>

Whether the project's Stripe account can take payments right now: use it to show "Connect Stripe" to the owner or to hide a Buy button while payments are off. Free.

Returns Promise<PaymentsStatus> — The state of the connected Stripe account in the current mode (test on the preview, live on the published site).

Errors — besides the errors every call can throw:

Example

const status = await totalum.payments.getStatus();
if (!status.chargesEnabled) return <p>Payments are not set up yet.</p>;

Result:

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

#payments.onboardingLink

payments.onboardingLink(input: OnboardingLinkInput): Promise<OnboardingLinkOutput>

A single-use link to Stripe's hosted onboarding, where the project owner connects (or updates) the Stripe account the app's payments go to. Only for the owner: the coding agent's sandbox key is refused. The live account can only be connected once the project is published.

Parameters

Returns Promise<OnboardingLinkOutput> — The onboarding URL to redirect the owner to, and when it expires.

Errors — besides the errors every call can throw:

Example

const { url } = await totalum.payments.onboardingLink({
  returnUrl: 'https://acme.totalum.app/admin/payments?connected=1',
  refreshUrl: 'https://acme.totalum.app/admin/payments',
  country: 'ES',
});

Result:

{ "url": "https://connect.stripe.com/setup/e/acct_1QZ3kPQm4n8Xa2Lb/Xq3VbD9yPpLk", "expiresAt": "2026-10-11T18:05:00.000Z" }

#payments.createCheckout

payments.createCheckout(input: CheckoutInput): Promise<CheckoutOutput>

Creates a Stripe Checkout page for a one-off payment (payment), a subscription (subscription) or saving a card for later (setup), and returns its URL: redirect the buyer there. Put your own ids (order, user) in metadata to find them again on the return page or in the webhook. A subscription needs a recurring price: an inline item with recurring: { interval: 'month' }, or a priceId; its metadata is also set on the subscription.

Parameters

Returns Promise<CheckoutOutput> — The Checkout Session id and the URL to redirect the buyer to.

Errors — besides the errors every call can throw:

Examples

// src/app/api/checkout/route.ts
const { url } = await totalum.payments.createCheckout({
  mode: 'payment',
  lineItems: [{ name: 'Concert ticket', unitAmount: 2500, currency: 'eur', quantity: 2 }],
  successUrl: 'https://acme.totalum.app/orders/ord_42?session_id={CHECKOUT_SESSION_ID}',
  cancelUrl: 'https://acme.totalum.app/cart',
  customerEmail: 'ana@example.com',
  metadata: { orderId: 'ord_42' },
});
return Response.redirect(url, 303);

Result:

{ "id": "cs_test_a1B2c3D4e5F6g7H8i9J0", "url": "https://checkout.stripe.com/c/pay/cs_test_a1B2c3D4e5F6g7H8i9J0#fid…" }

// a monthly subscription with a 14-day trial
const { url } = await totalum.payments.createCheckout({
  mode: 'subscription',
  lineItems: [{ name: 'Pro', unitAmount: 1900, currency: 'eur', quantity: 1, recurring: { interval: 'month' } }],
  trialDays: 14,
  successUrl: 'https://acme.totalum.app/billing?session_id={CHECKOUT_SESSION_ID}',
  cancelUrl: 'https://acme.totalum.app/pricing',
  metadata: { userId: user.id },
});

#payments.getCheckout

payments.getCheckout(sessionId: string): Promise<CheckoutSession>

Reads a Checkout Session back, to confirm a payment on the page Stripe returns the buyer to (successUrl with ?session_id={CHECKOUT_SESSION_ID}): when paymentStatus is 'paid', mark the order paid — no webhook needed. A subscription checkout also gives subscriptionId and customerId: store both on the member.

Parameters

Returns Promise<CheckoutSession> — The session's status, amount, your metadata and the ids it created.

Errors — besides the errors every call can throw:

Example

// src/app/orders/[id]/page.tsx
const session = await totalum.payments.getCheckout(searchParams.session_id);
if (session.paymentStatus === 'paid') await markOrderPaid(session.metadata.orderId);

Result:

{
  "id": "cs_test_a1B2c3D4e5F6g7H8i9J0",
  "status": "complete",
  "paymentStatus": "paid",
  "amountTotal": 5000,
  "currency": "eur",
  "metadata": { "orderId": "ord_42" },
  "paymentIntentId": "pi_3QZ4mNPQm4n8Xa2L0x1y2z3a",
  "customerEmail": "ana@example.com",
  "clientReferenceId": null,
  "customerId": null,
  "subscriptionId": null
}

#payments.customerPortalLink

payments.customerPortalLink(input: CustomerPortalLinkInput): Promise<CustomerPortalLinkOutput>

A link to Stripe's hosted customer portal, where a subscriber updates their card, downloads invoices or cancels their subscription. Show it as "Manage billing".

Parameters

Returns Promise<CustomerPortalLinkOutput> — The portal URL to redirect the customer to.

Errors — besides the errors every call can throw:

Example

const { url } = await totalum.payments.customerPortalLink({
  customerId: member.stripeCustomerId,
  returnUrl: 'https://acme.totalum.app/account',
});

Result:

{ "url": "https://billing.stripe.com/p/session/test_YWNjdF8xUVozaw…" }

#payments.subscriptions.get

payments.subscriptions.get(subscriptionId: string): Promise<Subscription>

Reads a subscription: give access while status is 'active' or 'trialing'; currentPeriodEnd is the next renewal (or the end of access when cancelAtPeriodEnd is true).

Parameters

Returns Promise<Subscription> — The subscription's status, renewal date and metadata.

Errors — besides the errors every call can throw:

Example

const sub = await totalum.payments.subscriptions.get(member.subscriptionId);
const active = sub.status === 'active' || sub.status === 'trialing';

Result:

{
  "id": "sub_1QZ5aBPQm4n8Xa2LcD3eF4gH",
  "status": "active",
  "customerId": "cus_R2x9YpL0aBcDeF",
  "cancelAtPeriodEnd": false,
  "currentPeriodEnd": "2026-11-11T17:40:00.000Z",
  "canceledAt": null,
  "metadata": { "userId": "user_42" }
}

#payments.subscriptions.update

payments.subscriptions.update(subscriptionId: string, input: SubscriptionUpdateInput): Promise<Subscription>

Cancels a subscription at the end of the paid period (cancelAtPeriodEnd: true, the usual "Cancel" button: the member keeps access until then), or undoes that (false).

Parameters

Returns Promise<Subscription> — The updated subscription.

Errors — besides the errors every call can throw:

Example

const sub = await totalum.payments.subscriptions.update(member.subscriptionId, { cancelAtPeriodEnd: true });

Result:

{
  "id": "sub_1QZ5aBPQm4n8Xa2LcD3eF4gH",
  "status": "active",
  "customerId": "cus_R2x9YpL0aBcDeF",
  "cancelAtPeriodEnd": true,
  "currentPeriodEnd": "2026-11-11T17:40:00.000Z",
  "canceledAt": null,
  "metadata": { "userId": "user_42" }
}

#payments.subscriptions.cancel

payments.subscriptions.cancel(subscriptionId: string): Promise<Subscription>

Cancels a subscription immediately: no more charges, status: 'canceled' at once, access ends now. To let the member keep the period they paid for, use update(id, { cancelAtPeriodEnd: true }) instead.

Parameters

Returns Promise<Subscription> — The canceled subscription.

Errors — besides the errors every call can throw:

Example

const sub = await totalum.payments.subscriptions.cancel('sub_1QZ5aBPQm4n8Xa2LcD3eF4gH');

Result:

{
  "id": "sub_1QZ5aBPQm4n8Xa2LcD3eF4gH",
  "status": "canceled",
  "customerId": "cus_R2x9YpL0aBcDeF",
  "cancelAtPeriodEnd": false,
  "currentPeriodEnd": "2026-11-11T17:40:00.000Z",
  "canceledAt": "2026-10-11T18:02:11.000Z",
  "metadata": { "userId": "user_42" }
}

#payments.refunds.create

payments.refunds.create(input: RefundInput): Promise<RefundOutput>

Refunds a payment, in full or in part. The buyer gets the money back on their card in a few days.

Parameters

Returns Promise<RefundOutput> — The refund's id, status and amount.

Errors — besides the errors every call can throw:

Example

const refund = await totalum.payments.refunds.create({
  paymentIntentId: 'pi_3QZ4mNPQm4n8Xa2L0x1y2z3a',
  amount: 2500,
  reason: 'requested_by_customer',
});

Result:

{ "id": "re_3QZ6bCPQm4n8Xa2L1k2l3m4n", "status": "succeeded", "amount": 2500, "currency": "eur" }

#CheckoutInput

What a Checkout page sells and where it sends the buyer, for payments.createCheckout().

#CheckoutOutput

The Checkout page created by payments.createCheckout().

#CheckoutSession

A Checkout Session read back with payments.getCheckout().

#CustomerPortalLinkInput

The input of payments.customerPortalLink().

#CustomerPortalLinkOutput

The answer of payments.customerPortalLink().

#OnboardingLinkInput

The input of payments.onboardingLink().

#OnboardingLinkOutput

The answer of payments.onboardingLink().

#PaymentsStatus

The state of the project's Stripe account, from payments.getStatus().

#RefundInput

The input of payments.refunds.create().

#RefundOutput

A refund, from payments.refunds.create().

#Subscription

A Stripe subscription, from payments.subscriptions.*.

#SubscriptionUpdateInput

The change payments.subscriptions.update() makes.