Why FastSpring

FastSpring is a Merchant of Record (MoR). That means FastSpring — not you — is the seller of record on every transaction. In practice this offloads a long list of compliance and operational headaches:

Sales tax, VAT and GST are calculated, collected and remitted by FastSpring across 200+ countries. You don't register for VAT in the EU, file Australian GST, or keep track of US state nexus.
Multi-currency pricing and checkout in 25+ currencies — buyers see local prices, you receive a single payout in your reporting currency.
Fraud, chargebacks and PCI scope are owned by FastSpring. You never touch a card number; PCI DSS reduces to the bare minimum self-assessment.
Payment methods (cards, PayPal, Apple Pay, Google Pay, SEPA, bank redirects, local methods) work out of the box without per-method onboarding.
Invoicing & receipts are issued under FastSpring's legal entity, with all the local-language localisation required for B2C and B2B sales.
Built-in dunning and recovery — failed-payment retries, account-update, and customer-self-service portal are part of the platform.
Subscription life-cycle features — paid trials, free trials, percentage and fixed-amount intro offers, multi-phase pricing, and product-switch (e.g. trial → regular) are configured in the FastSpring dashboard, not in code.

If you are selling globally and don't want to staff a tax & compliance team, FastSpring is one of the strongest options in the SaaS / digital-goods space.

Before you start

Create a FastSpring account: https://accounts.fastspring.com/account/signup.
Complete the business verification (KYC) in the FastSpring dashboard. You will need legal entity details, banking information for payouts, and a verified domain. Verification can take several business days; nothing in this guide will run live until your account is approved. Reference: https://docs.fastspring.com/getting-started/account-setup-and-verification.
Pick (or create) the FastSpring storefront you want to use. The storefront subdomain (e.g. mycompany.onfastspring.com or mycompany.test.onfastspring.com) is the most important identifier — web2wave needs it to call the API and to render the checkout.

Sandbox first. FastSpring exposes a separate Test mode under the same account. Use it for the entire integration, then flip the toggles to live keys at the end.

Integration guide

Part 1 – Set up your FastSpring account

1: Log into the FastSpring dashboard at app.fastspring.com (or app.test.fastspring.com for sandbox).

2: Go to Integrations → API Credentials → Generate Credentials. FastSpring will issue an API Username and API Password — copy both. Reference: https://docs.fastspring.com/integrations/api-credentials.

3: Go to Integrations → Webhooks → Configuration → Add Webhook.

Set Live and Test Orders to On.
Leave Webhook Expansion off.
Generate an HMAC SHA256 secret and copy it (web2wave will use it to verify webhook signatures).
Tick the following events:
- order.completed
- subscription.activated
- subscription.canceled
- subscription.deactivated
- subscription.uncanceled
- subscription.updated
- subscription.charge.completed
- subscription.charge.failed
- subscription.paused
- subscription.resumed
- return.created
- chargeback.created
Save the webhook — you'll paste the URL in Part 4.

Callout: The HMAC secret is optional in web2wave. If you leave both HMAC fields blank in the project settings, web2wave will still accept FastSpring webhooks and rely on the FastSpring outbound IP as the only authentication. Configuring the HMAC secret is strongly recommended for production.

Part 2 – Create prices in FastSpring

web2wave imports your FastSpring catalog into Plans & Prices automatically. You only need to model your products correctly on the FastSpring side.

4: In the FastSpring dashboard, go to Products → Create Product.

Set Type to Subscription (for recurring) or One-time (for single-purchase paywalls).
Configure the billing period (day / week / month / year) and interval length (e.g. month every 1).
Add a price for each currency you sell in. Each currency × product becomes one row in the web2wave Prices table.
Set Visibility to Public and confirm Quotable is On — web2wave skips drafts and archived items.
Reference: https://docs.fastspring.com/products/create-a-subscription-product.

Trials and introductory offers

web2wave supports two trial styles on the FastSpring side and imports both correctly:

Free trial — open the product in FastSpring, scroll to the Subscription section, and set the number of free days in the Free Trial field. The free days will appear next to the price in your web2wave Prices list.
Paid trial or introductory offer — create a Discount in FastSpring (Promotions → Discounts) that applies to the first billing periods of the product. For example, 100% off for the first 30 days gives you a free trial that auto-converts, and $1.99 for the first week gives you a paid intro offer. web2wave imports the discount as the first phase of the price, so the buyer sees the same intro pricing on your paywall.

Callout — Subscription Switch is supported, but not fully shown after import.
FastSpring lets you set up a subscription that automatically switches from one product to another after the trial ends (for example, a trial product that switches to a regular product). Subscriptions like this keep working correctly — web2wave still receives every renewal and the customer is charged the right amount — but the price you see in the web2wave cabinet will only reflect the first product, so after the switch the cabinet may still show the trial product even though the customer is paying for the regular one. Recommendation: configure your trials and intro offers as a Discount on a single product (see the bullet above) instead of using a two-product switch. This way the price shown in web2wave matches what the customer actually pays for the whole life of the subscription.

5: Once your products are saved, web2wave will pull them in Part 5.

Part 3 – Create and style the Embedded Checkout

web2wave renders the FastSpring checkout inline on your paywall — buyers don't get redirected to a FastSpring-hosted page. To make this work you need to create an Embedded Checkout in FastSpring and copy its URL slug into web2wave.

6: In FastSpring, go to Storefronts → Embedded Checkout → Create Embedded Checkout.

URL slug — the path component that follows your storefront. The default embedded works for most accounts; web2wave will compose <account-subdomain>/<slug> and send it as checkoutPath to the FastSpring sessions API. Copy this slug — you'll paste it into web2wave in Part 4.
Default products — leave empty. web2wave fills the cart from the price the buyer selected on your paywall.
Currency override — leave Auto unless you want to force a single currency for every buyer.

7: Style the checkout. FastSpring exposes a Theme Editor under Storefronts → Embedded Checkout → Theme. The most useful knobs are:

Colors — primary / accent / background / text. Match the swatches to your paywall design tokens.
Typography — choose a Google font that matches your brand. Avoid free-tier fonts that ship with limited weights — the checkout uses 400/500/600 at minimum.
Layout — set field labels to Floating or Top to match your existing forms.
Custom CSS — for fine-grained tweaks (button radius, spacing, hover states). FastSpring supports a small subset of CSS targeting checkout-internal selectors; reference: https://docs.fastspring.com/storefronts/style-the-embedded-storefront.

Callout: Theme changes preview live in FastSpring, but the Embedded Checkout caches aggressively. After you publish a new theme, hard-refresh your paywall (Cmd+Shift+R) — otherwise you may keep seeing the previous styling.

8: Save the Embedded Checkout.

Part 4 – Connect FastSpring to web2wave

9: In web2wave, click Projects in the left sidebar, find your project, and open its settings. Activate the FastSpring switch.

10: Fill in the Production Keys column:

Field	Value
Account subdomain	The part before `.onfastspring.com`, e.g. `mycompany`.
API Username	From Part 1, Step 2.
API Password	From Part 1, Step 2.
Webhook HMAC Secret	From Part 1, Step 3 (leave blank to disable verification).
Embedded checkout slug	The URL slug from Part 3 (e.g. `embedded`).

11: If you also want to test before going live, fill in the Sandbox Keys column with the equivalent values from your test storefront. The sandbox account subdomain is typically <company>.test; the API credentials are issued separately under the Test mode in FastSpring.

12: Copy the Webhook URL displayed in the project settings (https://<your-project>.web2wave.com/fastspring/webhook) and paste it into the FastSpring webhook you created in Part 1, Step 3.

13: Click Save.

Part 5 – Import prices into web2wave

14: In web2wave, go to Plans and Prices → Import Plans and Prices. Select your project, set Payment System to FastSpring, and click Start Import.

15: web2wave will pull every public, quotable product and create one Plan per product plus one Price per (product, currency) pair. Trials and discount phases are imported automatically. Verify the imported rows in the Prices list.

16: Open the paywall editor for the project and confirm that the FastSpring prices are selectable in the Plans field. Add the FastSpring form block to the paywall in the place where the Embedded Checkout should appear.

17: Run a sandbox test purchase to confirm the full flow:

Embedded Checkout renders on the paywall and reloads when the buyer switches between prices.
FastSpring webhooks reach web2wave — you can see each delivery in Project → Webhooks and the new subscription in your project's subscription list.
The subscription appears in the cabinet with the FastSpring order ID shown as a clickable link straight to the FastSpring dashboard.

Troubleshooting

Q: FastSpring: session creation failed. HTTP 400 {"message":"required","params":["Purchaser account or contact"]}

What it means: FastSpring requires the buyer's email before the checkout can be created, but no email was supplied.
Resolution: Make sure the paywall collects the buyer's email before the FastSpring form block renders, or pre-fill it from earlier quiz answers. Once the email is captured, web2wave passes it to FastSpring automatically.

Q: Embedded Checkout renders, but the form does not reload when the buyer switches prices.

What it means: The checkout was initialised once with the original price and was not refreshed when the buyer picked a different one.
Resolution: Make sure you're on the latest paywall renderer — the FastSpring form block automatically resets and re-renders the checkout on every price change. If you've customised the block, leave that reset behaviour in place.

Q: Checkout shows “No products configured”.

What it means: The Embedded Checkout in FastSpring has no default product, and the price selected on the paywall couldn't be matched to a FastSpring product. This usually happens when the imported price in web2wave is out of sync with the FastSpring catalog.
Resolution: Re-run the price import (Part 5) to refresh the link between web2wave and your FastSpring products.

Q: Subscription appears as canceled in web2wave, but the FastSpring dashboard shows it as still Active.

What it means: FastSpring sends a "cancellation scheduled" event the moment the customer asks to cancel, even though the subscription stays active until the end of the current billing period. web2wave handles both cases.
Resolution: None — this is intended behaviour. The cabinet marks the subscription as scheduled to cancel at period end until FastSpring confirms the actual deactivation, at which point the status flips to Canceled.

Q: The price column in the cabinet shows the trial product, not the regular one, after a Subscription Switch.

What it means: You configured a Switch Product in FastSpring (trial product → regular product). web2wave imports each product separately and links the subscription to the first product the customer paid for, so the price label stays on the trial product.
Resolution: This is a known limitation — the subscription itself continues to bill correctly through FastSpring's webhooks and the revenue and charge counts in the cabinet stay accurate. To avoid the cosmetic mismatch, configure the trial as a Discount on a single product instead of using a two-product switch.

Q: Webhook deliveries fail with an "invalid signature" error.

What it means: The webhook signing secret saved in web2wave does not match the one FastSpring is using.
Resolution: Either regenerate the secret in FastSpring and paste the new value into the matching web2wave field (Production or Sandbox Webhook HMAC Secret), or clear the secret in web2wave to disable signature verification. Both modes are supported.

Q: Need to re-sync revenue and invoices for a specific subscription?

Open the subscription in the web2wave cabinet and click Recalculate. web2wave will pull the latest data from FastSpring (the subscription, its renewal history, and the original order) and rebuild the invoice list from that authoritative source. The full request log is available in the project's logs.