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

# Stripe Integration

Connect your Stripe account to Paygent to collect invoice payments through Stripe Checkout. Paygent generates secure payment links, sends them in invoice emails when configured, and automatically marks invoices as paid when Stripe confirms payment.

> **Info**
>
> **What Paygent handles for you:**
>
> * Creates Stripe Checkout Sessions for unpaid invoices
> * Maps Paygent customers to Stripe customers on first payment
> * Verifies webhook signatures and records payments when checkout completes
> * Stores API keys encrypted — only masked values are shown in the dashboard

## Prerequisites

* A Stripe account with API access (test or live mode)
* At least one customer with an email address (required for automated invoice emails)
* An unpaid invoice with a total amount greater than zero

## Setup overview

| Step | Action                        | Description                                                                                           |
| ---- | ----------------------------- | ----------------------------------------------------------------------------------------------------- |
| 1    | **Connect Stripe in Paygent** | Add your Stripe secret key and webhook signing secret under Settings → Integrations.                  |
| 2    | **Configure Stripe webhook**  | Register Paygent's webhook URL in the Stripe Dashboard and subscribe to `checkout.session.completed`. |
| 3    | **Collect payments**          | Generate a payment link from an invoice, or enable automatic Stripe links in order invoice emails.    |
| 4    | **Payment confirmed**         | Stripe notifies Paygent via webhook; the invoice is marked paid automatically.                        |

---

## Step 1 — Connect Stripe in Paygent

1. Open **Settings → Integrations** in the Paygent dashboard.
2. Toggle **Stripe** on (or click **Edit** if already connected).
3. Enter a connection name (for example, `Production Stripe`).
4. Paste your **Stripe Secret Key** — starts with `sk_test_` or `sk_live_`.
5. Paste your **Webhook Signing Secret** — starts with `whsec_` (you will get this in Step 2).
6. Click **Save Connection**.

> **Tip**
>
> **Where to find your Stripe secret key:** In the [Stripe Dashboard → Developers → API keys](https://dashboard.stripe.com/apikeys), copy the **Secret key**. Use test keys while setting up; switch to live keys when you go to production.

---

## Step 2 — Configure the Stripe webhook

Paygent needs Stripe to send a webhook when a customer completes checkout. The webhook URL is unique to your organization and shown in the Connect Stripe dialog after you save your connection.

**`Webhook URL format`**

```text title="Webhook URL format"
https://api.withpaygent.com/api/webhooks/stripe/{your-organization-id}
```

### In the Stripe Dashboard

1. Go to [Developers → Webhooks](https://dashboard.stripe.com/webhooks) and click **Add endpoint**.
2. Paste your Paygent webhook URL (copy it from Settings → Integrations or the connection modal).
3. Under **Events to send**, select:
   * `checkout.session.completed`
4. Save the endpoint, then open it and reveal the **Signing secret** (`whsec_...`).
5. Return to Paygent → Settings → Integrations → Edit Stripe and paste the signing secret if you did not have it during initial setup.

> **Warning**
>
> **Test vs live mode.** Webhook endpoints, secret keys, and signing secrets are separate for Stripe test mode and live mode. When you switch from test to live, create a new webhook endpoint in live mode and update both keys in Paygent.

---

## Step 3 — Collect payments on invoices

Once Stripe is connected, you can collect payment in two ways.

### Option A — Generate a payment link manually

1. Open an unpaid invoice from the Invoices list.
2. Click **Generate payment link**.
3. Copy the Stripe Checkout URL and send it to your customer.
4. After payment, the customer is redirected to a Paygent confirmation page; the invoice status updates automatically via webhook.

### Option B — Include a Stripe link in invoice emails

1. Configure email delivery under **Settings → Email** (SMTP or provider credentials).
2. When creating or editing an order, set **Invoice email** to **Send invoice with Stripe payment link**.
3. When an invoice is generated and emailed, Paygent automatically creates a Checkout Session and embeds the payment link in the email body.

> **Info**
>
> **Email requirements:**
>
> * **Send invoice only** — sends the PDF without a payment link
> * **Send invoice with Stripe payment link** — requires Stripe connected *and* email configured
> * The customer record must have a valid email address

---

## How payment flow works

```
Customer                    Paygent                         Stripe
   |                            |                               |
   |<---- Invoice email/link ---|                               |
   |                            |--- Create Checkout Session -->|
   |<--------------------------- Stripe Checkout URL -----------|
   |--- Pays on Stripe ---------------------------------------->|
   |                            |<-- checkout.session.completed |
   |                            |--- Mark invoice paid          |
   |<--- Success page ----------|                               |
```

Checkout success and cancel URLs point to public Paygent pages (`/pay/success` and `/pay/cancel`). Customers do not need a Paygent login to pay.

---

## Local development with Stripe CLI

For local testing, forward Stripe events to your machine and use the CLI signing secret in Paygent.

**`Forward webhooks locally`**

```bash title="Forward webhooks locally"
# Install Stripe CLI: https://stripe.com/docs/stripe-cli
stripe login

# Forward checkout events to your local Paygent API
stripe listen --forward-to http://localhost:8080/api/webhooks/stripe/{your-organization-id}

# The CLI prints a whsec_... signing secret — use that in Paygent while testing locally
```

> **Tip**
>
> **Trigger a test payment:** Use Stripe test card `4242 4242 4242 4242` with any future expiry and CVC on the Checkout page. See [Stripe testing docs](https://stripe.com/docs/testing) for more test cards.

---

## Manual payment recording

If a customer pays outside Stripe Checkout (wire transfer, check, etc.), open the invoice and use **Record payment** to mark it paid manually. This does not go through Stripe.

---

## Security

Stripe secret keys and webhook secrets are encrypted at rest. The dashboard only displays masked values (last four characters).

The webhook endpoint is public but secured with Stripe signature verification — requests without a valid `Stripe-Signature` header are rejected.

---

## Troubleshooting

**"Generate payment link" button is missing**
Stripe must be connected under Settings → Integrations, and the invoice must be unpaid.

**Invoice email skipped with "stripe\_not\_connected"**
Connect Stripe before using "Send invoice with Stripe payment link" on orders.

**Customer paid but invoice still shows unpaid**
Confirm the webhook endpoint URL matches your organization ID, the signing secret in Paygent matches the endpoint in Stripe, and `checkout.session.completed` is subscribed. Check webhook delivery logs in the Stripe Dashboard for failed attempts.

**"Invalid Stripe signature" in logs**
The webhook signing secret in Paygent does not match the endpoint in Stripe. Re-copy the secret from Stripe → Webhooks → your endpoint → Signing secret.

> **Success**
>
> **You're ready!** After connecting Stripe and configuring the webhook, generate a test payment link from any unpaid invoice and complete a test checkout. The invoice should move to **paid** within a few seconds.