Skip to content

Stripe🔗

Stripe integration in Symfony with stripe/stripe-php.

Installation🔗

1
composer require stripe/stripe-php

Configuration🔗

First you will need a public key and a secret key from your Stripe account and a webhook key.

Note: For development you should use test keys. All Stripe configuration described in this cookbook can be done in test mode. Fake credit card numbers are provided by Stripe for test purpose.

1
2
3
4
# .env
APP_STRIPE_PUBLIC_KEY=
APP_STRIPE_SECRET_KEY=
APP_STRIPE_WEBHOOK_KEY=

Build-in proccess🔗

Stripe provides a build-in process and payment page.

Subscription🔗

Setup🔗

Create your plans as products in https://dashboard.stripe.com/products with a recurring price. You can add several prices to each product if you have a yearly price and a monthly price for example.

Get the ID of each price, that's what we will send to Stripe to create subscription. Eventualy store these ID in database if your plans are.

Database model suggestion:

Note: properties starting with a * come from Stripe

If you have only one price per plan, you can merge Price and Plan entities.

Subscription build-in process🔗

If your use-case is simple, you can use the Stripe built-in subscription process.

Create a payment session in your controller.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
class CheckoutAction
{
    public function __invoke()
    {
        \Stripe\Stripe::setApiKey('YOUR_API_KEY');

        $session = \Stripe\Checkout\Session::create([
          'payment_method_types' => ['card'],
          'line_items' => [['price' => 'YOUR_PLAN_PRICE_ID', 'quantity' => 1]],
          'mode' => 'subscription',
          'success_url' => 'https://your-domain.com/payment/success?session_id={CHECKOUT_SESSION_ID}',
          'cancel_url' => 'https://your-domain.com/payment/cancel',
          // Optional: A unique ID to link the session to an internal ID of our database
          'client_reference_id' => $user->getId(),
          // Optional: If your internal user already has a Stripe Customer ID from a previous purchase
          'customer' => $user->getCustomerId(),
          // Optional: Stripe will ask the billing address in the payment process
          'billing_address_collection' => 'required',
          // Optional: Preset the email address of the customer
          'customer_email' => $user->getEmail(),
          // Optional: Add discount coupon
          'subscription_data' => ['coupon' => 'YOUR_COUPON_ID'],
        ]);

        return new Response($this->twig->render('checkout.html.twig', [
            'session_id' => $session->id,
        ]));
    }
}

I recommend you to set at least the client_reference_id with unique identifier to retrieve your user in Stripe callback and webhook, and the customer with the customer id provided by Stripe during a previous session.

Note: others options can be set, see subscription documentation and the session API reference.

Then, in your view:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
# checkout.html.twig
<script src="https://js.stripe.com/v3/"></script>
<script>
  var stripe = Stripe('{{ stripe_public_key }}');
  stripe.redirectToCheckout({
    sessionId: '{{ session_id }}'
  }).then(function (result) {
    document.querySelector('.stripe-error').innerHTML = result.error.message;
  });
</script>

This script will redirect the user to Stripe payment page configured according your payment session.

When the user payment is successful, Stripe will automatically create a customer if not exists and a subscription in its database, and redirect the user to your success_url.

If the user cancel the payment, he will be redirected by Stripe to your cancel_url.

Webhook🔗

As the Stripe documentation says, you can't rely on the success redirect for fulfilling purchases. You have to create a webhook on the checkout.session.completed event and get the webhook secret key.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
class WebhookAction
{
    public function __invoke()
    {
        try {
            $event = \Stripe\Webhook::constructEvent(
                $request->getContent(),
                $request->headers->get('Stripe-Signature'),
                'YOUR_WEBHOOK_SECRET'
            );

            /** @var \Stripe\Checkout\Session $session */
            $session = $event->data->object;

            // Your user id
            $clientId = $session->client_reference_id;

            // Stripe customer id
            $customerId = $session->customer->id

            // Stripe subscription id
            $subscriptionId = $session->subscription->id

            // TODO Enable the subscription in your backend

            return new Response('OK', Response::HTTP_OK);
        } catch (\Exception $exception) {
            return new Response($exception->getMessage(), Response::HTTP_BAD_REQUEST);
        }
    }
}

I suggest to store the Stripe customer id on your user to be able to update customer info or to use the same customer for future payment or subscription.

I suggest to store the Stripe subscription id in the database with the user id, the domain subscription plan and the date to be able to update the subscritpion later.

Cancel a subscription🔗

You can cancel a customer subscription immediatly:

1
\Stripe\Subscription::retrieve('USER_SUBSCRIPTION_ID')->cancel()

Or cancel it at the date of your choice by updating its cancel_at property:

1
2
3
\Stripe\Subscription::update('USER_SUBSCRIPTION_ID', [
    'cancel_at' => (new \DateTime())->getTimestamp(),
]);

Or ask Stripe to automatically cancel the subscription at the end of the period (end of the month of monthly subscription for example):

1
2
3
\Stripe\Subscription::update('USER_SUBSCRIPTION_ID', [
    'cancel_at_period_end' => true,
]);

Note: More options in the cancel subscription documentation.

Change plan🔗

You can change your user plan by updating its subscription:

1
2
3
4
5
6
7
8
9
$subscription = \Stripe\Subscription::retrieve($subscription->getSubscriptionId());

\Stripe\Subscription::update($subscription->id, [
    'cancel_at_period_end' => false,
    'items' => [[
        'id' => $subscription->items->data[0]->id,
        'price' => 'NEW_PLAN_PRICE_ID',
    ]],
]);

Note: Stripe can automatically prorate charged price based on previous plan. See subscription update documentation.

Handle trials🔗

You may want to offer trial periods to your customers. Stripe can handle trial periods but it requires users to subscribe and enter their credit card info. The credit card will not be charged until the end of the trial period. Users have to end the subscribtion if they don't want to be charged.

If you don't want your user to enter their credit card in order to get trial period, I suggest you to handle trial periods yourself and require Stripe subscription after the trial period.

Their is 3 way to set trial periods when creating Stripe payment session.

Option 1, provide the trial period end date:

1
2
3
4
5
$session = \Stripe\Checkout\Session::create([
  // ...

  'trial_end' => (new \DateTime('+20 days'))->getTimestamp(),
]);

Option 2, provide the trial period duration in days:

1
2
3
4
5
$session = \Stripe\Checkout\Session::create([
  // ...

  'trial_period_days' => 20,
]);

Option 3, use the trial period duration defined on plan:

1
2
3
4
5
$session = \Stripe\Checkout\Session::create([
  // ...

  'trial_from_plan' => true,
]);

You can set trial periods duration on plans with the trial_period_days property.

One-time payment🔗

Setup🔗

Create your products in https://dashboard.stripe.com/products with a price.

Get the ID of each price, that's what we will send to Stripe to create payment. Eventualy store these ID in database if your products are.

Database model suggestion:

Note: properties starting with a * come from Stripe

Build-in process🔗

If your use-case is simple, you can use the Stripe built-in one-time payment process.

Create a payment session in your controller.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
class CheckoutAction
{
    public function __invoke()
    {
        \Stripe\Stripe::setApiKey('YOUR_API_KEY');

        $session = \Stripe\Checkout\Session::create([
          'payment_method_types' => ['card'],
          'line_items' => [
              ['price' => 'A_PRODUCT_PRICE_ID', 'quantity' => 3],
              ['price' => 'ANOTER_PRODUCT_PRICE_ID', 'quantity' => 1],
          ],
          'mode' => 'payment',
          'success_url' => 'https://your-domain.com/payment/success?session_id={CHECKOUT_SESSION_ID}',
          'cancel_url' => 'https://your-domain.com/payment/cancel',
          // Optional: A unique ID to link the session to an internal ID of our database
          'client_reference_id' => $user->getId(),
          // Optional: If your internal user already has a Stripe Customer ID from a previous purchase
          'customer' => $user->getCustomerId(),
          // Optional: Stripe will ask the billing address in the payment process
          'billing_address_collection' => 'required',
          // Optional: Preset the email address of the customer
          'customer_email' => $user->getEmail(),
          // Optional: Add discount coupon
          'subscription_data' => ['coupon' => 'YOUR_COUPON_ID'],
          // Optional: A collection of key-value pairs, can be retrieved in callbacks and webhooks
          'metadata' => ['foo' => 'bar', 'bar' => 'foo']
        ]);

        return new Response($this->twig->render('checkout.html.twig', [
            'session_id' => $session->id,
        ]));
    }
}

I recommend you to set at least the client_reference_id with unique identifier to retrive your user in Stripe callback and webhook, and the customer with the customer id provided by Stripe during a previous session. Alternatively, you can use the metadata to store information about the order.

In case of products purchase, client_reference_id can be the id of the cart or id of the order.

Note: others options can be set, see payment documentation and the session API reference.

Then, in your view:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
# checkout.html.twig
<script src="https://js.stripe.com/v3/"></script>
<script>
  var stripe = Stripe('{{ stripe_public_key }}');
  stripe.redirectToCheckout({
    sessionId: '{{ session_id }}'
  }).then(function (result) {
    document.querySelector('.stripe-error').innerHTML = result.error.message;
  });
</script>

Webhook🔗

As the Stripe documentation says, you can't rely on the success redirect for fulfilling purchases. You have to create a webhook on the checkout.session.completed event and get the webhook secret key.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
class WebhookAction
{
    public function __invoke()
    {
        try {
            $event = \Stripe\Webhook::constructEvent(
                $request->getContent(),
                $request->headers->get('Stripe-Signature'),
                'YOUR_WEBHOOK_SECRET'
            );

            /** @var \Stripe\Checkout\Session $session */
            $session = $event->data->object;

            // Your user id
            $clientId = $session->client_reference_id;

            // Stripe customer id
            $customerId = $session->customer->id

            // TODO Fulfill the purchase in your backend

            return new Response('OK', Response::HTTP_OK);
        } catch (\Exception $exception) {
            return new Response($exception->getMessage(), Response::HTTP_BAD_REQUEST);
        }
    }
}

I suggest to store the Stripe customer id on your user to be able to update customer info or to use the same customer for future payment or subscription.

I suggest to store the Stripe subscription id in the database with the user id, the domain subscription plan and the date to be able to update the subscritpion later.

Success page🔗

Since we set https://your-domain.com/payment/success?session_id={CHECKOUT_SESSION_ID} as success url, we can get back the session id from it. It allows to retrieve the session and display information to the user.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
class SuccessController
{
    public function __invoke(Request $request)
    {
        $id = $request->query->get('session_id');
        $session = \Stripe\Checkout\Session::retrieve($id);

        return new Response($this->twig->render('success.html.twig', [
            'total' => $session->payment_intent->amount,
        ]));
    }
}

Customer🔗

Before entering into the payment process, you may want to create a customer:

1
2
3
4
5
6
7
8
$customer = Stripe\Customer::create([
    'email' => $user->getEmail(),
    'name' => $user->getFistname() . ' ' . $user->getLastname(),
    'phone' => $user->getPhoneNumber(),
    'description' => 'USER_DESCRIPTION',
]);

$user->setCustomerId($customer->id);

Or update existing customer:

1
2
3
4
5
6
Stripe\Customer::update($user->getCustomerId(), [
    'email' => $user->getEmail(),
    'name' => $user->getFistname() . ' ' . $user->getLastname(),
    'phone' => $user->getPhoneNumber(),
    'description' => 'USER_DESCRIPTION',
]);

Custom process🔗

I you process don't fit the build-in process or if you want to use your own payment page and form instead of Stripe one, you can use Stripe's API to fully custumomize the user experience.

Read the API documentation for further details.

Project references🔗

  • MyJob.Company (subscriptions, monthly/yearly prices and coupons)
Last update: December 20, 2024