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

# Connect Stripe Direct

> Connect the customer's own Stripe account, recurring Price, tax settings, and webhook to FloKit.AI.

Stripe Direct connects the customer's own Stripe account to FloKit. The customer
remains the Merchant of Record, Stripe settles funds directly to that account,
and FloKit uses the connected account to create the approved subscription
checkout.

FloKit currently connects Stripe Direct with a secret key and matching
publishable key. Stripe Connect OAuth is not part of the production setup.

## Decisions to make first

### Does the launch use Stripe Billing?

The current Stripe Direct checkout creates a Stripe **subscription** Checkout
Session. The selected offer must use an active recurring Stripe Price.

If the customer is not using Stripe Billing, or the first offer is a one-time
payment, stop before connecting the account and agree on a different checkout
setup.

### Which Product and Price will be sold?

FloKit imports existing Stripe Products and Prices as read-only records. FloKit
does not create or edit the customer's Stripe catalog.

Prepare one active recurring Price for the first launch and confirm:

* Product name;
* Price ID;
* amount and currency;
* monthly or annual interval;
* trial length, if any;
* whether promotion codes are allowed; and
* the entitlement or access granted after purchase.

Test-mode and live-mode Products and Prices are separate. A test Price ID cannot
be reused in live mode.

### How will tax be handled?

FloKit does not activate Stripe Tax for the customer.

* When Stripe reports that Stripe Tax is active on the connected account,
  FloKit enables automatic tax on the Checkout Session.
* When Stripe Tax is not active, FloKit omits automatic tax.

The customer should decide whether Stripe Tax is required for the initial launch
and complete that setup in Stripe before qualification.

## What is needed from the customer

| Input                | Requirement                                                               |
| -------------------- | ------------------------------------------------------------------------- |
| Stripe administrator | Access to the correct Test or Live Stripe account                         |
| Secret key           | The key for the selected environment                                      |
| Publishable key      | The matching key for the same environment and account                     |
| Product and Price    | One active recurring Stripe Price for the first offer                     |
| Billing decision     | Confirmation that Stripe Billing subscriptions are the intended model     |
| Tax decision         | Confirmation that Stripe Tax is active now or intentionally left inactive |
| Trial and promotions | Trial days and whether promotion codes should be accepted                 |

The key must support the operations FloKit performs: validating the account,
reading Products and Prices, creating Checkout Sessions, provisioning the FloKit
webhook endpoint, reading subscription and tax status, and qualifying the
checkout payment domain when used.

## Connect and qualify Stripe

<Steps>
  <Step title="Open Stripe Direct in FloKit">
    In the FloKit dashboard, select the correct App and environment, then go to
    **Governance -> Integrations** and open **Stripe Direct**.
  </Step>

  <Step title="Enter the matching keys">
    Enter the Stripe secret key and publishable key for the same account and
    environment.

    Use the test pair for sandbox qualification and the live pair only for the
    approved production connection.
  </Step>

  <Step title="Validate the account">
    FloKit calls Stripe to confirm the account identity and whether the
    credential belongs to Test or Live mode.
  </Step>

  <Step title="Sync the Stripe catalog">
    FloKit imports the account's Products and Prices. Confirm that the expected
    recurring Price is active and has the correct amount, currency, and
    interval.
  </Step>

  <Step title="Map the first offer">
    FloKit creates or selects the App Package and binds it to the imported
    Stripe Product and Price. Trial days and promotion-code support are set on
    this binding.
  </Step>

  <Step title="Provision the webhook">
    Select **Provision webhook** in FloKit.

    FloKit creates or updates the connection-specific Stripe webhook endpoint
    and stores the signing secret returned by Stripe. The customer does not
    need to create a second webhook manually.
  </Step>

  <Step title="Qualify the connection">
    Run the Stripe qualification step. A connection must pass credential,
    catalog, webhook, and provider checks before it can serve checkout traffic.
  </Step>

  <Step title="Run a controlled test purchase">
    Publish the test Flow, complete one Stripe test checkout, and confirm that
    FloKit receives the provider event and records the expected transaction,
    subscription, and entitlement state.
  </Step>

  <Step title="Repeat for Live">
    After the test environment passes, connect the live keys, sync the live
    catalog, bind the live Price, provision the live webhook, and run the
    separately approved live canary.
  </Step>
</Steps>

## What the Stripe webhook does

The webhook is the authoritative return path from Stripe to FloKit. It is used
to update payment, subscription, cancellation, refund, and entitlement state.

A browser redirect after checkout is not treated as proof of payment. FloKit
waits for the verified Stripe event and the canonical checkout status.

## Custom domains and wallets

When a published Flow uses a custom hostname, complete Stripe payment-method
domain qualification for that exact hostname before launch. The FloKit fallback
domain can be used for the first technical test so DNS does not block the
connection.

## Ready for launch

Stripe Direct is ready when:

* the connection reports the correct account and environment;
* the expected recurring Price is present in the synced catalog;
* the FloKit Package is bound to that Price;
* the webhook is provisioned;
* qualification reports `ready`; and
* one controlled test checkout is reflected in FloKit from the Stripe event.

## Troubleshooting

### The account validates, but the Price is missing

Confirm that the Product and Price exist in the same Stripe environment as the
connected keys, that the Price is active, and that it is recurring. Then sync
the catalog again.

### A one-time Price never appears in FloKit

The catalog sync imports subscription options only, so a one-time Price is
skipped and never becomes bindable. The current Stripe Direct checkout is
subscription-only. Create an active recurring Stripe Billing Price and sync the
catalog again.

### Tax is not being calculated

Confirm that Stripe Tax is active in the connected Stripe account. FloKit omits
automatic tax when Stripe reports any other status.

### Webhook provisioning fails

Confirm that the Stripe key can list, create, and update webhook endpoints, then
run **Provision webhook** again.

### A custom-domain wallet is unavailable

Confirm that the exact Flow hostname has completed Stripe payment-method domain
qualification.