# Paddle

Source: https://kart.bnomei.com/docs/providers/paddle
Updated: 2025-08-08T14:20:33+00:00
Summary: Configure Kirby Kart with Paddle: provider & virtual fields, API keys, checkout URL, JS snippet, callbacks, metadata mapping, price-based variants.

> Paddle has no hosted checkout sessions thus their JS library is used as described below.

## Using the provider

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

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

  
## 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.paddle.virtual' => true,
 // 'bnomei.kart.providers.paddle.virtual' => ['raw', 'description', 'gallery', 'downloads', 'price', 'tags', 'categories', 'variants', 'title', 'featured'],

 // other options
];
```

  
## API Credentials

Paddle has a fully separated [sandbox environment](https://www.paddle.com/help/start/set-up-paddle/how-do-i-test-my-checkout-integration). Unlike with other providers you can not switch between sandbox and live environments but need to [create two different accounts](https://sandbox-vendors.paddle.com/onboarding/get-started).

Within the dashboard you can see your current environment in the top-left corner. Head to `Developer Tools > Authentication` and create a new secret API key. The Kirby Kart plugin needs both the secret API key, and the public facing *client-side tokens*. You can set them within the Kirby [configuration](https://kart.bnomei.com/docs/setup/configuration) or use an `.env`-file ([plugin](https://github.com/bnomei/kirby3-dotenv)).

![](https://kart.bnomei.com/media/pages/media/8c65d3ddac-1746706068/paddle-1920x.webp)  
Path: .env  
Code (plaintext):  
```
PADDLE_PUBLIC_TOKEN=XXX
PADDLE_SECRET_KEY=ZZZ
PADDLE_ENDPOINT=https://sandbox-api.paddle.com
# PADDLE_ENDPOINT=https://api.paddle.com
```

  
## Default Checkout URL

You will also need to validate your domain and set the default checkout URL to `https://yourdomain.com/kart/provider-payment`. You can [read more about here](https://developer.paddle.com/errors/transactions/transaction_default_checkout_url_not_set).

This URL should be the URL is defined internally by Kart and matches where you are rendering the `kart/paddle-checkout`-snippet or a customized version of it. You can do so on the `site/templates/payment.php`.

## 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.paddle.checkout_options' => function (\Bnomei\Kart\Kart $kart) {
        // configure the checkout based on current kart instance
        // https://developer.paddle.com/api-reference/transactions/create-transaction
        return [];
    },
    'bnomei.kart.providers.paddle.checkout_line' => function (\Bnomei\Kart\Kart $kart, \Bnomei\Kart\CartLine $line) {
        // add custom data to the current checkout line
        return [];
    },
    // other options
];
```

  
## Paddle Checkout JS

Path: site/templates/payment.php  
Code (php):  
```
<?php snippet('kart/paddle-checkout') ?>

<?php // or create a custom version based on the snippet ?>
<script src="https://cdn.paddle.com/paddle/v2/paddle.js"></script>
<script type="text/javascript">
    Paddle.Initialize({
        ...
    });
</script>
```

  
## Customer Portal

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

Code (php):  
```
<a href="<?= kart()->provider()->portal() ?>">Paddle 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; `filename1.jpg,filename2.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`.