Merchant Billing v2

Merchant Billing v2 is the recommended integration surface for new B2B checkout and billing integrations.

Use v2 when you need:

• hosted checkout links for online orders
• balance top-ups such as AI credits or prepaid account balance
• subscription billing with customer-confirmed renewal invoices
• products and prices managed from a catalog
• project-scoped API keys, limits, team access, and webhooks
• usage records linked to your customer or subscription data

Legacy API status

The old payment-intent flow remains available for existing integrations, but it should be treated as legacy and deprecated in future. New integrations should use /api/v2/*.

Core objects

Object	What it means
Project	Isolates catalog, checkout sessions, API keys, webhooks, limits, and team access.
Customer	Optional billing identity for subscriptions, invoices, usage, and portal access. Checkout can create one automatically from customer fields.
Product	What you sell, such as VPN Pro, AI token pack, or SaaS Pro.
Price	How you charge for a product: one-time, balance top-up, or subscription.
Checkout session	Hosted payment link opened by the customer.
Invoice	Billable record created behind checkout and subscriptions.
Subscription	Renewal schedule created after a subscription checkout is completed. Customers confirm renewal payments unless you build a balance-based flow.
Usage record	Metered activity for reporting or usage-based billing.
Webhook delivery	Delivery log for events sent to your backend.

Billing modes

Mode	Use it for	Required price fields
one_time	Online order, license, setup fee, single purchase	unitAmountCents, currency
balance_top_up	Credits, AI tokens, prepaid balance	unitAmountCents, currency, creditAmount
subscription	Monthly or recurring product access	unitAmountCents, currency, recurringInterval

Recommended setup

1. Create or select a project in the B2B dashboard.
2. Copy the read-only Project ID from Project Settings.
3. Create an API key with billing:write,billing:read,payments:write,payments:read.
4. Configure a webhook endpoint and save the signing secret immediately.
5. Create products and prices in the catalog.
6. Create checkout sessions from your backend.
7. Fulfill access only after a verified webhook event confirms payment.

Create catalog and checkout

API_KEY="st_live_or_dev_key"
PROJECT_ID="project_uuid"

curl -X POST "https://api.stendly.com/api/v2/products" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: product-vpn-pro" \
  -d '{
    "projectId": "'"$PROJECT_ID"'",
    "name": "VPN Pro",
    "description": "Monthly VPN access"
  }'

PRODUCT_ID="product_uuid"

curl -X POST "https://api.stendly.com/api/v2/prices" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: price-vpn-pro-monthly" \
  -d '{
    "projectId": "'"$PROJECT_ID"'",
    "productId": "'"$PRODUCT_ID"'",
    "name": "VPN Pro monthly",
    "unitAmountCents": 999,
    "currency": "USD",
    "billingMode": "subscription",
    "recurringInterval": "month"
  }'

PRICE_ID="price_uuid"

curl -X POST "https://api.stendly.com/api/v2/checkout-sessions" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: checkout-order-1001" \
  -d '{
    "projectId": "'"$PROJECT_ID"'",
    "priceId": "'"$PRICE_ID"'",
    "mode": "subscription",
    "externalCustomerId": "telegram_123456",
    "customerEmail": "customer@example.com",
    "merchantReference": "order_1001",
    "successUrl": "https://example.com/success",
    "cancelUrl": "https://example.com/cancel"
  }'

Open the returned checkoutUrl on your website or inside your application.

Webhook handling

Your backend should verify X-Stendly-Signature and then update local order state by event type.

Common v2 event families:

• checkout.session.*
• invoice.*
• subscription.*
• customer.balance_*
• payment_intent.*

For production, do not collapse all event types into a single paid state. Treat checkout completion, invoice payment, subscription activation, and balance crediting according to your fulfillment rules.

Examples

The repo includes website-based v2 examples:

• examples/v2-node
• examples/v2-python
• examples/v2-dotnet

Each example implements one-time checkout, balance top-up, subscription checkout, catalog setup, usage recording, webhook verification, and local order status sync.