Trials

Altruon supports subscription trials across all four billing engines (Chargebee, Recurly, Stripe Billing, and Frisbii). During a trial, checkout collects a reusable payment method without charging the customer today, then bills automatically when the trial ends.

How it works

1. Estimate — Your billing platform returns trial metadata (trialEnd, amountDueNow). Altruon uses this to show $0 due today and to schedule mandates (e.g. PagBrasil Pix pix_rec_first_recurrence).
2. Gateway setup — The merchant gateway runs a zero-amount flow: card tokenization (SETUP), Pix/UPI consent (CONSENT), or open-banking mandate (MANDATE).
3. Subscription create — Altruon creates the subscription in trial status with trial_start, trial_end, and nextBillingDate = trial_end.
4. Trial end — The billing platform transitions the subscription to active and generates a payment-due invoice. Altruon collects it via MIT using credentials stored at signup. If collection fails, the merchant’s retry rules apply; Altruon may cancel the subscription when configured — not preemptively at trial end.

Payment method is always required at trial signup so renewal can run without customer action.

By default, trial length comes from your billing catalog (e.g. Stripe Price trial_period_days, Chargebee item trial).

Override trial length per checkout

Use billingData.forceTrialPeriodDays on Create Session when you want to set the trial length at checkout time instead of on the plan in your billing catalog.

Field	billingData.forceTrialPeriodDays (integer, days)
Range	1–730
Effect	Starts a $0 subscription trial for that many days. Overrides any trial configured on the plan.
Due today	Subscription portion is $0; one-time lineItems with type: "charge" are still charged today if present.
Platforms	Stripe Billing, Chargebee, Recurly, Frisbii
Not supported	Static hosted pages (hostedPageConfigId / /checkout/p/)

Pass the field inside billingData — not at the root of the request body:

{
  "hostedCheckout": true,
  "paymentData": { "currency": "USD" },
  "billingData": {
    "billingPlatformId": "3287b8c7-ce43-41fd-9d58-f510e610b8f3",
    "forceTrialPeriodDays": 30,
    "lineItems": [
      { "type": "plan", "id": "price_1SMtJj4hYau76GhIakR22BKu", "quantity": 1 }
    ]
  },
  "customerData": { "email": "shopper@example.com" },
  "redirectUrl": "https://your-site.com/success"
}

When set, the Create Session response includes a trial object with inTrial, trialEnd, amountDueNow, and nextInvoiceDate. At trial end, the billing platform activates the subscription and Altruon collects the first invoice via the payment method stored at signup.

Supported gateway × payment method pairs (V1)

Gateway	Payment methods	Collection mode
PagBrasil	card, pix	SETUP / CONSENT
Adyen	card	SETUP
Nuvei	card	SETUP
Checkout.com	card, applepay, kakaopay	SETUP
dLocal	card, pix, upi	SETUP / CONSENT
Trustly	openbanking	MANDATE

Other gateway × payment method combinations return a clear unsupported error at session creation when the plan is in trial with $0 due today.

Checkout behaviour

• Order summary shows “Free until …” (or equivalent) when amountDueNow is zero.
• Hosted checkout hides payment methods that are not in the V1 trial matrix.
• PagBrasil Pix trial checkout uses consent-only flow: no charge today; first debit is scheduled from trialEnd.

API / session fields

Session and estimate responses include a trial object:

Field	Description
inTrial	Whether the cart is in a trial period
trialEnd	ISO-8601 instant when the trial ends
amountDueNow	Amount charged at signup (typically 0 for pure trials)
nextInvoiceDate	First invoice date after trial

Gateway pending responses may include paymentCollectionMode (SETUP, CONSENT, MANDATE, CHARGE) for frontend hints.

Trial + immediate charge

If the estimate returns amountDueNow > 0 (e.g. trial plus setup fee or discounted first period), Altruon uses a normal CHARGE flow for today’s amount while still storing the payment method for renewal.

Testing

• Use sandbox plans with configured trial periods on each billing platform.
• Verify estimate returns trialEnd before payment.
• Confirm subscription is trial locally after checkout and becomes active after trial end webhooks.
• Regression: non-trial and paid-first checkout must behave unchanged.