Payment Forms

Collect payment via Stripe Checkout when a form is submitted, using a restricted key from your own Stripe account. Fixed, per-field or line-item amounts.

View .md
On this page

Payment Forms route the submitter through Stripe Checkout before the submission is recorded. You provide a restricted API key from your own Stripe account. There is no Stripe Connect platform relationship, and StaticForm doesn’t custody funds or take a cut. The feature is available on the Pro plan.

Configuring payment collection on a form

How money moves

  1. You create a Stripe restricted API key in your Stripe Dashboard with a narrow set of scopes (listed below).
  2. You paste the key into StaticForm. StaticForm stores it encrypted.
  3. When someone submits a payment-enabled form, StaticForm uses your key to create a Stripe Checkout session on your account.
  4. Stripe redirects the submitter through Checkout. Cards / wallets / etc. are processed by Stripe, so StaticForm never sees them.
  5. On payment success, Stripe sends a webhook to a per-connection URL on StaticForm. StaticForm verifies the signature with the per-connection webhook secret you supplied, then records the submission.

You can revoke at any time by deleting the API key in your Stripe Dashboard. StaticForm immediately stops being able to act on your account.

Scenarios

  • Fixed amount per submission: Event tickets, paid signups, application fees.
  • Amount from a form field: Donations, “pay what you want”, tips.
  • Line items priced from form fields: Product or service orders. An enum field maps to a price table; an optional quantity field multiplies.

All three modes support conditional rules so the charge can depend on what the user fills in: “if plan = pro charge €49, else if plan = basic charge €19, else don’t require payment.”

Step 1: create a restricted API key

In your Stripe Dashboard:

  1. Developers → API keys → Restricted keys → Create restricted key.
  2. Set the scopes to:
    • Checkout Sessions: Write
    • Customers: Write (so Checkout can auto-create the customer record)
    • PaymentIntents: Read (optional, recommended: if Stripe’s webhook event for a failed delayed payment, such as a SEPA Direct Debit, is missed, StaticForm’s background check can still confirm the failure and clean up)
  3. Leave every other scope at None.
  4. Save and copy the secret (starts with rk_test_ or rk_live_).

StaticForm uses the key to create Checkout sessions and to read back the session (and, with the optional scope, the payment intent of a delayed payment) before it records or discards a submission. Payment success, failures, refunds and expiry arrive via webhooks, which don’t use the key.

Use a test mode key (rk_test_…) until you’re confident the flow works for your form, then switch to a live-mode key.

Step 2: add the connection to StaticForm

In StaticForm:

  1. Settings → Integrations → Stripe (Payment Forms) → Add Stripe connection.
  2. Give it a label (e.g. “Acme production”) and paste the restricted key.
  3. StaticForm verifies the key by creating and immediately expiring a throwaway Checkout session (it’s never payable), then saves the key encrypted. You may see this test session in your Stripe logs.

Step 3: register the webhook

After saving the connection, StaticForm shows the webhook URL for it. Copy it. Back in Stripe:

  1. Developers → Webhooks → Add endpoint.
  2. Endpoint URL: the copied URL (it has the form https://api.staticform.app/api/v1/payments/webhook/stripe/{connectionId}).
  3. Listen to these events:
    • checkout.session.completed
    • checkout.session.async_payment_succeeded
    • checkout.session.async_payment_failed
    • checkout.session.expired
    • charge.refunded, charge.dispute.created and charge.dispute.closed (optional: they keep the payment shown on a submission in step with refunds and disputes you handle in Stripe)
  4. Create the endpoint, then reveal the signing secret (whsec_…) and paste it back into StaticForm’s webhook setup screen.

Stripe creates the endpoint using your account’s default API version, which you can’t change in the Add endpoint dialog. You don’t need to. StaticForm accepts current Stripe API versions, so no version configuration is required on your side.

The connection now shows Ready in the integrations list and is selectable from any payment-enabled form’s connection picker.

Configure payment on a form

In the form editor, open the Payment tab.

  1. Toggle Collect payment on submission.
  2. Pick the connected Stripe account the charge should go to.
  3. Choose a currency.
  4. (Optional) Set a top-level condition to only require payment when the condition matches the submitted data. Useful for coupon fields, “free for students” toggles, member discounts.
  5. Pick a pricing mode and configure the rules.

Fixed amount

Add one or more rules. Each rule has an amount and an optional condition. The first rule whose condition matches wins. If no rule matches, or the matching rule’s amount is 0, the submission goes through as a free submission. Any other amount must be at least the minimum charge (see below).

Amount from a field

Add one or more rules. Each rule names a numeric form field and an optional minimum amount. First matching rule wins; the submitted value of the named field becomes the charge. A value below the rule’s minimum, or below the minimum charge, is refused with an error and nothing is saved. That includes 0: to let visitors submit without paying, use the top-level condition (for example, only require payment when the amount is greater than 0).

Line items

Add line items. Each item names an enum field and a price map mapping each enum option to its price. Optionally name a quantity field to multiply. All matching items accumulate into one Checkout session. A quantity of 0 leaves that item out; a negative quantity is refused.

If an order ends up with nothing to pay (the visitor picked no option with a price, or set every quantity to 0), the submission is refused. Turn on Accept orders with nothing to pay to save those submissions without payment instead. A total above 0 but below the minimum charge is always refused.

Invoices and tax

Three optional switches in the payment tab:

  • Create an invoice: Stripe issues a paid invoice for every payment. Stripe emails it to the buyer (with the receipt) when Successful payments is on under customer emails in your Stripe settings, and it is always in your Stripe Dashboard. Stripe prices these invoices separately from payments: see Stripe’s pricing for post-payment invoices.
  • Calculate tax automatically: Stripe Tax works out the VAT or sales tax from the buyer’s address, which Checkout then asks for. Your prices include tax: the buyer pays exactly the price you set, and the tax is shown inside it on Checkout and on the invoice. Turn on Stripe Tax in your Stripe Dashboard first (origin address and tax registrations). Stripe charges a fee per transaction for Stripe Tax.
  • Collect tax IDs: business buyers can enter a VAT number or other tax ID. It’s printed on the invoice, and with automatic tax Stripe applies the reverse charge where it’s due.

If Stripe refuses to start Checkout after you turn one of these on, check the restricted key’s request log in Stripe: it names any scope the key is missing.

Submission flow

  1. User submits the form.
  2. StaticForm validates fields and files, stages everything, and creates a Stripe Checkout session on your account using your restricted key.
  3. The user is redirected to Stripe Checkout to pay.
  4. On payment success, the submission is recorded and your submit actions (email, webhook, Sheets, Notion) fire as normal.
  5. On payment abandonment or expiry, the staged submission and any uploaded files are cleaned up automatically. No submission is recorded.
  6. With a delayed payment method (such as SEPA Direct Debit), Checkout completes before the money arrives. The submission is recorded once Stripe reports the payment as succeeded, which can take several days. If the payment fails, the staged submission and its files are cleaned up and the storage they held is freed.

Because the submitter has to leave your page for Stripe Checkout and come back, a payment-enabled form always responds with an HTTP redirect rather than a JSON response, for both success and error outcomes. The JSON Response option is disabled once payment is on, and both redirects are required (the form won’t save without them). Set the success and error destinations on the form’s Behaviour tab. They default to StaticForm’s built-in result page, and you can point either at your own URL instead. On the built-in page, Go back returns the buyer to the page your form is on, through a signed link that stays valid for 2 hours. That only works when the page is on one of the form’s allowed domains, so turn them on for a payment form; otherwise Go back returns to the previous page in the browser. Your own URL receives status (success or cancelled) and pending_submission_id in its query string.

If your form has an email field (a field with the email validation rule), its submitted value prefills the email on Stripe Checkout, so the buyer doesn’t retype it. Stripe leaves the field editable. Whenever the form has one or more email fields, the payment panel shows a picker so you can choose which one feeds Checkout (it defaults to the first). When the form has no email field, Checkout asks for the email as usual.

Every charge is at least the minimum charge of 50 in the currency’s smallest unit (€0.50, $0.50, ¥50). A resolved amount below it is refused with an error rather than accepted for free, so a visitor cannot get a paid form for free by entering a tiny amount. For coupon or “free for students” flows, use the top-level condition or a fixed rule of 0.

Refunds are handled entirely in your own Stripe Dashboard. The submission already recorded in StaticForm stays as-is.

Security notes

  • Your restricted API key is stored encrypted at rest with the StaticForm data-protection key.
  • StaticForm never sees card numbers; those are entered into Stripe Checkout directly.
  • Webhook events are signed by Stripe and verified by StaticForm against the per-connection signing secret you provided.
  • You can revoke the key any time from your Stripe Dashboard. Doing so instantly invalidates StaticForm’s access. There is no separate “uninstall” step required on Stripe’s side.

Limits and caveats

  • One currency per form.
  • Recurring subscriptions, sending unpaid invoices and partial payments are not supported in this release. Prices with automatic tax are always tax-inclusive.
  • Connected before delayed-payment failures were handled? Add checkout.session.async_payment_failed to your webhook endpoint’s events (you can edit the endpoint in place in Stripe). Until then, a staged submission whose delayed payment failed keeps its uploaded files and counts towards your storage. Adding PaymentIntents: Read to your restricted key is optional: it lets the background check clean up when the webhook event is missed.
  • File uploads on payment-enabled forms are supported: files are staged before Checkout and finalised on payment success.