> This page is for version v2 (default).
> For other versions, use one of these documentation indexes:
> - v2 (default): https://docs.paid.ai/v-2/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.paid.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.paid.ai/_mcp/server.

# Stripe

> Connect Stripe to Paid to put payment links on invoices, charge cards on file, and run hosted checkout.

Connect your Stripe account and Paid collects payment for the invoices it issues: a payment link on every invoice the customer cannot be charged for automatically, cards on file charged when an invoice is issued, and hosted checkout for self-serve sign-up. This page explains which of Paid's two Stripe connections does what, which permissions Paid asks for, and how an order turns into an invoice your customer can pay.

## Prerequisites

* A Stripe account. A live Paid organization needs a live Stripe account, and a test-mode Paid organization needs a Stripe sandbox.
* An admin user on Paid. Only an organization admin can connect or disconnect Stripe.
* Permission to authorize third-party apps on the Stripe account.

## The two Stripe connections

Paid has two separate Stripe connections. They do different jobs, and only one of them lets Paid take payments.

| Where in Paid                                    | What it is                                                       | What it does                                                                                                                                                                              |
| ------------------------------------------------ | ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Settings → Billing → Connect Stripe**          | Stripe Connect (OAuth). You log in to Stripe and authorize Paid. | Powers everything payment-related: payment links on invoices, charging cards on file, hosted checkout, bank transfers, and optional invoice sync to Stripe. **This is the one you need.** |
| **Settings → Integrations → Stripe integration** | A Stripe API key you paste in.                                   | One-way import of existing Stripe customers (matched by email) and already succeeded payments into Paid. Useful for migrating history. It cannot create payment links.                    |

To get payment links on invoices, use the first. The second is optional and covered in [Import your Stripe history](#import-your-stripe-history).

## Permissions Paid asks for

**Settings → Billing → Connect Stripe** sends you to Stripe's standard Connect authorization page. Paid asks for Stripe's `read_write` scope on your account. Paid uses it to:

* Create Stripe customers for your Paid customers, so a card they save sits on their Stripe customer record.
* Create Stripe Payment Links for the amount due on an invoice.
* Charge a saved payment method when an invoice is issued, and confirm card payments made on the invoice's pay page, including 3D Secure.
* Create invoices in your Stripe account when Paid finalizes one. This is off by default.
* Issue virtual bank account numbers for customers who pay by ACH or wire. This needs [bank transfers](/documentation/billing/bank-transfers) enabled in Stripe.

Paid stores the connected account ID, not a secret key. You never type a key into Paid for this connection. You can revoke it at any time with **Disconnect** in Paid, or from your Stripe Dashboard under **Settings → Connected applications**.

## How a payment link reaches your customer

Paid attaches payment links to invoices, not to orders. From "order created" to "customer has a link to pay":

1. You create and activate an order, in the app, by API, or through a checkout.
2. Paid creates the order's invoices: any upfront fees when the order activates, then recurring and usage charges at each billing cycle. An invoice starts as a draft unless the order or organization finalizes invoices automatically (see [Decide how invoices go out](#decide-how-invoices-go-out)). A draft has no payment link yet.
3. When an invoice is finalized, Paid checks whether the customer has a chargeable payment method on file in your connected Stripe account.
   * **Card on file:** Paid charges it automatically. If the charge is declined, Paid adds a payment link so the customer can still pay.
   * **No card on file:** Paid creates a Stripe Payment Link for the amount due and stores it on the invoice.
4. The invoice PDF and email carry a **Pay online** button (you can rename it) that opens the Stripe-hosted payment page. The email goes out when the invoice is finalized if the order or organization sends billing emails automatically; otherwise you send it from the invoice page. When the customer pays, the invoice is marked paid in Paid, and your own systems can hear about it through [webhooks](/documentation/billing/webhooks).

So the connection alone is not the whole workflow. Three settings decide what happens after an order is created, and two of them are off by default:

| Setting                         | Default | Set where                                                                       |
| ------------------------------- | ------- | ------------------------------------------------------------------------------- |
| Add payment links to invoices   | On      | Settings → Billing → Stripe settings, and per order under **Payments**          |
| Finalize invoices automatically | Off     | Settings → Billing, and per order under **Invoices** → **Invoice generation**   |
| Auto-send billing emails        | Off     | Settings → Billing, and per order under **Invoices** → **Sharing the invoices** |

Turn the last two on, or finalize and send each invoice by hand, and the workflow is: create and activate the order, the first invoice is finalized with a payment link and emailed to the billing contacts.

> **Note**
>
> If you need the customer to pay before the order exists (sign-up or
> self-serve), use [Checkout](/documentation/customers-users/checkout) instead. Paid gives you a
> hosted checkout link or an API call, the customer pays by card, and Paid
> creates the order on success.

## 1. Connect your Stripe account

1. In Paid, go to **Settings → Billing**.
2. Click **Connect Stripe**. You are sent to Stripe.
3. Log in, pick the Stripe account to connect, and click **Authorize**.
4. You land back in Paid, and the Billing page shows the connected account name and date.

Paid refuses a live Stripe account on a test-mode organization and a sandbox on a live organization. To switch accounts, disconnect first, then connect again.

## 2. Review the Stripe settings

Once connected, a **Stripe settings** card appears on the same page.

| Setting                           | Default      | What it does                                                                                                                                            |
| --------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Auto-create Stripe customers      | On           | Creates a Stripe customer whenever you create a Paid customer. Leave on.                                                                                |
| Add payment links to invoices     | On           | Adds a Stripe Payment Link to invoices the customer cannot be auto-charged for.                                                                         |
| Payment link display name         | "Pay online" | The button text on the invoice.                                                                                                                         |
| Payment methods for payment links | Card         | Which methods the Stripe page offers: card, US bank account (ACH), SEPA direct debit, PayPal, Klarna. Each must also be enabled in your Stripe account. |
| Sync invoices to Stripe           | Off          | Also creates the invoice in Stripe when Paid finalizes it. Only needed if your finance team works from Stripe's invoice list.                           |

Click **Save**.

## 3. Decide how invoices go out

Two organization-wide switches further up the **Settings → Billing** page decide whether an invoice needs a person to touch it. Both are off by default:

* **Finalize invoices automatically**: finalize each invoice Paid generates from an order as soon as it is created. When off, invoices stay as drafts until you review and finalize them, and a draft has no payment link.
* **Auto-send billing emails**: email finalized invoices to the billing contacts. When off, you send each invoice from its page.

Each order can override both, in the order wizard under **Invoices** and editable later: **Invoice generation** (Create as draft, or Finalize automatically) and **Sharing the invoices** (Send manually, or Send automatically).

## 4. Check the order's payment settings

Each order also has its own payment options, under **Payments** in the order wizard:

* **Include Stripe payment link**: on by default once Stripe is connected.
* **Include payment instructions**: adds your bank details to the invoice if you have entered them.
* **Send automatic confirmations**: emails the billing contacts each time a payment is received. This is the payment receipt, not the invoice; invoice emails are the **Sharing the invoices** choice above.

## 5. Test it

The safest rehearsal is a test-mode Paid organization connected to a Stripe sandbox:

1. Connect the sandbox under **Settings → Billing** of the test organization.
2. Create a customer with an email you can read, then create an order with an upfront fee. In the order's **Invoices** settings, pick **Finalize automatically** and **Send automatically**, then activate the order.
3. Open the invoice Paid generated. It is finalized, shows the **Pay online** link, and the email has arrived at the customer's address. If you left the invoice as a draft, finalize it from the invoice page and send it; the link is added when it is finalized.
4. Pay it with a Stripe test card (`4242 4242 4242 4242`). The invoice flips to paid.

If a link is missing, the usual causes are: the invoice is still a draft, the customer already has a card on file (so Paid charged it instead), payment links are turned off for the organization or the order, or the amount is below the card minimum for the currency.

## Import your Stripe history

If you already have customers or payments in Stripe that you want in Paid, use **Settings → Integrations → Stripe integration**, when it is shown for your organization. Paste a Stripe restricted key with read access to Customers and Payment Intents (an `rk_live_` key is enough; a secret key also works), tick what to sync, and click **Connect**. The key must match the organization's mode: `rk_live_` or `sk_live_` for a live organization, `rk_test_` or `sk_test_` for test. The import runs right after connecting.

Skip this step for a brand-new Stripe account.

## Related

* [Checkout](/documentation/customers-users/checkout)
* [Bank transfers](/documentation/billing/bank-transfers)
* [Webhooks](/documentation/billing/webhooks)