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

# Paddle payment integration

> Integrate Paddle as your payment provider in FunnelFox. Step-by-step setup for web subscriptions, checkouts, and recurring billing.

Paddle is a payment integration for FunnelFox that provides global
payment processing, advanced subscription management, and
support for multiple payment methods.

## Key features

The FunnelFox integration with Paddle supports multiple payment methods and transaction types:

| Transaction type               | Cards | Apple Pay | Google Pay | PayPal |
| ------------------------------ | :---: | :-------: | :--------: | :----: |
| **Subscriptions**              |       |           |            |        |
| Subscriptions                  |   ✅   |     ✅     |      ✅     |    ✅   |
| Free & paid trials             |   ✅   |     ✅     |      ✅     |    ✅   |
| **Upsells**                    |       |           |            |        |
| One-time products              |   ✅   |     ✅     |      ✅     |    ✅   |
| Subscription upsells (2nd sub) |   ❌   |     ❌     |      ❌     |    ❌   |
| Subscription upsells (upgrade) |   ✅   |     ✅     |      ✅     |    ✅   |
| **Offers**                     |       |           |            |        |
| Intro offers                   |   ✅   |     ✅     |      ✅     |    ✅   |
| Discount codes                 |   ✅   |     ✅     |      ✅     |    ✅   |

Learn more about [configuring each transaction type](/integrations/payments/paddle#subscription-configuration) in your funnel.

### Additional features

* **Cancellation funnels**: Full support for [cancellation flows](/dashboard/funnels#cancellation-funnels) with options to offer discounted subscriptions, gifts, or pauses instead of losing customers completely.
* **Apple Pay Express Checkout**: Seamless one-click payment experience similar to a wallet button.
* **Failed payment recovery**: When payment fails for automatically-collected subscriptions, [Paddle automatically retries](https://developer.paddle.com/build/retain/set-up-retain-profitwell) the saved payment method.

## Setup

<Tip>To simplify Paddle account verification, use your FunnelFox project subdomain `[your project].fnlfx.com` as the domain in Paddle.</Tip>

The following steps are for production setup using your verified live Paddle account. If you need to configure a sandbox environment for testing, the process is identical, but:

* Create a Paddle Sandbox account at [https://sandbox-vendors.paddle.com/signup](https://sandbox-vendors.paddle.com/signup).
* Use the Sandbox fields instead of Production fields when pasting keys in FunnelFox.

Learn more about [Sandbox in Paddle](https://developer.paddle.com/build/tools/sandbox).

### 1. API key

1. Go to [Developer Tools > Authentication](https://vendors.paddle.com/authentication-v2) in Paddle.
2. Click **+ New API key**.

<Frame>
  <img src="https://mintcdn.com/funnelfox/WE4aqGorvrBuF8f8/assets/new-api-key.png?fit=max&auto=format&n=WE4aqGorvrBuF8f8&q=85&s=731010020b2d035a9f6cc32339fbcf12" width="1921" height="879" data-path="assets/new-api-key.png" />
</Frame>

3. Configure your API key with the following details, then click **Save**:
   * **Name**: FunnelFox
   * **Expires at**: Never expires
   * **Permissions**: Set the permissions as shown in the table below

| Permission                     | Read | Write |
| ------------------------------ | ---- | ----- |
| Addresses                      | ✅    |       |
| Adjustments                    | ✅    |       |
| Businesses                     | ✅    |       |
| Client-side tokens             |      | ✅     |
| Customer portal sessions       |      |       |
| Customer authentication tokens |      | ✅     |
| Customers                      |      | ✅     |
| Discounts                      |      | ✅     |
| Notification settings          |      | ✅     |
| Notifications                  |      | ✅     |
| Notification simulations       | ✅    |       |
| Payment methods                |      | ✅     |
| Prices                         |      | ✅     |
| Products                       |      | ✅     |
| Reports                        |      | ✅     |
| Subscriptions                  |      | ✅     |
| Transactions                   |      | ✅     |

<Frame>
  <img src="https://mintcdn.com/funnelfox/hJHhcQt1L345h34q/assets/paddle-permissions.gif?s=d8a571be412f5b4e7ac11ce81d80f101" width="1920" height="880" data-path="assets/paddle-permissions.gif" />
</Frame>

4. Copy your API key.

<Warning>You won't be able to view the API key again in Paddle.</Warning>

<Frame>
  <img src="https://mintcdn.com/funnelfox/Fhm8L6WWrlD28zfY/assets/paddle-copy-key.png?fit=max&auto=format&n=Fhm8L6WWrlD28zfY&q=85&s=b2681ab608adc3d3a72d2d729be66004" width="1920" height="879" data-path="assets/paddle-copy-key.png" />
</Frame>

5. Go to [Integrations > Paddle](https://app.funnelfox.com/integrations/paddle) in FunnelFox.
6. Paste the API key into the **API key** field under the **Production** section.

<Info>Don't close your Paddle integration settings in FunnelFox and proceed with the next section.</Info>

<Frame>
  <img src="https://mintcdn.com/funnelfox/CL6JlZm0xbv0vPRH/assets/paddle-production-api.png?fit=max&auto=format&n=CL6JlZm0xbv0vPRH&q=85&s=08de1432b5f10bf92aeacf4a610995e3" width="1920" height="879" data-path="assets/paddle-production-api.png" />
</Frame>

### 2. Client-side token

1. Go to the **Client-side tokens** tab of [Developer Tools > Authentication](https://vendors.paddle.com/authentication-v2) in Paddle.
2. Click **+ New Client-side token**.

<Frame>
  <img src="https://mintcdn.com/funnelfox/Fhm8L6WWrlD28zfY/assets/paddle-new-token.png?fit=max&auto=format&n=Fhm8L6WWrlD28zfY&q=85&s=87bf11c8d9368f93bd95c65cb0b9820e" width="1921" height="879" data-path="assets/paddle-new-token.png" />
</Frame>

3. Name your token and click **Save**.

<Frame>
  <img src="https://mintcdn.com/funnelfox/Fhm8L6WWrlD28zfY/assets/paddle-name-token.png?fit=max&auto=format&n=Fhm8L6WWrlD28zfY&q=85&s=d8b2e34956821ad30d786c49682a22da" width="1920" height="879" data-path="assets/paddle-name-token.png" />
</Frame>

4. Go back to [Integrations > Paddle](https://app.funnelfox.com/integrations/paddle) in FunnelFox.
5. Paste the client-side token into the **Client-side token** field under the **Production** section.

<Frame>
  <img src="https://mintcdn.com/funnelfox/CL6JlZm0xbv0vPRH/assets/paddle-paste-token.png?fit=max&auto=format&n=CL6JlZm0xbv0vPRH&q=85&s=ee368180bedf0cfe16e68f0158b7a7d2" width="1920" height="879" data-path="assets/paddle-paste-token.png" />
</Frame>

6. Click **Save changes**.

### 3. Payment link

1. Go to [Settings > Domains](https://app.funnelfox.com/settings/domains) in FunnelFox.
2. Copy your project subdomain from the **Hosted subdomain** section (for example: `https://demo-app.fnlfx.com/`).

<Frame>
  <img src="https://mintcdn.com/funnelfox/Fhm8L6WWrlD28zfY/assets/paddle-subdomain.png?fit=max&auto=format&n=Fhm8L6WWrlD28zfY&q=85&s=dfbdd922e1fa558ef757155ddedf6667" width="1920" height="879" data-path="assets/paddle-subdomain.png" />
</Frame>

3. Go to [Checkout > Checkout settings](https://vendors.paddle.com/checkout-settings) in Paddle.
4. Paste your subdomain into the **Default payment link** section.

<Frame>
  <img src="https://mintcdn.com/funnelfox/Fhm8L6WWrlD28zfY/assets/paddle-link.png?fit=max&auto=format&n=Fhm8L6WWrlD28zfY&q=85&s=d0db0e2ea5f341a21865ea1791d18b59" width="1920" height="879" data-path="assets/paddle-link.png" />
</Frame>

5. Click **Save** at the top right of the page.

<Check>Your Paddle integration is now active! Remember to republish your funnels to apply the changes.</Check>

<Frame>
  <img src="https://mintcdn.com/funnelfox/Fhm8L6WWrlD28zfY/assets/paddle-save.png?fit=max&auto=format&n=Fhm8L6WWrlD28zfY&q=85&s=9cf17976efc43d3e859e2d325a1d9ac6" width="1921" height="879" data-path="assets/paddle-save.png" />
</Frame>

## Subscription configuration

After setup, FunnelFox automatically creates webhooks in your Paddle account and syncs your products.

Products created in Paddle become available in the **Element** tab of your [Checkout element](/elements/checkout#subscription-configuration).

Configure Paddle products in your funnels:

* [Free trial](/elements/checkout#free-trial)
* [Paid trial](/elements/checkout#paid-trial)
* [Intro offers](/elements/checkout#offers)
* [Upsell](/elements/checkout#upsell)

<Frame>
  <img src="https://mintcdn.com/funnelfox/Ji7_s9Rh2wfOcnaz/assets/paddle-products.png?fit=max&auto=format&n=Ji7_s9Rh2wfOcnaz&q=85&s=342d5b98d2cbfa16fff4f323d18fc1a9" width="1124" height="855" data-path="assets/paddle-products.png" />
</Frame>

## Digital wallets

FunnelFox supports Apple Pay and Google Pay with Paddle for
faster checkout.

Apple Pay requires verifying your domain enables a smoother one-click experience. Google Pay works by
default.

### Apple Pay

Paddle supports two ways to use Apple Pay:

* [Apple Pay Express Checkout](/integrations/payments/paddle#apple-pay-express-checkout): Provides a seamless one-click payment experience similar to a wallet button. It prioritizes Apple Pay by showing it first to customers, while other payment methods are placed under the **Pay another way** button.

<Frame>
  <img src="https://mintcdn.com/funnelfox/GILyJ770Z6E1cwpK/assets/paddle-express-example.jpg?fit=max&auto=format&n=GILyJ770Z6E1cwpK&q=85&s=532f59e8f8919f38211b3ab3c045f3aa" style={{width: "300px", height: "auto"}} width="1179" height="2152" data-path="assets/paddle-express-example.jpg" />
</Frame>

* [One-page or multi-page checkout](/integrations/payments/paddle#one-page-or-multi-page-checkout): Shows Apple Pay alongside other payment methods during checkout.

<Frame>
  <img src="https://mintcdn.com/funnelfox/GILyJ770Z6E1cwpK/assets/paddle-apple-pay.jpg?fit=max&auto=format&n=GILyJ770Z6E1cwpK&q=85&s=72f46f6db82a6442f8eedd21d195f53a" style={{width: "300px", height: "auto"}} width="1179" height="2139" data-path="assets/paddle-apple-pay.jpg" />
</Frame>

<Info>Apple Pay is shown in Paddle checkout only if the user has a card added
to their wallet.</Info>

#### Apple Pay Express Checkout

To enable a seamless one-click payment experience similar to a wallet button:

1. [Verify your domain](/integrations/payments/paddle#domain-verification) in order to offer the one-click experience in express checkout.

2. Configure your [Checkout element](/elements/checkout#paddle-2):

* **Variant**: Express (Apple Pay).
* **Show Pay another way**: Adds a button to select another payment method or use them as a fallback.

<Frame>
  <img src="https://mintcdn.com/funnelfox/GILyJ770Z6E1cwpK/assets/paddle-express-checkout.png?fit=max&auto=format&n=GILyJ770Z6E1cwpK&q=85&s=5d220b8162efc8e430b3ee3740167f39" width="1176" height="979" data-path="assets/paddle-express-checkout.png" />
</Frame>

Customer email is resolved differently depending on whether an email is collected before the Checkout element:

* **If no email is collected before your Checkout element**: Paddle creates the customer using
  the email from the Apple Pay wallet settings.
* **If an email is collected before Checkout element**: That email
  takes priority over the wallet email.

#### One-page or multi-page checkout

To show Apple Pay alongside other payment methods during checkout:

1. [Verify your domain](/integrations/payments/paddle#domain-verification) for a smooth one-click experience without
   popups. On unverified domains, Paddle opens a
   popup that launches the Apple
   Pay modal.

2. Configure the **Variant** field in your [Checkout element](/elements/checkout#paddle-2) as one-page or multi-page.

<Frame>
  <img src="https://mintcdn.com/funnelfox/GILyJ770Z6E1cwpK/assets/paddle-variant-onepage.png?fit=max&auto=format&n=GILyJ770Z6E1cwpK&q=85&s=0bfd9d29bf08648855412c0b1b655310" width="1169" height="978" data-path="assets/paddle-variant-onepage.png" />
</Frame>

3. Enable Apple Pay as a payment method in your Checkout element.

<Frame>
  <img src="https://mintcdn.com/funnelfox/GILyJ770Z6E1cwpK/assets/paddle-all-methods.png?fit=max&auto=format&n=GILyJ770Z6E1cwpK&q=85&s=156b7b80bb50b1265f3bfb390c159970" width="1171" height="978" data-path="assets/paddle-all-methods.png" />
</Frame>

#### Domain verification

To verify your domain:

1. Go to **Checkout > Website approval > Domain approval** in your Paddle
   dashboard.
2. Click **+ Add a new domain**.

<Frame>
  <img src="https://mintcdn.com/funnelfox/Er_-9kIw2rAXBhZP/assets/paddle-verify-domain.png?fit=max&auto=format&n=Er_-9kIw2rAXBhZP&q=85&s=0f93513f9cb18b6b371872f896899bb6" width="1920" height="989" data-path="assets/paddle-verify-domain.png" />
</Frame>

3. Add your project domain from [Settings > Domains](https://app.funnelfox.com/settings/domains)
   in FunnelFox and click **Save**. If you have a custom domain, add it as
   well.

<Frame>
  <img src="https://mintcdn.com/funnelfox/Er_-9kIw2rAXBhZP/assets/paddle-verified-domains.png?fit=max&auto=format&n=Er_-9kIw2rAXBhZP&q=85&s=d4670bc236e87c000ef32640703e5bb6" width="1920" height="989" data-path="assets/paddle-verified-domains.png" />
</Frame>

4. Go to [Settings > Domains](https://app.funnelfox.com/settings/domains) in
   FunnelFox.
5. Select **Paddle** under **Apple Pay domain verification**.

<Frame>
  <img src="https://mintcdn.com/funnelfox/Er_-9kIw2rAXBhZP/assets/paddle-select-domain.png?fit=max&auto=format&n=Er_-9kIw2rAXBhZP&q=85&s=cafc53e1dcac704c5b12c6d9af392efd" width="1920" height="989" data-path="assets/paddle-select-domain.png" />
</Frame>

6. Click **Save**.

<Check>One-click Apple Pay button will become available in your checkout after
domain verification completes.</Check>

### Google Pay

Google Pay checkout buttons with Paddle works by default and requires no additional
configuration.

Enable Google Pay as [payment method for Paddle](/elements/checkout#paddle-2) in your Checkout element.

## Testing

Test your Paddle integration with simulated payments before going live.

1. Configure the test in your Checkout element's **Sandbox** section.

<Frame>
  <img src="https://mintcdn.com/funnelfox/Ji7_s9Rh2wfOcnaz/assets/paddle-test-sandbox.png?fit=max&auto=format&n=Ji7_s9Rh2wfOcnaz&q=85&s=8a191d0767027b301547e88060a77621" width="1131" height="865" data-path="assets/paddle-test-sandbox.png" />
</Frame>

2. Open your funnel in **Preview** mode.

<Frame>
  <img src="https://mintcdn.com/funnelfox/Ji7_s9Rh2wfOcnaz/assets/paddle-test-preview.png?fit=max&auto=format&n=Ji7_s9Rh2wfOcnaz&q=85&s=237e3846fdfa17ef7e1525e90e2b6ae4" width="1132" height="864" data-path="assets/paddle-test-preview.png" />
</Frame>

3. Use these Paddle test cards with any future expiry date and `100` as CVV:

| Card Number         | Result                                                           |
| ------------------- | ---------------------------------------------------------------- |
| 4242 4242 4242 4242 | Success                                                          |
| 4000 0000 0000 0002 | Declined                                                         |
| 4000 0027 6000 3184 | Successful initial transaction, subsequent declined transactions |

Learn more about [Paddle test cards](https://developer.paddle.com/concepts/payment-methods/credit-debit-card#test-payment-method).

## Troubleshooting

<AccordionGroup>
  <Accordion title="Something went wrong (Checkout error)">
    This error often occurs when your setup is missing the default payment link:

    <Frame>
      <img src="https://mintcdn.com/funnelfox/7fGWEHFZ0eAsO1GP/assets/something-went-wrong.png?fit=max&auto=format&n=7fGWEHFZ0eAsO1GP&q=85&s=94659679f64892105fc77ff42e4b9cc5" style={{ width: '350px', height: 'auto' }} width="813" height="865" data-path="assets/something-went-wrong.png" />
    </Frame>

    1. Go to [Checkout > Checkout settings](https://vendors.paddle.com/checkout-settings) in Paddle.
    2. Check if you have the link set under the **Default payment link**.
    3. If not, go to [Settings > Domains](https://app.funnelfox.com/settings/domains) in FunnelFox.
    4. Copy your project subdomain from the **Hosted subdomain** section (for example: `https://demo-app.fnlfx.com/`).
    5. Paste your project subdomain under the **Default payment link**.
    6. Click **Save** at the top right, then republish your funnel.
  </Accordion>
</AccordionGroup>

## Next steps

* [Set up checkout element](/elements/checkout) in your funnel