Skip to main content

Recurring Payments

Overview​

Recurring Payments lets you sell subscriptions. You define a plan (what to charge and how often), send the customer to checkout, and the service charges them on schedule.

Authenticate with a JWT that already identifies your merchant. Creates and lists are scoped to that merchant automatically.

How it works​

  1. Create a plan with amount, currency, and billing frequency.
  2. The response includes subscription_url. Redirect the customer there.
  3. The customer reviews the plan, enters their data, and pays with a card.
  4. A customer, payment method, and subscription are created. Recurring charges run according to the plan.
  5. Listen to webhooks for subscription and charge events.

Merchant identity​

The JWT in Authorization already identifies your merchant. Creates and lists are scoped to that merchant automatically.

You will still see merchant_id in responses and webhooks. That value is the merchant’s internal UUID (not the merchant code in the token). Use it as a read-only identifier, for example in the customer portal recovery URL.

What you can manage​

ResourceWhat it is
PlansBilling rules. Creating a plan returns subscription_url for checkout.
CustomersPeople subscribed to your plans. Email is unique per merchant.
Payment methodsCards on file, used for recurring charges.
SubscriptionsThe link between a customer, a plan, and a payment method.
ChargesEach billing attempt and its history.

Checkout and customer portal​

Checkout is the hosted flow behind subscription_url. After subscribe, the customer can open the customer portal (/account) to manage the subscription.

If the portal session expires, the customer is redirected to recover it:

https://<your-checkout-host>/session-request/<merchant_id>

<merchant_id> is the UUID returned by the API (the same merchant_id in plan/customer responses), not the merchant code from the token. The page asks for the customer email and sends a new portal link.

See Checkout for the three checkout steps.

Webhooks​

Receive events when subscriptions, charges, or plans change.

Platform Webhooks · Integration guide

API reference​

Recurring Payments API — endpoints, schemas, and authentication.