# Stripe

Source: https://kart.bnomei.com/docs/providers/stripe
Updated: 2025-10-23T10:43:07+00:00
Summary: Configure Stripe in Kirby Kart plugin: set test & live secret keys, virtual fields, custom checkout, customer portal, metadata mapping & variants from prices.

## Using the provider

Path: site/config/config.php  
Code (php):  
```
<?php

return [
   'bnomei.kart.provider' => 'stripe',
   // other options
];
```

  
## Account

You need to create a [Stripe](https://stripe.com/) account.

## Setup your Products

This provider is designed to sync products from Stripe to Kirby. It cannot be used solely for processing payments. After creating your Stripe account, set up at least one product with a price in Stripe. Once you've configured your credentials in the settings (see below), the Kart plugin will fetch that product.

## Test Mode and Secret Key

Ensure you are in **Test Mode** or a **Sandbox** and retrieve your **Stripe Secret Key** from the Stripe Dashboard.

![](https://kart.bnomei.com/media/pages/media/555b736d08-1746706067/klub-stripe-test-mode-1920x.webp)  
![](https://kart.bnomei.com/media/pages/media/36b18a14ab-1746706062/dashboard.stripe.com_test_apikeys-1440-3xl-1920x.webp)  
## Configuration

Create a default configuration for the default with the Stripe `STRIPE_SECRET_KEY_TEST`.

Path: site/config/config.php  
Code (php):  
```
<?php

return [
  'bnomei.kart.provider' => 'stripe',
  'bnomei.kart.providers.stripe.secret_key' => fn() => env('STRIPE_SECRET_KEY_TEST'),
  // other options
];
```

  
For your production domain I would recommend you create an additional configuration file and set the secret to either a different environment variable `STRIPE_SECRET_KEY_LIVE`.

Path: site/config/config.www.yourwebsite.com.php  
Code (php):  
```
<?php

return [
  'bnomei.kart.provider' => 'stripe',
  'bnomei.kart.providers.stripe.secret_key' => fn() => env('STRIPE_SECRET_KEY_LIVE'),
  // other options
];
```

  
You need to provide the credentials as config values as shown above or via an `.env` file ([plugin](https://github.com/bnomei/kirby3-dotenv)).

Path: .env  
Code (plaintext):  
```
STRIPE_SECRET_KEY_TEST=XXX
STRIPE_SECRET_KEY_LIVE=ZZZ
```

  
## Virtual Fields

You can define which fields are treated as purely virtual and fetched from the provider ignoring any changes you make within the panel.

Code (php):  
```
<?php

return [
 'bnomei.kart.providers.stripe.virtual' => true,
 // 'bnomei.kart.providers.stripe.virtual' => ['raw', 'description', 'gallery', 'downloads', 'price', 'tags', 'categories', 'variants', 'title', 'featured'],

 // other options
];
```

  
## Customzing the Checkout

You can use callbacks to customise both the checkout process and each line item. The returned arrays from your callbacks will be merged with the defaults created by the plugin for this provider, allowing you to override those defaults. Check the relevant PHP class and the linked online documentation for the provider to learn more about the expected data structure.

Code (php):  
```
<?php

return [
    'bnomei.kart.providers.stripe.checkout_options' => function (\Bnomei\Kart\Kart $kart) {
        // configure the checkout based on current kart instance
        // https://docs.stripe.com/api/checkout/sessions/create
        return [];
    },
    'bnomei.kart.providers.stripe.checkout_line' => function (\Bnomei\Kart\Kart $kart, \Bnomei\Kart\CartLine $line) {
        // add custom data to the current checkout line
        return [];
    },
    // other options
];
```

  
## API Version

You might want to react to the session data sent from Stripe at some point in your business logic. Within the [Stripe Developer Dashboard](https://dashboard.stripe.com/test/workbench/overview) you can set the API Version your account uses. Ensure you use the same version set in the dashboard when [browsing their API docs](https://docs.stripe.com/api) for both the API and SDK.

The Kart plugin uses plain POST requests to the Stripe API and such is always the version you choose within the Stripe dashboard.

![](https://kart.bnomei.com/media/pages/media/230100301a-1746706069/stripe-dashboard-workbench-api-version-1920x.webp)  
![](https://kart.bnomei.com/media/pages/media/21f5dba8c2-1746706070/stripe-docs-api-sdk-verions-dropdown-1920x.webp)  
## Customer Portal

You can link your customers to the provider portal with this code.

Code (php):  
```
<a href="<?= kart()->provider()->portal() ?>">Stripe Portal</a>
```

  
## Values from metadata

You can link categories, tags, gallery images, downloads, and the featured option from a product's metadata with a key to a value.

- `categories` =&gt; `evil`
- `tags` =&gt; `light,red`
- `gallery` =&gt; `filename_1.jpg,filename_2.jpg`
- `downloads` =&gt; `nice-song.mp3`
- `featured` =&gt; `true`

## Variants from prices

The Kirby Kart plugin will create a variant for each price. You can set custom metadata (in the price) with a key `variant`, a comma-separated string of `group:option` pairs, like `size:M,color:Sky Blue`.