> ## 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.

# Integrate FunnelFox Billing with FunnelFox

> Learn how to connect FunnelFox Billing as your FunnelFox payment provider.

Our team handles most of the integration process, including connecting FunnelFox Billing to your FunnelFox projects, configuring workflows, and more. You only need to complete a few steps on your side.

Start by setting up the Sandbox environment first, then move to Production.

<Tip>Once integrated, you’ll be able to [create products](https://funnelfox.com/docs/dashboard/products) and select FunnelFox Billing as the payment provider for your [Checkout element](/elements/checkout) in FunnelFox.</Tip>

## Sandbox

Follow these steps to set up FunnelFox Billing in your Sandbox environment.

### 1. Get Primer invitation

Your Solution Manager will send you an email invitation to [Primer.io](https://primer.io/).

This is a dedicated Primer Sandbox account we create for your FunnelFox Billing setup.

### 2. Connect your Stripe to Primer

<Info>You can optionally connect a different payment provider instead of Stripe using similar setup steps.</Info>

1. Go to the [Integrations](https://sandbox-dashboard.primer.io/integrations) page in the Primer account we created for you.

2. Click **+ New integration** at the top right.

<Frame>
  <img src="https://mintcdn.com/funnelfox/X1L03E8LxF9D174B/assets/primer-new-integration.png?fit=max&auto=format&n=X1L03E8LxF9D174B&q=85&s=d96d81b1e74ba01d1966eb7a38d574de" width="1920" height="879" data-path="assets/primer-new-integration.png" />
</Frame>

3. Click **Connect** under **Stripe**.

<Frame>
  <img src="https://mintcdn.com/funnelfox/jD67o39RsDgtyUJj/assets/primer-stripe-connect.png?fit=max&auto=format&n=jD67o39RsDgtyUJj&q=85&s=ebe35552dddc9b1ae560f3c137abf25f" width="1920" height="879" data-path="assets/primer-stripe-connect.png" />
</Frame>

4. Click **Connect with Stripe**.

<Frame>
  <img src="https://mintcdn.com/funnelfox/X1L03E8LxF9D174B/assets/primer-connect-with-stripe.png?fit=max&auto=format&n=X1L03E8LxF9D174B&q=85&s=345cecf3b753eaa3b4b54157a5fccd07" width="1920" height="879" data-path="assets/primer-connect-with-stripe.png" />
</Frame>

5. Select your sandbox account and click **Connect**.

<Frame>
  <img src="https://mintcdn.com/funnelfox/jD67o39RsDgtyUJj/assets/primer-select-stripe-acc.png?fit=max&auto=format&n=jD67o39RsDgtyUJj&q=85&s=6c233bae708c95e396d53e29644eea9b" width="1920" height="879" data-path="assets/primer-select-stripe-acc.png" />
</Frame>

After connecting, you'll see the **Webhooks** page in Stripe where you can proceed to the next step.

### 3. Set up Primer webhook

1. Click **+ Add destination** on the [Developers > Webhooks](https://dashboard.stripe.com/webhooks) page in Stripe.

<Frame>
  <img src="https://mintcdn.com/funnelfox/4bfgNRl1wZ2B7XV8/assets/stripe-add-destination.png?fit=max&auto=format&n=4bfgNRl1wZ2B7XV8&q=85&s=7f1970167e400e14dfe48b88a81594c3" width="1920" height="803" data-path="assets/stripe-add-destination.png" />
</Frame>

2. Select **Your account** under **Events from**.

<Frame>
  <img src="https://mintcdn.com/funnelfox/jD67o39RsDgtyUJj/assets/primer-your-account.png?fit=max&auto=format&n=jD67o39RsDgtyUJj&q=85&s=4afcb009ab97639fb4a8f126b4131592" width="1920" height="879" data-path="assets/primer-your-account.png" />
</Frame>

3. Ensure the API version is 2020-03-02 or later.

<Tip>If you're using an older Stripe API version, learn about [Stripe API upgrades](https://docs.stripe.com/upgrades).</Tip>

<Frame>
  <img src="https://mintcdn.com/funnelfox/4bfgNRl1wZ2B7XV8/assets/stripe-api-version.png?fit=max&auto=format&n=4bfgNRl1wZ2B7XV8&q=85&s=5fc2819588c6bd3e40fc29fe1ceb2e29" width="1920" height="879" data-path="assets/stripe-api-version.png" />
</Frame>

4. Select the following events and click **Continue**:

* **payment\_intent.succeeded**
* **payment\_intent.payment\_failed**
* **payment\_intent.processing**
* **payment\_intent.canceled**
* **payment\_intent.amount\_capturable\_updated**
* **payment\_intent.partially\_funded**
* **charge.dispute.created**
* **charge.dispute.closed**

<Frame>
  <img src="https://mintcdn.com/funnelfox/jD67o39RsDgtyUJj/assets/primer-stripe-events.png?fit=max&auto=format&n=jD67o39RsDgtyUJj&q=85&s=c38bf20467494bd0ee234c684fa46935" width="1920" height="879" data-path="assets/primer-stripe-events.png" />
</Frame>

5. Select **Webhook endpoint** under **Destination type** and click **Continue**.

<Frame>
  <img src="https://mintcdn.com/funnelfox/jD67o39RsDgtyUJj/assets/primer-webhook-endpoint.png?fit=max&auto=format&n=jD67o39RsDgtyUJj&q=85&s=66a7d7233951b6d0606db0e693e7ece4" width="1920" height="879" data-path="assets/primer-webhook-endpoint.png" />
</Frame>

6. Go back to the Stripe integration in Primer and copy the endpoint URL under **Set up webhook**.

<Frame>
  <img src="https://mintcdn.com/funnelfox/X1L03E8LxF9D174B/assets/primer-endpoint-url.png?fit=max&auto=format&n=X1L03E8LxF9D174B&q=85&s=8ce3e5c243f93f44574dcf895cc9cf82" width="1920" height="879" data-path="assets/primer-endpoint-url.png" />
</Frame>

7. Go back to webhook configuration in Stripe and paste the endpoint URL into the **Endpoint URL** field.

<Frame>
  <img src="https://mintcdn.com/funnelfox/jD67o39RsDgtyUJj/assets/primer-stripe-paste-url.png?fit=max&auto=format&n=jD67o39RsDgtyUJj&q=85&s=997fdbd5df2e4f22cabfbfe9cccb2a88" width="1920" height="879" data-path="assets/primer-stripe-paste-url.png" />
</Frame>

8. Click **Create destination**.

<Info>Click **Finish** in the Stripe integration in Primer. You can skip the remaining steps about enabling raw card data handling—that section of the Primer guide is outdated.</Info>

### 4. Set up FunnelFox Billing webhook

Repeat the steps above to set up another webhook using a different endpoint URL and events.

1. Click **+ Add destination** on the [Developers > Webhooks](https://dashboard.stripe.com/webhooks) page in Stripe.

2. Select **Your account** under **Events from**.

3. Select the following events and click **Continue**:

* **charge.refunded**
* **charge.succeeded**

<Frame>
  <img src="https://mintcdn.com/funnelfox/jD67o39RsDgtyUJj/assets/primer-stripe-ff-events.png?fit=max&auto=format&n=jD67o39RsDgtyUJj&q=85&s=bb2898a3f6c9b4059a0a8703ffe4dd9e" width="1920" height="879" data-path="assets/primer-stripe-ff-events.png" />
</Frame>

4. Select **Webhook endpoint** under **Destination type** and click **Continue**.

5. Request your **Sandbox Organization ID** (org id) from your Solution manager.

6. Replace `{ORG_ID}` in `https://billing.funnelfox.com/{ORG_ID}/v1/stripe/webhook?region=default` with your Sandbox Organization ID.

<Tip>Your complete endpoint URL will look like `https://billing.funnelfox.com/sndbx_123a4b5678c9d0/v1/stripe/webhook?region=default`.</Tip>

7. Go back to the Stripe webhook configuration and paste the endpoint URL into **Endpoint URL**.

<Frame>
  <img src="https://mintcdn.com/funnelfox/X1L03E8LxF9D174B/assets/primer-paste-ff-url.png?fit=max&auto=format&n=X1L03E8LxF9D174B&q=85&s=d82210c1a9f0acc755b8c6bb907b27c2" width="1920" height="879" data-path="assets/primer-paste-ff-url.png" />
</Frame>

8. Click **Create destination**.

### 5. Configure field mapping

Map required fields in Primer to ensure FunnelFox Billing receives the necessary customer data from Stripe.

1. Go to [Integrations](https://sandbox-dashboard.primer.io/integrations) in Primer and open the Stripe integration you just set up.

2. Click **Manage** at the top right and select **Advanced mapping**.

<Frame>
  <img src="https://mintcdn.com/funnelfox/X1L03E8LxF9D174B/assets/primer-mapping.png?fit=max&auto=format&n=X1L03E8LxF9D174B&q=85&s=90dce7e5f315fd57ad911ea7e7aadf6c" width="1920" height="879" data-path="assets/primer-mapping.png" />
</Frame>

3. Click **Add field** and map the following fields under the **Authorization** tab:

* `ff_org_id`: `metadata[ff_org_id]`
* `ff_country_code`: `payment_method_data[billing_details][address][country]`
* `postal_code`: `payment_method_data[billing_details][address][postal_code]`
* `email`: `payment_method_data[billing_details][email]`

<Frame>
  <img src="https://mintcdn.com/funnelfox/X1L03E8LxF9D174B/assets/primer-mapped-fields.png?fit=max&auto=format&n=X1L03E8LxF9D174B&q=85&s=5115948914cae422be6204115fb67c72" width="1920" height="879" data-path="assets/primer-mapped-fields.png" />
</Frame>

4. Click **Save**.

### 6. Get Support Tool access

Your Solution manager will reach out to provide access to the dedicated FunnelFox Billing dashboard with the Support Tool.

Use the Support Tool to manage subscriptions, process refunds, and view payments, webhooks, and more.

<Check>Your FunnelFox Billing Sandbox setup is complete. Make test payments to verify that everything is configured correctly.</Check>

## Production

After testing in Sandbox, set up FunnelFox Billing for your live environment to start accepting real payments.

Repeat the setup process from the Sandbox section above using the Primer Production account we create for you.

After completing the setup, proceed with configuring Apple Pay, Google Pay, and PayPal.

<Info>
  Before you begin, ensure you have:

  * Your Merchant ID from the [Google Pay & Wallet Console](https://pay.google.com/business/console/home) with a verified business profile.
  * An active PayPal business account.
</Info>

### 1. Set up Apple Pay

1. Go to the [Integrations](https://sandbox-dashboard.primer.io/integrations) page in the Primer account we created for you.

2. Click **+ New integration** at the top right.

<Frame>
  <img src="https://mintcdn.com/funnelfox/X1L03E8LxF9D174B/assets/primer-new-integration.png?fit=max&auto=format&n=X1L03E8LxF9D174B&q=85&s=d96d81b1e74ba01d1966eb7a38d574de" width="1920" height="879" data-path="assets/primer-new-integration.png" />
</Frame>

3. Click **Connect** under **Apple Pay**.

<Frame>
  <img src="https://mintcdn.com/funnelfox/X1L03E8LxF9D174B/assets/primer-connect-apple.png?fit=max&auto=format&n=X1L03E8LxF9D174B&q=85&s=af09fc68a9e739ae79f1c4d7b3ed1d17" width="1920" height="879" data-path="assets/primer-connect-apple.png" />
</Frame>

4. Click **+ Add new domain** and add three domains:

* `cdn.fnlfx.com`.
* Your project domain from [Settings > Domains](/dashboard/settings#domains) in FunnelFox (for example, `demo-app.fnlfx.com`).
* Your custom domain (if any).

<Frame>
  <img src="https://mintcdn.com/funnelfox/X1L03E8LxF9D174B/assets/primer-domains.png?fit=max&auto=format&n=X1L03E8LxF9D174B&q=85&s=5500d87d04e0a1b8881587b559bfc87d" width="1920" height="879" data-path="assets/primer-domains.png" />
</Frame>

5. Go to [Settings > Domains](/dashboard/settings#domains) in FunnelFox.

6. Select **FunnelFox Billing** under **Apple Pay domain verification**.

<Frame>
  <img src="https://mintcdn.com/funnelfox/X1L03E8LxF9D174B/assets/primer-apple-domain.png?fit=max&auto=format&n=X1L03E8LxF9D174B&q=85&s=af54d87efef00694307216c3c5b97768" width="1920" height="879" data-path="assets/primer-apple-domain.png" />
</Frame>

7. Save changes.

### 2. Set up Google Pay

1. Click **+ New integration** on the [Integrations](https://sandbox-dashboard.primer.io/integrations) page in Primer.

2. Click **Connect** under **Google Pay**.

<Frame>
  <img src="https://mintcdn.com/funnelfox/X1L03E8LxF9D174B/assets/primer-connect-gpay.png?fit=max&auto=format&n=X1L03E8LxF9D174B&q=85&s=2000aba6dcef3e97a1e4337841b54a35" width="1920" height="879" data-path="assets/primer-connect-gpay.png" />
</Frame>

3. Enter your Google Pay merchant details and click **Connect**:

* **Merchant ID**
* **Merchant Name**

<Frame>
  <img src="https://mintcdn.com/funnelfox/X1L03E8LxF9D174B/assets/primer-connect-gpay-2.png?fit=max&auto=format&n=X1L03E8LxF9D174B&q=85&s=4ea7ef4931d66af7dac4d3ce7c551a2a" width="1920" height="879" data-path="assets/primer-connect-gpay-2.png" />
</Frame>

4. Go to the Business profile page in your [Google Pay & Wallet Console](https://pay.google.com/business/console/home) and verify your business profile is complete.

<Frame>
  <img src="https://mintcdn.com/funnelfox/Ex0bwYVU0x5LL0sH/assets/gpay-incomplete.png?fit=max&auto=format&n=Ex0bwYVU0x5LL0sH&q=85&s=66abf12918b22ba56faec47dbd9afa48" width="1920" height="879" data-path="assets/gpay-incomplete.png" />
</Frame>

5. Go to **Google Pay API > Web integration**.

<Frame>
  <img src="https://mintcdn.com/funnelfox/Ex0bwYVU0x5LL0sH/assets/gpay-web-integration.png?fit=max&auto=format&n=Ex0bwYVU0x5LL0sH&q=85&s=79ae87e79a5b38ca7ba6ed0391b7d70b" width="1920" height="879" data-path="assets/gpay-web-integration.png" />
</Frame>

6. Complete the form and click **Submit for approval**:

* **Website URL**: Enter the domain you’d like to integrate with. If you have multiple domains, enter the main one.
* **Integration type**: Gateway.
* **Screenshots of your buyflow**: Upload screenshots of your buyflow with the Google Pay API (1MB max).

<Accordion title="Use the screenshots below when submitting your buyflow:">
  <Frame>
    <img src="https://mintcdn.com/funnelfox/hPONIN2BagaymXqk/assets/buyflow-1.jpg?fit=max&auto=format&n=hPONIN2BagaymXqk&q=85&s=4420fddd6c607c05c19047be6bb9b1eb" width="1080" height="2400" data-path="assets/buyflow-1.jpg" />
  </Frame>

  <Frame>
    <img src="https://mintcdn.com/funnelfox/hPONIN2BagaymXqk/assets/buyflow-2.jpg?fit=max&auto=format&n=hPONIN2BagaymXqk&q=85&s=fc5811f2cedfe5472d6d1973c4b7c7b8" width="1080" height="2400" data-path="assets/buyflow-2.jpg" />
  </Frame>
</Accordion>

### 3. Set up PayPal

1. Click **+ New integration** on the [Integrations](https://sandbox-dashboard.primer.io/integrations) page in Primer.

2. Click **Connect** under **PayPal**.

<Frame>
  <img src="https://mintcdn.com/funnelfox/X1L03E8LxF9D174B/assets/primer-connect-paypal.png?fit=max&auto=format&n=X1L03E8LxF9D174B&q=85&s=37ec3b94a0e5d2cafa5aea72218891d2" width="1920" height="879" data-path="assets/primer-connect-paypal.png" />
</Frame>

3. Go to [Apps & Credentials](https://developer.paypal.com/dashboard/applications/sandbox) in your PayPal Developer dashboard and open your app under **REST API apps**.

<Frame>
  <img src="https://mintcdn.com/funnelfox/X1L03E8LxF9D174B/assets/paypal-api-creds.png?fit=max&auto=format&n=X1L03E8LxF9D174B&q=85&s=6509c9ff7d1b5cbc20ef25b240b71e94" width="1920" height="879" data-path="assets/paypal-api-creds.png" />
</Frame>

4. Copy your PayPal API credentials and paste them in Primer:

* **Account**: Email address associated with the PayPal app under the **Account info**.
* **Client ID**: Public API identifier for the PayPal app under the **API credentials**.
* **Secret**: API secret key for the PayPal app under the **API credentials**.
* **Landing Page**: Billing page.

<Frame>
  <img src="https://mintcdn.com/funnelfox/X1L03E8LxF9D174B/assets/primer-paypal-config.png?fit=max&auto=format&n=X1L03E8LxF9D174B&q=85&s=107ee7224e6736ba5fc536be70403abb" width="1920" height="879" data-path="assets/primer-paypal-config.png" />
</Frame>

4. Click **Connect**.

5. Go back to your app page under [Apps & Credentials](https://developer.paypal.com/dashboard/applications/sandbox) in the PayPal Developer dashboard and ensure **Save payment methods** is enabled.

This allows the Vault API to save customer payment methods for faster checkout.

6. Contact PayPal Support and request to enable [Reference transactions](https://developer.paypal.com/docs/checkout/advanced/customize/reference-transactions/).

Reference transactions allow you to charge customers using their saved payment method.

<Check>Your FunnelFox Billing Production setup is complete. Make test payments to verify that everything is configured correctly.</Check>