> ## Documentation Index
> Fetch the complete documentation index at: https://docs.komerza.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Setup Paddle

> Configure Paddle payments on your Komerza store

Accept payments through Paddle on your Komerza store. Paddle handles the checkout UI — your customers are redirected to a secure Paddle-hosted payment page, then returned to your store once payment is complete.

## Prerequisites

* A [Paddle account](https://www.paddle.com/) (free to create)

<Steps>
  <Step title="Get Your Paddle API Key">
    1. Log into your [Paddle Dashboard](https://vendors.paddle.com/)
    2. Go to **Developer Tools → Authentication**
    3. Click **Generate API Key**
    4. Copy the key — it starts with `pdl_live_`

    <Note>
      **Testing first?** Use the [Sandbox Dashboard](https://sandbox-vendors.paddle.com/) instead. Sandbox keys start with `pdl_test_` and no real money is charged.
    </Note>
  </Step>

  <Step title="Connect Paddle to Komerza">
    1. In your Komerza dashboard, go to **Payment Methods**
    2. Find **Paddle** and click **Configure**
    3. Paste in your **API Key** (from Step 1)
    4. Click **Save**

    Komerza automatically creates the webhook endpoint on your Paddle account. No manual webhook configuration needed.
  </Step>

  <Step title="Verify the Connection">
    Go to **Payment Methods → Paddle** in your dashboard. The status will show:

    * **Active** — Everything is connected and working
    * **Inactive** — Check that your API key is correct

    <Note>
      If the status shows **Inactive**, double-check that your API key starts with `pdl_live_` (or `pdl_test_` for sandbox).
    </Note>
  </Step>
</Steps>

## How It Works

1. A customer selects Paddle at checkout
2. They're redirected to Paddle's secure hosted checkout page
3. After paying, they're sent back to your store with a confirmation
4. Komerza receives a webhook from Paddle confirming the payment and delivers the order automatically

## Managing Payments

* **Refunds** — You can issue full refunds through Komerza. The refund is processed via Paddle's system and the customer is credited back.
* **Disputes** — If a customer opens a dispute with their bank, you'll receive a notification in Komerza. The order is marked as disputed and you can respond through Paddle's dashboard.

## Sandbox Testing

If you want to test before going live:

1. Create a [Sandbox account](https://sandbox-vendors.paddle.com/)
2. Use your sandbox API key (`pdl_test_...`)
3. No real charges are made — you can test the full flow safely
4. When ready, disconnect and reconnect with your production API key

## Disconnecting Paddle

Go to **Payment Methods → Paddle** and click **Disconnect**. This also removes the webhook endpoint from your Paddle account. Your existing orders are not affected — only new checkouts will no longer offer Paddle.

## Troubleshooting

| Problem                             | Fix                                                                                       |
| ----------------------------------- | ----------------------------------------------------------------------------------------- |
| Payments not completing             | Check that your API key is valid and starts with `pdl_live_` (or `pdl_test_` for sandbox) |
| Inactive status                     | Double-check your API key in **Payment Methods → Paddle**                                 |
| Not receiving dispute notifications | Contact support — the webhook may need to be recreated (disconnect and reconnect Paddle)  |