Add support to specify custom stripe API version (or add version suffix)

[dvigueras]

Cashier Stripe Version

16.0.0

Laravel Version

12.31.1

PHP Version

8.4

Database Driver & Version

No response

Description

Hi,

I'm using Stripe Managed Payments (which is currently in Private Preview).

In order to use this Stripe feature, there are two steps that must be done:

1. Pass the 'managed_payments' => ['enabled' => true], option in the array when creating a new Checkout session. This can currently be done by passing this option as the first argument of the checkout( Cashier method.

2. Add ; managed_payments_preview=v1 as a suffix to the stripe_version option:

$stripe = new \Stripe\StripeClient([
  'api_key' => 'sk_test_51S2nRFLfdT6DuBGAS9gO29AaQ7kFK1xMF583jjSMqZz10bxGrw47S2DCnzZWyMXVZ7gb6IPLUNWyNoJHCb3zV9FW00QQJEHIri',
  'stripe_version' => '2025-08-27.basil; managed_payments_preview=v1',
]);

Right now, Cashier uses a fixed Stripe version (which is the one that in bundled in the Stripe PHP package):

    public static function stripe(array $options = [])
    {
        $config = array_merge([
            'api_key' => $options['api_key'] ?? config('cashier.secret'),
            'stripe_version' => static::STRIPE_VERSION,
            'api_base' => static::$apiBaseUrl,
        ], $options);

        return app(StripeClient::class, ['config' => $config]);
    }

When invoking the stripe() method from my code, I could override the $options array and set my custom stripe_version (which will be the same but with the suffix added).

However, when using the `checkout()' method, I can't override this option.

I could submit a PR with one of these two options, but before coding I want to hear your feedback and if you would be open to accept the PR:

• Option 1: Be able to override the stripe_version option. A new setting in Cashier's configuration file would be added to allow this: stripe_version
• Option 2: Be able to add a string suffix to the stripe_version option. Those suffixes would be added to the stripe_version option used in Cashier. A new setting in Cashier's configuration file would be added to allow this: e.g. stripe_version_suffix

Let me know what you think about this and I'll be happy to submit a PR if you think it's a good idea.

Steps To Reproduce

Enroll in the managed payments private preview and try to use Laravel Cashier

[crynobone]

Can you share the documentation describing the feature (setting up version suffix)?

[dvigueras]

Managed Payments Documentation is not public yet (it's a Private Preview).

This is an extract from the doc:

Set up your server [Server-side]

Stripe uses Checkout Sessions to represent what your customer sees when they’re redirected to the payment form. You can configure Checkout Sessions with options such as line items to charge or currencies to accept.

Create a Checkout Session

Subscriptions

Create a Checkout Session using one of the prices you created as a line item. Set the mode to subscription, and set the success_url and cancel_url to the URLs of your success and cancel pages. To enable Managed Payments, set managed_payments[enabled] to true and include ;managed_payments_preview=v1 in your version header.

// Set your secret key. Remember to switch to your live secret key in production.
// See your keys here: https://dashboard.stripe.com/apikeys
$stripe = new \Stripe\StripeClient([
  'api_key' => '<<YOUR_SECRET_KEY>>',
  'stripe_version' => '2025-09-30.preview; managed_payments_preview=v1',
]);

$session = $stripe->checkout->sessions->create([
  'line_items' => [
    [
      'price' => '{{PRICE_ID}}',
      'quantity' => 1,
    ],
  ],
  'managed_payments' => ['enabled' => true],
  'mode' => 'subscription',
  'success_url' => 'https://localhost:4242/success',
  'cancel_url' => 'https://localhost:4242/cancel',
]);

One-off payments

Create a Checkout Session using one of the prices you created as a line item. Set the mode to payment and set the success_url and cancel_url to the URLs of your success and cancel pages. To enable Managed Payments, set managed_payments[enabled] to true and include ;managed_payments_preview=v1 in your version header.

// Set your secret key. Remember to switch to your live secret key in production.
// See your keys here: https://dashboard.stripe.com/apikeys
$stripe = new \Stripe\StripeClient([
  'api_key' => '<<YOUR_SECRET_KEY>>',
  'stripe_version' => '2025-09-30.preview; managed_payments_preview=v1',
]);

$session = $stripe->checkout->sessions->create([
  'line_items' => [
    [
      'price' => '{{PRICE_ID}}',
      'quantity' => 1,
    ],
  ],
  'managed_payments' => ['enabled' => true],
  'mode' => 'payment',
  'success_url' => 'https://localhost:4242/success',
  'cancel_url' => 'https://localhost:4242/cancel',
]);

[larskoole]

Is there currently a workaround for the checkout?

[larskoole]

I managed to get it working by overriding the stripe() method on my billable model. For most people this would be the User model.

public static function stripe(array $options = []): StripeClient
{
    return Cashier::stripe(array_merge([
        'stripe_version' => Cashier::STRIPE_VERSION . '; managed_payments_preview=v1',
    ], $options));
}

[larskoole]

One thing that doesn't work with managed payments is increasing the quantity of a subscription. The reason for this is that subscriptions that were created with the managed_payments flag aren't allowed to update the payment_behaviour. So even passing the parameter causes issues.

You'll get the following error: payment_behavior cannot be updated for Subscriptions created by Checkout Sessions with Stripe Managed Payments enabled.