Docs / Payments
Customer payments
Your app’s checkout, subscriptions and billing history.
One integration, your design
Start with test payments. Create plans, connect your app backend and build your billing UI. The owner completes Stripe verification to accept real payments.
Management APIPOST /api/v1/apps/{appId}/payments/actions/{action}
App backendPOST /runtime/v1/payments/{action}
Use a Bearer token and JSON. Keep runtime tokens server-only. Your backend must authenticate each user and derive customerRef from their session.
Node, Python, Checkout, Elements and event examples →
Machine-readable action catalogue →
Actions
Amounts use currency minor units. Mutations need a stable requestId. Every response wraps its result in data.
status · Management
Cached test/live connection status; no provider call.
app:read
{
"mode": "test"
}account.refresh · Management
Read current Stripe charges, payouts and requirements.
app:read
{
"mode": "test"
}plans.list · App backend & agent
Paginated catalog, including archived entries and Stripe IDs. Render only active plans for new purchases.
app:read
{
"mode": "test"
}customers.list · Management
Paginated customerRef → Stripe customer mapping for this app and mode. Management only.
app:read
{
"mode": "test",
"limit": 25
}customers.get · App backend & agent
Read name, email and default payment method.
app:read
{
"mode": "test",
"customerRef": "user_123"
}checkout.get · App backend & agent
Read status, paymentStatus, paymentId and subscriptionId; verify payment server-side before fulfilment.
app:read
{
"mode": "test",
"customerRef": "user_123",
"id": "cs_..."
}cards.list · App backend & agent
List this customer’s saved cards (brand, last4, expiry; never full details).
app:read
{
"mode": "test",
"customerRef": "user_123"
}subscriptions.list · App backend & agent
Paginated subscription history; runtime is customer-scoped.
app:read
{
"mode": "test",
"customerRef": "user_123",
"limit": 25
}subscriptions.get · App backend & agent
Read status, period end, items and pendingUpdate. Wrong-customer objects return 404.
app:read
{
"mode": "test",
"customerRef": "user_123",
"id": "sub_..."
}transactions.list · App backend & agent
Paginated PaymentIntent history, amounts, refund totals and receipt links.
app:read
{
"mode": "test",
"customerRef": "user_123",
"limit": 25
}transactions.get · App backend & agent
Read current payment status and refund total.
app:read
{
"mode": "test",
"customerRef": "user_123",
"id": "pi_..."
}invoices.list · App backend & agent
Paginated invoices with amounts, status, hosted payment URL and PDF URL.
app:read
{
"mode": "test",
"customerRef": "user_123",
"limit": 25
}invoices.get · App backend & agent
Read an invoice; its hosted URL supports customer payment/authentication.
app:read
{
"mode": "test",
"customerRef": "user_123",
"id": "in_..."
}refunds.list · App backend & agent
List refunds for an owned paymentId.
app:read
{
"mode": "test",
"customerRef": "user_123",
"paymentId": "pi_..."
}events.list · App backend & agent
Cursor feed. after defaults to 0; limit 1–100. Runtime returns customer events and pending:true when an earlier refresh blocks progress. Persist nextAfter only after processing.
app:read
{
"mode": "test",
"customerRef": "user_123",
"after": "0",
"limit": 25
}events.get · App backend & agent
Inspect one event by evt_ ID and its current processing status/summary.
app:read
{
"mode": "test",
"customerRef": "user_123",
"id": "evt_..."
}access.get · App backend & agent
Current Stripe-backed paid features for a customer. Active plus paid latest invoice, or trialing; no paused collection. No automatic one-off purchase grants.
app:read
{
"mode": "test",
"customerRef": "user_123"
}customers.upsert · App backend & agent
Create a customer once per customerRef; returns existing mapping unchanged if it already exists.
app:write
{
"mode": "test",
"customerRef": "user_123",
"email": "buyer@example.com",
"name": "Alex",
"requestId": "customer-user-123"
}customers.update · App backend & agent
Update optional name and/or email on a mapped customer.
app:write
{
"mode": "test",
"customerRef": "user_123",
"email": "new@example.com",
"requestId": "update-customer-001"
}checkout.create · App backend & agent
Create Checkout. ui: hosted, embedded or custom. Requires an active plan, customer and charges-enabled account. quantity defaults to 1 (max 1000). returnUrl must belong to this app. Optional trialDays 1–30 is administrator-only. Persist requestId and session ID.
app:write
{
"mode": "test",
"customerRef": "user_123",
"planCode": "pro-monthly",
"ui": "custom",
"returnUrl": "https://YOUR_APP_URL/billing",
"requestId": "checkout-user-123-001"
}checkout.expire · App backend & agent
Expire an open checkout and free its subscription checkout slot.
app:write
{
"mode": "test",
"customerRef": "user_123",
"id": "cs_...",
"requestId": "expire-session-001"
}cards.setup · App backend & agent
Create a SetupIntent. Returns clientSecret, publishableKey and stripeAccount for that customer’s browser.
app:write
{
"mode": "test",
"customerRef": "user_123",
"requestId": "save-card-001"
}cards.remove · App backend & agent
Detach a card only when the customer has no non-terminal subscription. Use the portal to replace cards otherwise.
app:write
{
"mode": "test",
"customerRef": "user_123",
"id": "pm_...",
"requestId": "remove-card-001"
}cards.default · App backend & agent
Set a customer default invoice payment method. Does not override a subscription-specific default.
app:write
{
"mode": "test",
"customerRef": "user_123",
"id": "pm_...",
"requestId": "default-card-001"
}portal.create · App backend & agent
Create a short-lived customer billing portal URL for payment methods, invoices and cancellation.
app:write
{
"mode": "test",
"customerRef": "user_123",
"returnUrl": "https://YOUR_APP_URL/billing",
"requestId": "billing-portal-001"
}subscriptions.preview · App backend & agent
Estimate the invoice for an immediate prorated plan change. Requires a recurring plan; amounts may change before confirmation.
app:write
{
"mode": "test",
"customerRef": "user_123",
"id": "sub_...",
"planCode": "pro-yearly",
"requestId": "preview-change-001"
}subscriptions.update · App backend & agent
Apply a confirmed prorated change. An unpaid change remains pending. Read invoices for an authentication/payment link.
app:write
{
"mode": "test",
"customerRef": "user_123",
"id": "sub_...",
"planCode": "pro-yearly",
"confirm": true,
"requestId": "change-plan-001"
}subscriptions.cancel · App backend & agent
confirm:true required. Defaults to period-end cancellation; immediate:true cancels now. No automatic refund.
app:write
{
"mode": "test",
"customerRef": "user_123",
"id": "sub_...",
"confirm": true,
"immediate": false,
"requestId": "cancel-plan-001"
}subscriptions.resume · App backend & agent
confirm:true required. Remove a scheduled period-end cancellation; cancelled subscriptions cannot resume.
app:write
{
"mode": "test",
"customerRef": "user_123",
"id": "sub_...",
"confirm": true,
"requestId": "resume-sub-001"
}invoices.retry · App backend & agent
Retry an open invoice using its saved payment method. confirm:true required; authentication may still be needed via the invoice URL.
app:write
{
"mode": "test",
"customerRef": "user_123",
"id": "in_...",
"confirm": true,
"requestId": "retry-invoice-001"
}onboard · Management
Create a sandbox for testing, or return owner verification for live mode. Country and businessType apply to live accounts.
app:write; live activation requires owner
{
"mode": "live",
"country": "GB",
"businessType": "individual"
}account.session · Management
Owner browser only. Short-lived embedded Stripe account session; never expose to an agent or app customer.
owner
{
"mode": "live"
}plans.create · Management
Create an immutable price. amount is an integer in currency minor units; interval is month, year or omitted for a one-off. features maps names to booleans or non-negative numeric limits.
app:write
{
"mode": "test",
"code": "pro-monthly",
"name": "Pro",
"amount": 1500,
"currency": "usd",
"interval": "month",
"features": {
"pro": true,
"workspaces": 10
},
"requestId": "plan-pro-monthly-001"
}plans.archive · Management
Stop new purchases. Existing subscriptions continue.
app:write
{
"mode": "test",
"planCode": "pro-monthly",
"requestId": "archive-plan-001"
}refunds.create · Management
Administrator only; confirm:true and positive amount required. Refunds move money, do not cancel subscriptions, and do not automatically revoke paid access.
app:write
{
"mode": "test",
"paymentId": "pi_...",
"amount": 500,
"confirm": true,
"requestId": "refund-order-001"
}events.retry · Management
Administrator retry of an event refresh; does not resend or repeat the payment.
app:write
{
"mode": "test",
"id": "evt_...",
"requestId": "retry-event-001"
}