FormWork FormWork

FormWork documentation

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:

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.