# Stripe

Canonical: https://useformwork.com/docs/extensions/stripe

Configure Stripe Checkout payments, verification, webhooks, and workflow actions.

The built-in Stripe extension lets a form redirect respondents to Stripe-hosted Checkout and store the resulting PaymentIntent ID. It also exposes Stripe actions for workflows and verifies payments before submission.

## What it adds

- A **Payment** field (`stripe:payment`)
- Client actions to create and retrieve a Checkout Session
- Submission validation against Stripe's PaymentIntent API
- Verified Stripe webhooks that update the payment answer
- Workflow actions for Checkout Sessions and PaymentIntents

## Install and configure

1. Open the project, select **Extensions**, and open **Stripe**.
2. Select **Install extension**.
3. Create an environment, such as **Stripe Test**.
4. Add the required **Stripe Secret Key** (`sk_…`).
5. Optionally add the **Webhook Signing Secret** (`whsec_…`).
6. Save and enable the environment; make it default if appropriate.

FormWork manages Stripe's connection settings for you. You only need to add the credentials for each test or live environment.

Use Stripe test keys and test-mode webhooks in a test environment; keep live credentials in a separate live environment.

## Add a Payment field

After installing Stripe, add **Payment** from the field chooser. Configure:

### Money and line items

- **Currency:** USD, EUR, GBP, AUD, or CAD; default USD.
- **Amount Unit:** Minor (for example cents/pence) or Major decimal values.
- **Line Item Source:** Manual, Reference, or Repeater.
- **Manual:** one or more items, each with a name and amount (fixed or reference value).
- **Reference:** source collection reference, item-name reference, and item-price reference.
- **Repeater:** repeatable Group field plus name and price subfield IDs.

The extension normalises and validates each amount. When the calculated line items are unavailable or invalid, the payment control reports that payment is not yet available.

### Checkout behaviour

- **Capture Method:** Automatic or Manual.
- **Payment Description:** optional PaymentIntent description.
- **Customer Email Field:** optional Email field used to prefill Checkout.
- **Billing Address Collection:** Auto or Required.
- **Collect Phone Number:** on/off.
- **Allow Promotion Codes:** on/off.
- **Pay Button Label:** default **Pay now**.
- **Repay Button Label:** default **Pay again**.
- **Paid State Label:** default **Payment complete**.

## Respondent flow

1. The field ensures an entry exists and calculates its line items.
2. **Pay now** creates a Stripe Checkout Session linked to this payment field.
3. The respondent completes Checkout on Stripe.
4. The client retrieves the session and saves its `pi_…` PaymentIntent ID as the field answer.
5. On form submit, FormWork verifies that the PaymentIntent belongs to this payment field.

A non-empty payment answer must match a PaymentIntent-style `pi_…` reference. Submission fails when payment is required but missing, the environment is not configured, Stripe cannot verify it, or the intent does not belong to this entry/field.

For manual capture, authorisation and capture are separate; use the capture workflow action at the appropriate business point.

## Webhooks

Configure this Stripe endpoint:

```text
https://app.useformwork.com/api/v1/extensions/stripe/webhooks
```

Subscribe as needed to:

- `checkout.session.completed` — writes the session's PaymentIntent to the matching entry field.
- `payment_intent.succeeded` — writes the succeeded intent ID to the matching entry field.
- `payment_intent.payment_failed` — verified and matched, with no answer mutation.

FormWork verifies each webhook with the environment's webhook signing secret and applies it to the matching payment field. Do not omit the signing secret for live webhook processing.

## Workflow actions

Stripe contributes these step choices:

- **Create Checkout Session**
- **Retrieve Checkout Session**
- **Create Payment Intent**
- **Retrieve Payment Intent**
- **Capture Payment**

The first two also back the Payment field's entry-key-authorised client actions. Workflow actions use the selected/default environment and expose mapped Stripe response data for downstream steps.

Checkout response fields include session ID, URL, status, payment status, PaymentIntent ID, amount total, and currency.

## Launch checklist

- Use a test environment and Stripe test card first.
- Verify minor/major units and currency with low and decimal values.
- Test manual, reference, or repeater line items after their source answers change.
- Test cancel, retry, promotion-code, and required billing-address paths.
- Confirm the webhook signature succeeds and updates the intended field.
- For manual capture, test the workflow's capture timing and failure path.
- Switch the form/workflows to the live enabled environment only after end-to-end testing.

Stripe billing for your FormWork subscription is separate from this project extension. Account subscription management is covered in [Plans & Billing](/docs/platform/billing).