Process Stripe Billing subscriptions with Yuno

Stripe Billing stays your system of record for plans, subscriptions, invoices, tax and proration. Yuno executes every subscription payment: the first charge, each renewal, each retry and each refund. Yuno also makes the Stripe API calls that report each outcome back, so your backend does not call Stripe’s payment record APIs.

Before you start

Check these points against your use case before you integrate:

Stripe account. Billing must have third-party payment processing enabled. Request it from your Stripe account team.
Countries. Your business and your payment providers must be in countries Stripe supports for this mode. See Stripe’s supported countries.
Checkout. Customers pay through your Yuno checkout. Stripe Checkout, the Stripe-hosted invoice page and embedded Stripe pricing tables do not work in this mode.
Customer emails. Stripe does not send its revenue recovery emails for these payments. You send failed-payment and card-update emails from your own systems.
Retries. Stripe Smart Retries are not available. You configure a custom retry schedule or Billing automations instead.
Disputes and refunds. You handle both in Yuno. Stripe cannot start a refund or manage a dispute for a payment it did not process.
Fees. Stripe charges Billing fees on the volume Yuno processes. See Billing fees.

Who does what

Area	Stripe Billing	Your backend	Yuno
Plans, prices, tax, proration	Owns	Configures	None
Subscription and invoice lifecycle	Owns	Reads webhooks for entitlements	None
Retry schedule	Runs it	Configures it	Executes each attempt
First payment	Waits for the report	Creates the Yuno payment with `external_subscription`	Charges, vaults, reports to Stripe
Renewals	Sends `invoice.payment_attempt_required`	Nothing	Charges as a merchant-initiated transaction, reports to Stripe
Payment method reference in Stripe	Stores it	Nothing	Creates it and sets it as default
Refunds	Records the refund and credit note	Starts the refund in Yuno	Refunds, reports to Stripe, creates the credit note
Disputes	None	Handles them in Yuno	Receives them from the provider
Dunning emails and card-update flow	None	Owns	Vaults the new card and updates Stripe

To collect the payment of one specific Stripe invoice instead, such as a balance top-up, see Pay a Stripe invoice (top-ups).

How it works

Stripe’s third-party payment processing mode lets an external processor execute the charges for Billing subscriptions. Yuno is that processor.

Renewals and retries

Your backend keeps listening to the Stripe webhooks it uses today (invoice.paid, customer.subscription.updated and others) for entitlements. On the Yuno side, every payment created this way carries the external_subscription object in its payment webhook, so you can match a Yuno payment to a Stripe subscription. See Object and examples. Trial enrollments are the exception: the enrollment webhook does not include the object, so correlate through the verification payment instead (verify.payment.id in the enrollment response).

Prerequisites

A Yuno account with your providers connected and routing published.
A Stripe account with Billing and third-party payment processing enabled.
A restricted API key from your Stripe account, shared with your Yuno contact during onboarding. Yuno uses it to register the webhook endpoint and report payments. Yuno stores it encrypted and uses it only for your account.

Step 1: Create the subscription in Stripe

Create the customer and subscription in Stripe as you do today, with payment_behavior: default_incomplete. Expand latest_invoice in the same call: you need its amount_due and currency in step 2. Keep the customer and subscription IDs.

Create the subscription at checkout time and collect the payment in the same session. Stripe requires the first payment to be reported within 23 hours of the subscription’s creation. Past that deadline Stripe moves the subscription to incomplete_expired, and you have to create it again.

Step 2: Collect the first payment with Yuno

Run your normal Yuno checkout and create the payment from your backend with two additions: vault_on_success and the external_subscription object that links the payment to your Stripe subscription. See Create payment.

{
  "account_id": "<your_account_id>",
  "merchant_order_id": "<your_order_id>",
  "description": "Pro plan, first month",
  "country": "US",
  "amount": { "currency": "USD", "value": 99.00 },
  "customer_payer": { "id": "<yuno_customer_id>" },
  "payment_method": {
    "type": "CARD",
    "token": "<one_time_token_from_sdk>",
    "vault_on_success": true
  },
  "external_subscription": {
    "id": "sub_1QwZzz",
    "customer_id": "cus_RplXYZ"
  }
}

Match the amount to the invoice

Charge the invoice’s amount_due, in the invoice’s currency. amount_due already includes tax, discounts and proration. Yuno reports the amount it charged, so any other value leaves the Stripe invoice mismatched. Stripe and Yuno format amounts differently, so convert both fields:

Field	Stripe invoice	Yuno payment
Amount	Minor units: `9900`	Decimal value: `99.00`
Zero-decimal currency (for example JPY)	`1000`	`1000`
Currency	Lowercase: `usd`	Uppercase ISO 4217: `USD`

Request fields

Field	Required	Notes
`external_subscription.id`	Yes	The subscription’s ID in Stripe (`sub_...`). 3 to 255 characters.
`external_subscription.customer_id`	No	The Stripe customer that owns the subscription (`cus_...`).
`payment_method.vault_on_success`	For renewals	Yuno takes over the recurring charges only when the payment is approved and the card is vaulted.

external_subscription and the subscription object are mutually exclusive: sending both returns INVALID_REQUEST. Use subscription when Yuno is the recurrence engine, and external_subscription when Stripe is.

When the payment is approved, Yuno creates a payment method reference in your Stripe account (no card data), attaches it to the subscription as its default payment method, and reports the payment. Stripe then marks the first invoice as paid and activates the subscription.

Free trials

When signup starts a trial, there is no first charge. The trigger is the $0 card verification of the enrollment flow instead. Create the Stripe subscription with trial_end as usual, then enroll the card through the Enroll payment method endpoint with the external_subscription object nested inside verify:

{
  "account_id": "<your_account_id>",
  "country": "US",
  "type": "CARD",
  "workflow": "DIRECT",
  "card_data": { "...": "..." },
  "verify": {
    "vault_on_success": true,
    "currency": "USD",
    "external_subscription": {
      "id": "sub_1QwZzz",
      "customer_id": "cus_RplXYZ"
    }
  }
}

Use the subscription’s currency for the verification. Renewals are charged in the subscription’s currency.

verify.vault_on_success must be true. Sending verify.external_subscription without it returns INVALID_PARAMETERS.

On a successful verification, Yuno links the vaulted card to the trialing subscription: its default_payment_method in Stripe becomes the Yuno reference. Nothing is charged or reported, because no invoice is due. At trial end, Stripe issues the first real invoice and Yuno charges it with network-compliant stored credentials, like any renewal.

Renewals

Renewals need no code on your side. Stripe finalizes the invoice and sends invoice.payment_attempt_required. Yuno charges the vaulted card as a merchant-initiated transaction, through your routing and provider cascade, and reports the result. Each charge appears as a normal payment in your Yuno dashboard and reports.

Failed payments and retries

When Yuno reports a failed renewal, the invoice stays open and Stripe moves the subscription to past_due. Stripe then sends a new invoice.payment_attempt_required event on each scheduled retry, and Yuno executes each retry across your routing and provider cascade. Yuno reports every retry against the invoice’s existing payment record. Configure retries in Stripe with a custom retry schedule or Billing automations. Stripe’s Smart Retries and recovery emails do not work in third-party processing mode. Both are Stripe limitations, unrelated to Yuno’s Smart Retries, which apply to Yuno-managed subscriptions.

Hard and soft declines

A custom retry schedule runs the same way for every failed invoice. Stripe does not see the decline reason, so a stolen card or a closed account gets the same retries as insufficient funds. Card networks limit retries on declines that cannot succeed, and repeated retries on them can add network fees. Keep the retry schedule short, and cancel the subscription or mark the invoice uncollectible when the decline reason in Yuno shows that a retry cannot succeed.

Detect the final attempt

Stripe has no dedicated “retries exhausted” event. Treat a failure as final when:

Your backend receives invoice.payment_failed, or invoice.updated when you use automations, and
The invoice’s next_payment_attempt is null.

Then the subscription moves to the state set in your Stripe retry settings (canceled, unpaid or past due). Start your own dunning flow from this point.

Stripe does not send invoice.payment_attempt_required while an invoice has auto_advance set to false. Such an invoice never reaches Yuno: nothing is charged and nothing errors. Set auto_advance back to true to resume collection.

Change the customer’s card

Use this flow for card updates and for recovering a past_due subscription:

Bring the customer back to your Yuno checkout

Send the customer to your own card-update page. Stripe does not send this email for you.

Collect a new payment or verification

Create a payment (or, for a trialing subscription, a verification) with the same external_subscription.id and vault_on_success: true.

Yuno switches the default in Stripe

Yuno vaults the new card and sets it as the subscription’s default payment method in Stripe. Renewals continue on the new card.

Customer portal

Stripe’s customer portal works with these subscriptions. Customers can update the subscription, switch payment method, set a default payment method and cancel.

The portal lets customers switch to a Stripe-supported payment method. Stripe processes that payment method itself, so the subscription’s renewals stop going through Yuno. To keep every renewal on Yuno, turn off payment method updates in your portal configuration and send customers to your Yuno card-update page instead.

The portal also cannot add a discount to a subscription on a custom payment method when the portal session’s proration behavior is always_invoice.

What you see in Stripe

Two things in the Stripe dashboard look wrong and are not:

A canceled payment on every invoice. Stripe creates its own PaymentIntent for each charge_automatically invoice and cancels it once Yuno reports the payment. Each invoice carries a Canceled entry next to the Yuno one. Stripe documents this as expected behavior. It changes neither the invoice nor the subscription status.
One payment entry per invoice, not one per attempt. Yuno reports each retry against the existing payment record. A recovered invoice shows one payment with the history of its attempts, not one failed entry plus one succeeded entry.

If it is enabled for your organization, the metadata you send is also copied onto the Stripe payment records. See Your payment metadata on the Stripe payment record.

Refunds

Refund through the Yuno API or dashboard as with any payment. Yuno reports the refund to Stripe and creates the matching credit note, so your Stripe records stay consistent. Full and partial refunds are supported. For payments made with external_invoice (top-ups), see Refunds.

Disputes

Stripe cannot manage disputes for payments it did not process. A chargeback on one of these payments reaches you through the Yuno provider that processed the charge, and you handle it in Yuno. See Chargeback Management.

Billing fees

Stripe counts the volume Yuno processes toward your total Stripe Billing volume and charges for it under your Billing contract. One-off invoices paid through a third-party processor are also billed under Stripe’s Invoicing pricing.

Test in sandbox

Signup and renewals. Create the subscription on a Stripe test clock, pay the first invoice through your Yuno sandbox checkout, then advance the clock past the renewal date. Check that a new payment appears in Yuno and the invoice is paid in Stripe.
Retries. Use a Yuno test card that declines, then advance the clock past next_payment_attempt. If the retry event does not arrive, advance the clock again by about one minute.
Dunning in real time. To validate dunning as production runs it, create a subscription without a test clock on a short custom retry schedule and let it run.

Integration checklist

Stripe: enable third-party payment processing

Ask your Stripe account team, and confirm your business country is supported.

Yuno onboarding: share a restricted Stripe API key

Send it to your Yuno contact. Yuno registers the webhook endpoint.

Stripe: configure retries

Set a short custom retry schedule or Billing automations, and the final state after the last retry.

Stripe: restrict the customer portal

Turn off payment method updates so renewals stay on Yuno.

Backend: create the subscription

Use payment_behavior: default_incomplete and expand latest_invoice.

Backend: create the first Yuno payment

Send vault_on_success: true, external_subscription, and the converted amount_due within 23 hours.

Backend: handle trials

Enroll the card with verify.external_subscription for subscriptions with trial_end.

Backend: handle the final failed attempt

Detect next_payment_attempt: null and start your dunning emails and card-update flow.

Test in sandbox

Cover signup, one renewal, one failed renewal with retry, a refund, and a card update.

Troubleshooting

Symptom	Cause	Fix
`INVALID_REQUEST` on Create payment	`external_subscription` and `subscription` sent in the same request	Send only one of them
`INVALID_PARAMETERS` on Enroll payment method	`verify.external_subscription` sent without `verify.vault_on_success: true`	Set the flag to `true`
Subscription stays `incomplete`, then turns `incomplete_expired`	No payment was reported within 23 hours of creating the subscription	Create the subscription and collect the payment in the same session, then recreate the expired one
Renewals stop and no error appears anywhere	The invoice has `auto_advance: false`, so Stripe never sends `invoice.payment_attempt_required`	Set `auto_advance` back to `true`
Renewals appear in Stripe but not in Yuno	The customer switched to a Stripe-supported payment method in the customer portal	Turn off payment method updates in the portal and collect a new card through Yuno
A `Canceled` payment sits next to each reported payment	Stripe cancels its own PaymentIntent once Yuno reports the payment	Expected behavior, no action needed

PayPal

You can collect subscription payments with PayPal through the Stripe billing integration. The first payment saves the customer’s PayPal account, and each renewal charges that saved account. PayPal is enabled per organization: your Technical Account Manager turns it on after the steps below.

Before you start

Complete these steps with your Technical Account Manager (TAM):

Share your PayPal account details. For both sandbox and live: your PayPal Merchant ID (the payer ID shown in your PayPal dashboard), the business vertical PayPal assigned to your account, and whether PayPal flags your account as high risk. Your TAM sets them on your PayPal connection in Yuno. PayPal subscription payments can’t be processed without them.
Enable Vault on PayPal. In the PayPal apps connected to Yuno, sandbox and live, enable Vault (save payment methods). Renewals charge the saved PayPal account, so Vault is required.
Create a “PayPal” custom payment method in Stripe. In the Stripe Dashboard, go to Settings → Payment methods → Custom payment methods and create one named PayPal. If you want card payments to show as Card, create a “Card” one as well. Do this in both live mode and test mode, and send the IDs (they start with cpmt_) to your TAM.

Yuno registers these IDs and runs a test on your sandbox before PayPal is enabled in live.

What to expect

Subscription payments and renewals made with PayPal appear in Stripe under the PayPal payment method name. Top-up payments appear as Yuno.
PayPal can’t verify an account with a 0.00 payment, as cards do. When a subscription starts with a trial, send a payment of 1.00 in the subscription’s currency, with the subscription’s external_subscription object. Yuno refunds it automatically and doesn’t report it to Stripe as a payment. This is enabled per organization; until it is, the 1.00 is not refunded automatically.

Not supported in this mode

Per Stripe’s third-party processing mode: Stripe Checkout, the Stripe-hosted invoice page, Stripe Smart Retries and recovery emails, Stripe-managed disputes, and Stripe-initiated refunds. Embedded Stripe pricing tables are not compatible, because the checkout is Yuno’s.

Getting Started

Core Concepts

Using Yuno

Direct Integration Use Cases

Payment Features

Payouts and Disputes

Webhooks

Wallets

AI Capabilities

Security and Compliance

Plugins

Additional Services

Process Stripe Billing subscriptions with Yuno

Before you start

Who does what

How it works

Renewals and retries

Prerequisites

Step 1: Create the subscription in Stripe

Step 2: Collect the first payment with Yuno

Match the amount to the invoice

Request fields

Free trials

Renewals

Failed payments and retries

Hard and soft declines

Detect the final attempt

Change the customer’s card

Customer portal

What you see in Stripe

Refunds

Disputes

Billing fees

Test in sandbox

Integration checklist

Troubleshooting

PayPal

Before you start

What to expect

Not supported in this mode

​Before you start

​Who does what

​How it works

​Signup and first payment

​Renewals and retries

​Prerequisites

​Step 1: Create the subscription in Stripe

​Step 2: Collect the first payment with Yuno

​Match the amount to the invoice

​Request fields

​Free trials

​Renewals

​Failed payments and retries

​Hard and soft declines

​Detect the final attempt

​Change the customer’s card

​Customer portal

​What you see in Stripe

​Refunds

​Disputes

​Billing fees

​Test in sandbox

​Integration checklist

​Troubleshooting

​PayPal

​Before you start

​What to expect

​Not supported in this mode

Before you start

Who does what

How it works

Signup and first payment

Renewals and retries

Prerequisites

Step 1: Create the subscription in Stripe

Step 2: Collect the first payment with Yuno

Match the amount to the invoice

Request fields

Free trials

Renewals

Failed payments and retries

Hard and soft declines

Detect the final attempt

Change the customer’s card

Customer portal

What you see in Stripe

Refunds

Disputes

Billing fees

Test in sandbox

Integration checklist

Troubleshooting

PayPal

Before you start

What to expect

Not supported in this mode