---
title: "Taking Payments"
description: "How to collect a payment or start a subscription as part of a workflow using Stripe, and how to rehearse it without moving real money."
slug: "taking-payments"
audience: "all"
generated_at: "2026-10-16T19:47:02.300Z"
screenshots:
  - "/docs/screenshots/taking-payments/connections.png"
---

## What a Stripe payment step does

A payment step in FormAssembly is a **Connect** step that uses your Stripe connection to collect money as part of a workflow run. When a respondent reaches the payment step, FormAssembly builds a Stripe Checkout page from the line items you configured, sends the respondent to Stripe to pay, and then brings them back into the workflow with the payment result attached to the run.

Payments always use **Stripe-hosted Checkout**. Card numbers, wallets, and any bank verification steps are handled entirely on Stripe's page, which means card data never passes through FormAssembly and you don't have to build or secure a payment form yourself.

A payment step can charge:

- **One-off amounts** — either a fixed price from your Stripe catalog or a custom amount calculated from the respondent's answers.
- **Subscriptions** — recurring prices from your Stripe catalog.
- **A combination of line items** — several charges assembled into a single checkout.

## What a PayPal payment step does

A PayPal payment step is the other payment connector in FormAssembly, and it works the same way as the Stripe step: the respondent is sent to a **PayPal-hosted approval page**, pays there, and is returned to the workflow with the result attached to the run. Card and wallet data never pass through FormAssembly.

A PayPal payment step runs in one of two modes, and a single step can only be one or the other:

- **A one-time order** made up of one or more line items that you describe directly (name, amount, quantity). PayPal has no one-time price catalog, so every one-time item is defined in the step itself.
- **A subscription** against exactly one active billing plan from your PayPal catalog. Create the plan in your PayPal dashboard first; FormAssembly cannot create products or plans for you.

A PayPal step cannot mix one-time items and a subscription. If you ask Fai for both in one step, the step will not run — use two steps instead.

## Is Stripe included in my plan?

Payment connectors are sold as an account add-on in FormAssembly, covering Stripe and PayPal together. Your account can use a Stripe or PayPal payment step when your plan includes the payments add-on or you have purchased it separately. If your account does not have it, saving a workflow that contains a payment step is refused with a message explaining that the connector "isn't included in your account's plan. It's available as an add-on. Talk to sales to have it enabled for your account." Every save of the workflow is refused until the payment step is removed.

## Before you start: connect Stripe

A payment step needs a Stripe connection, authorized from the **Connections** page; see the **Connecting Services** article for how to connect, reconnect, and disconnect. The connection grants FormAssembly read and write access to your Stripe account so it can read your catalog prices and create checkouts on your behalf.

![The Connections page showing the Stripe connection](/docs/screenshots/taking-payments/connections.png)

Nothing else needs to be enabled in Stripe up front — however, if you plan to charge fixed prices or subscriptions, create those products and prices in your Stripe catalog first so they are available to select. If you want to rehearse payments without moving real money, also authorize a Stripe sandbox (test-mode) connection on the same page. See [Testing payments safely](#how-do-i-test-a-payment-without-charging-a-real-card) below.

## Before you start: connect PayPal

A PayPal payment step needs a PayPal connection, authorized from the **Connections** page by completing PayPal's seller sign-up; see the **Connecting Services** article for the details. FormAssembly acts as a PayPal partner: funds settle in your own PayPal account, and FormAssembly takes the payment on your behalf.

Two things must be true on the PayPal side before the connection can be stored: your account must be able to receive payments, and your primary email address must be confirmed. Billing plans for subscriptions are authored in your PayPal dashboard. A sandbox PayPal connection is available on the same page for testing, as it is for Stripe.

## How do I add a payment step to a workflow?

Payment steps are configured through **Fai**, the AI assistant built into the FormAssembly builder. Fai authors the connector configuration for you, so you describe what you want to charge rather than filling in a technical form. The **Add step** menu has no payment item — ask Fai to add a Stripe or PayPal step. The payment step itself shows a read-only summary on the canvas, ending "Connector configuration is managed by the AI agent" — to change what is charged, ask Fai.

1. Open the workflow you want to take payments in.
2. Make sure you have a **Collect** step that gathers whatever the payment depends on — for example the respondent's email, a quantity, a donation amount, or a plan choice.
3. Click **Open Fai** to open the chat panel. You can ask Fai to add a step from either **Overview** or **Focus** view.
4. Describe the payment in plain language. For example: *"After the form, add a Stripe payment step that charges the Standard Ticket price times the Number of tickets field, and prefill the email from the Email field."*
5. Fai adds the payment step to the workflow and configures the checkout. Review the step, then switch to **Focus** view and click **Add step** there to add anything that should happen after payment (a confirmation, a Salesforce record, an email). **Add step** and the other structural controls are available in Focus view only; **Overview** is a read-only map of the workflow, and clicking a step card there switches you to Focus.
6. Click **Test** to run the workflow end to end, then **Publish** when the workflow is ready.

You can keep refining the step by asking Fai for changes — "add a $5 processing fee line item", "allow promotion codes", "change the button to say Donate".

## Configuring the checkout

The payment step has one checkout configuration plus one entry per line item. Ask Fai for each of the settings below.

### Checkout configuration

- **Currency** is required only when the step has a custom-amount line item, and it applies to those items. Use the standard three-letter code, such as `USD`, `EUR`, or `JPY`. A checkout made only of catalog prices takes its currency from those prices.
- **Customer email** is optional. Map it to an email field from a Collect step so Stripe's email box is prefilled and the respondent doesn't retype it.
- **Submit button label** is optional and applies to one-off payments only. Stripe supports **Pay**, **Donate**, and **Book**.
- **Allow promotion codes** is optional. Turn it on to show a promo code box on the Stripe Checkout page.

### Line items

Each line item is either a catalog item or a custom amount.

- **Catalog line items** reference an existing active price in your Stripe catalog. FormAssembly lists your active prices so you can pick one by product name and amount, or you can map the price to a field — for example a picklist of plans whose values are Stripe prices, so the respondent chooses what they're paying for.
- **Custom-amount line items** don't need anything in your Stripe catalog. You supply a product name, an optional description, and an amount that can be a fixed value, a mapped field, or a calculation over fields (for example quantity × unit price, or a percentage-based fee).
- **Quantity** defaults to 1 and can be mapped to a field such as "Number of tickets".
- **Subscriptions must use a catalog price.** Recurring pricing has to come from Stripe; you cannot build a custom recurring amount from a form field.
- If any line item is a subscription, the whole checkout becomes a subscription checkout. Otherwise it is a one-off payment.
- A line item attached to a repeated section produces one line item per submitted instance of that section — useful for "add another attendee" style forms.

Amounts must be positive and can't be finer than the currency allows (no fractional yen, no third decimal on dollars). An invalid amount stops the step before FormAssembly ever contacts Stripe.

To pull answers into line items, tell Fai which field each value comes from — for example "take the amount from the Donation amount field". Fai writes the configuration; the payment step itself is read-only.

## Configuring a PayPal checkout

A PayPal payment step has the same shape: one checkout configuration plus the items being charged.

### PayPal checkout configuration

- **Currency** is required for a one-time order. A subscription takes its currency from the PayPal billing plan.
- **Brand name** is optional and replaces your business name on PayPal's approval page.
- **Customer email** is optional and prefills the payer's email address.
- **Description** is optional, applies to one-time orders only, and appears on the order.

### PayPal line items

- **One-time items** are defined in the step: a name, an optional description, a unit amount in major units (dollars, not cents), an optional quantity (defaults to 1), and an optional category of digital goods, physical goods, or donation. Amounts can be fixed, mapped from a field, or calculated.
- **A subscription item** references an active billing plan from your PayPal catalog. FormAssembly lists your active plans so you can pick one by name and price, or map the plan to a field so the respondent chooses. Quantity is honoured only for plans that support it; PayPal rejects it otherwise.
- **One mode per step.** A step holds either one-time items or exactly one subscription plan. Mixed or empty steps stop before PayPal is contacted.
- A one-time item attached to a repeated section produces one item per submitted instance.
- Amounts must be positive and respect the currency's precision — whole numbers for PayPal's non-fractional currencies such as JPY and HUF, two decimals otherwise.

## What the respondent sees

1. The respondent fills in your **Collect** step and submits it.
2. FormAssembly assembles the line items and sends the respondent to Stripe's hosted Checkout page, showing each line item, its quantity, and the total. A PayPal step sends the respondent to PayPal's approval page instead, where they approve the order or subscription.
3. The respondent pays on Stripe or PayPal. Any card authentication or wallet flow happens there.
4. Stripe or PayPal returns the respondent to the workflow, which picks up where it left off and continues to the next step — a confirmation message, a record creation, an email, or anything else you've added.

FormAssembly confirms the payment with Stripe or PayPal itself before advancing the run, so a respondent can't skip a payment by editing the return address in their browser.

## What happens if a respondent cancels or the payment fails?

If the respondent clicks back out of Stripe Checkout or PayPal's approval page without paying, the payment step follows its **failure** path. You author what happens next — most workflows send the respondent back to the **Collect** step so they can try again. Resubmitting creates a brand-new checkout; the abandoned one simply expires.

A genuine cancel is treated as a normal outcome: the respondent sees no error banner, and the workflow owner is not sent a failure notification. Real errors — an expired checkout, a declined or voided PayPal capture, or a problem reaching the payment provider — do show an error banner and are reported as failures.

If the payment is confirmed as successful, the workflow advances down the **success** path even if the respondent arrived back through the cancel link. The confirmed payment always wins over what the return link claims.

If you move a run backwards past the payment step (a replay), FormAssembly expires the unpaid Stripe checkout that run was parked on, so the respondent cannot pay for a step the run has already left. A checkout that was already paid or already expired is left as it is.

PayPal orders expire if they are not approved within PayPal's own window of about three hours. A respondent who leaves the approval page open past that point and then returns gets a failure with an error, and should resubmit.

## What payment details can later steps use?

After a successful payment, the payment provider returns the payment result to the payment step. A payment detail becomes usable elsewhere only once you **map it to a workflow variable** on the payment step — ask Fai to write the details you need into variables. Once mapped, later steps reference the value by the payment step's name (for example `{{ step_2.checkout_amount_paid }}`) in confirmation messages, field mappings, conditions, and emails.

For Stripe, the details available to map are:

- **Checkout and payment status** — the checkout session ID and the payment status.
- **Amount and currency** — the amount paid as a plain decimal, and the currency code.
- **Customer** — the Stripe customer ID and the email address the respondent entered at checkout.
- **Payment intent** — its ID, status, and a link straight to it in your Stripe dashboard.
- **Subscription** — for subscription checkouts, the subscription ID and a dashboard link.
- **Per line item** — the price ID, product ID, dashboard links, and whether the line item was a custom amount.

For PayPal, the details available to map are:

- **Payment status** — the status of the payment, plus a reason when it is pending.
- **Amount and currency** — the amount paid or due, and the currency code. For one-time orders, the PayPal fee and the net amount are also available when PayPal reports them.
- **Payer** — the payer's PayPal ID, email address, and name.
- **Order** — for one-time orders, the order ID, the capture ID, and a link to the payment in PayPal.
- **Subscription** — for subscriptions, the subscription ID and status, the plan ID, the start time, the next billing time, and a link to the subscription in PayPal.

A PayPal payment can complete as **pending** — an eCheck or a PayPal review that clears over days, which FormAssembly treats as a success because the payer has done their part. If fulfilment must wait for cleared funds, map the payment status into a variable and branch on it.

A common pattern is to include the amount paid and the customer email in the **Confirmation message** on the following Respond step, and to write the payment intent or capture ID into a Salesforce or Google Sheets record so finance can reconcile.

## How do I test a payment without charging a real card?

Ask Fai to set a **sandbox connection** on the payment step; the payment step has no connection picker of its own. A sandbox connection is a separate connection to the provider's test environment — Stripe test mode, or a PayPal sandbox merchant — authorized with **Connect sandbox account** on that provider's connection settings page, reached from the **Connections** page. When a payment step has both a live and a sandbox connection:

- Runs started from **Test** in the builder use the sandbox connection. The checkout is created in the provider's test environment and the respondent pays with a test card (for Stripe, `4242 4242 4242 4242` succeeds and `4000 0000 0000 0002` declines). No real money moves.
- Live, published runs always use the live connection. FormAssembly never runs a real submission against a sandbox connection.

If a payment step has **no** sandbox connection set, test runs use the live connection like any other step — meaning **a test run creates a real checkout and can take a real payment**. A test-mode banner tells you the run is a test in both cases, so read it before entering a card.

Once a sandbox connection is set on the step, FormAssembly never quietly falls back to the live connection: if that sandbox connection has been disconnected or is no longer valid, the test run fails at the payment step with an error rather than charging a real card.

You can build and test with a sandbox connection only, but publishing a workflow requires the live connection to be set.

### Which line items test cleanly in the sandbox?

- **Custom-amount line items** test cleanly — they don't depend on anything existing in your Stripe catalog. PayPal one-time orders are the same: every item is defined in the step, so nothing has to exist in a catalog.
- **Respondent-chosen catalog prices** (a picklist backed by your Stripe catalog with its own sandbox connection) also test cleanly, because the picklist lists your test-mode catalog inside a test-mode run. A respondent-chosen PayPal plan behaves the same way.
- **A fixed catalog price picked in the builder will fail in a sandbox test run.** Stripe generates price IDs per environment and they can never match across live and test mode — even copying a price to live mode creates a new ID. Test those steps with a custom-amount line item, or accept that the fixed-price path is exercised only against the live connection. A fixed PayPal billing plan has the same limitation: a live plan ID does not exist in the sandbox.

The builder's price and plan pickers always list items from your **live** catalog, because step configuration targets production. If you have authorized only a sandbox connection, the pickers have no live catalog to list — build and test with custom-amount line items or field-mapped prices until you connect your live account.

## Limitations

- **Hosted checkout only.** Payments use Stripe's hosted Checkout page or PayPal's hosted approval page. Embedded card fields, saved payment methods, invoicing, and tax configuration are not available.
- **No refunds or captures from FormAssembly.** Issue refunds and capture authorized payments in the Stripe or PayPal dashboard.
- **Lookups are limited to catalog pricing.** FormAssembly reads your active Stripe prices and your active PayPal billing plans, which is what backs the builder's pickers and respondent-facing picklists. There is no prefill from existing Stripe or PayPal customers, and no customer or payment-method lookups.
- **No platform fees or shipping on PayPal.** Platform fees, authorizations without capture, vaulting, shipping, and multiple purchase units are not supported.
- **Closed tabs leave the run parked.** If a respondent pays and then closes the tab before returning, the payment completes with the provider but the workflow run stays parked at the payment step. The payment is visible in your Stripe or PayPal dashboard; the run will not continue on its own.
- **Two payment steps in one workflow are supported.** Each payment step writes its results into the variables you map on that step, so a second payment step does not overwrite the first one's payment details.
- Customers are created by Stripe Checkout itself; you cannot manage Stripe customer records from FormAssembly. Likewise, PayPal products and billing plans are authored in your PayPal dashboard.

## Tips & Troubleshooting

- **The respondent lands back on the form after paying.** Check the payment step's failure path — if a genuine cancel loops back to the **Collect** step, that's expected. If a *successful* payment lands there, confirm the step's success path leads to your intended next step.
- **A sandbox test run fails immediately at the payment step.** The most common cause is a fixed catalog price or billing plan: that ID exists only in your live catalog. Swap in a custom-amount line item for testing, or ask Fai to add one.
- **The test run charged a real card.** The payment step had no sandbox connection set. Authorize a sandbox connection with **Connect sandbox account** on the **Connections** page and ask Fai to set it on the step.
- **The step aborts before the payment page opens.** Check the mapped amount. Zero, negative, blank, or non-numeric amounts stop the step, as do amounts with more decimal places than the currency allows. For PayPal, also check that the step holds either one-time items or a single subscription plan, not both.
- **A subscription line item won't accept an amount.** Recurring pricing has to come from your catalog — create the recurring price in Stripe or the billing plan in PayPal, then reference it in the line item.
- **Where do I see the error details?** Open **Execution log** on the workflow to see what the payment step reported, including the reference PayPal returns for its own support team.
- **PayPal says the seller is not ready.** Your PayPal account cannot receive payments yet, or your primary email is unconfirmed. Finish those steps in PayPal, then connect again from the **Connections** page.
- **PayPal says "The provider did not finish setting up the account."** The full message is *"The provider did not finish setting up the account. Complete the sign-up with the provider, then connect again."* — the sign-up on PayPal's side was left before it finished. Finish signing up with PayPal, then connect again from the **Connections** page.
- **How do I confirm which PayPal account is connected?** A successful PayPal connection shows a banner naming the connected PayPal account's email address. If that is not the account you expect funds to settle in, connect again with the right account.
- **A PayPal payment shows as pending.** eChecks and PayPal reviews clear over days. The workflow treats the payment as successful; map the payment status to a variable and branch on it if fulfilment must wait for cleared funds.
- **The confirmation message shows nothing where the amount should be.** Check that the amount is actually mapped to a variable on the payment step — unmapped payment details are not available downstream — and remember that payment variables are written only when the payment completes, so they're available on the success path only. Use the **Insert field value** control on the **Confirmation message** to insert them rather than typing the name by hand.
- **Prefill the email.** Mapping your form's email field to the checkout email reduces drop-off and makes the returned customer email match the response.
- **Verify with the dashboard links.** The payment and subscription links returned by the step point directly at the record in Stripe or PayPal — write them into your CRM or a sheet to make reconciliation quick.