Payments

import { createClient } from "@resultdev/sdk";

export const backend = createClient({
  baseUrl: process.env.NEXT_PUBLIC_BACKEND_URL!,
  anonKey: process.env.NEXT_PUBLIC_BACKEND_ANON_KEY!,
  payments: {},
});

That is the whole setup. Create your products in the dashboard under Finance > Products, then use the plan ids they give you.

You do not write a webhook. Result receives every payment event, verifies its signature, handles retries and out-of-order delivery, and writes the result into billing_customers and billing_subscriptions in your own backend. Those tables already exist. Do not create them, do not write to them, and do not build a payment webhook endpoint.

Pricing page

const { data: plans } = await backend.payments.plans();

[
  {
    "slug": "pro-monthly",
    "name": "Monthly",
    "productName": "Pro",
    "amount": "1000",
    "currencyCode": "USD",
    "interval": "month",
    "formattedTotal": "$10.00"
  }
]

In a browser, formattedTotal is display-ready. Paddle accounts localize it to the visitor’s country with tax applied; connected Stripe accounts format the price and currency stored in Stripe. Server-side you get amount and currencyCode to format yourself.

amount is a string in the currency’s lowest denomination. "1000" is $10.00. It is not always hundredths, either: "1200" in JPY is ¥1,200, not ¥12. Use formattedTotal where you can.

Checkout

await backend.payments.checkout({ plan: "pro-monthly" });

Opens the configured provider’s checkout. Paddle uses its overlay; connected Stripe accounts use Stripe-hosted Checkout. The signed-in user’s id is attached automatically, which is how the purchase gets matched back to their account. The buyer has to be signed in. With nobody signed in this throws PAYMENTS_SIGN_IN_REQUIRED rather than opening a checkout, because a payment with no user attached can never grant access and there is no way to repair it after the money has moved. Send buyers through sign-in first.

Option	What it does
`plan`	Required. The plan id from Finance > Products
`quantity`	Seats, for per-seat pricing
`successUrl`	Where the buyer lands after paying
`email`	Prefill, when you already know it
`displayMode`	`"overlay"` (default) or `"inline"`
`frameTarget`	CSS selector, required for `"inline"`
`customData`	Extra fields echoed back on payment events

Gating features

const { data: allowed } = await backend.payments.hasAccess();
const { data: isPro } = await backend.payments.hasAccess("pro-monthly");
const { data: sub } = await backend.payments.subscription();

Never grant access from a success URL, a redirect, or the checkout callback. The buyer can close the tab before any of them run, and you will have taken money without granting anything. hasAccess() reads what the payment actually wrote.

Access is granted for active, trialing and past_due. past_due means a renewal payment failed and automatic recovery is under way, which usually succeeds. Show a banner linking to the billing portal rather than cutting the customer off:

{sub?.status === "past_due" && (
  <Banner>Your payment didn't go through. <a href={portalUrl}>Update it</a></Banner>
)}

A scheduled cancellation keeps access until it takes effect, so someone who cancels mid-month keeps what they paid for.

Managing a subscription

const { data: url } = await backend.payments.portalUrl();
await backend.payments.changePlan({ plan: "pro-yearly" });
await backend.payments.cancel();                    // at the end of the period
await backend.payments.cancel({ immediately: true }); // right now

The portal handles payment methods, invoices and cancellation.

Portal links are single-use and short-lived. Mint one per click, open it in a new tab, and never cache or iframe it. Changes a customer makes there arrive back in your database on their own.

Plan changes cannot be made in the portal, which is why changePlan() exists. It bills the difference immediately, prorated to the minute.

Test mode

Test-mode accounts use test cards, never a real one:

Card	What happens
4242 4242 4242 4242	Succeeds
4000 0038 0000 0446	Succeeds, with a 3DS challenge
4000 0000 0000 0002	Declined
4000 0027 6000 3184	Succeeds once, then fails on renewal

Any future expiry and any name work. Paddle accounts go live with the switch in Finance > Payments. Stripe accounts connect the live Stripe account from Payments > Settings. Your running app follows the account connection, so neither path needs an app environment variable change or redeploy.

Before you can go live

Paddle’s merchant-of-record setup requires three pages, publicly reachable without a login:

Terms and conditions, stating that Paddle.com is the reseller and Merchant of Record for all orders.
A refund policy with a window between 14 and 90 days.
A privacy notice.

Login walls and hidden pricing are the most common reason a site is refused. With Stripe, you remain the merchant and keep your existing Stripe business, tax, dispute and payout configuration. Result only requests the permissions needed to show and operate that account from Finance.

Reading the tables directly

Useful for dashboards and joins:

select status, plan, current_period_ends_at
  from billing_subscriptions
 where user_id = auth.uid();

billing_customers, billing_subscriptions and billing_plans are read-only to signed-in users and scoped to their own rows.

From the CLI

result payments status   # is this app set up to take money
result payments plans    # the plan ids to use in checkout()

Getting started

SDK

CLI

Guides

Pricing page

Checkout

Gating features

Managing a subscription

Test mode

Before you can go live

Reading the tables directly

From the CLI

​Pricing page

​Checkout

​Gating features

​Managing a subscription

​Test mode

​Before you can go live

​Reading the tables directly

​From the CLI

Pricing page

Checkout

Gating features

Managing a subscription

Test mode

Before you can go live

Reading the tables directly

From the CLI