How Stripe Online Payments Work

Source: stripe_controller.rb

• Session validation is skipped for payment endpoints because they are customer-facing (accessed via public invoice links)
• Payment intent creation requires either a valid session-based auth OR a public invoice link token — both paths are accepted
• The invoice must be in "processed" status with the full balance outstanding; partial payments via Stripe are not supported
• Stripe fee passthrough is calculated from the integration-level setting; if not set, it falls back to the global default rate
• Zero-decimal currencies (e.g., JPY) skip the standard multiply-by-100 conversion when creating the payment intent amount
• Only one payment intent is created per invoice (idempotency enforced); if an intent gets stuck in an incomplete state, it requires manual cleanup in the database
• Xero and QuickBooks accounting syncs triggered by payment run in separate background threads — if they fail, the payment still succeeds but the sync is silently lost
• The webhook endpoint validates the origin site against a list of known production sites; if the site is not recognized, it returns 200 OK but silently ignores the event (no error logged)
• A successful payment triggers both a fee adjustment line item (if fee passthrough is enabled) and the payment record being processed against the invoice
• Cancelled or failed payment intents void the associated payment record and reset the invoice state so the customer can retry

Support scenarios

• "Customer paid online but it's not showing in Xero/QuickBooks" → The accounting sync runs in a background thread that can fail silently. Check delayed jobs for errors; the payment itself is recorded in Workshop but the sync needs to be re-triggered manually.
• "Customer is getting an error when trying to pay an invoice online" → Verify the invoice is in "processed" status with the full balance due. If a previous payment attempt was abandoned, there may be a stuck payment intent — check for orphaned intent records on the invoice.
• "The Stripe fee amount looks wrong on the invoice" → Check the integration-level fee rate setting first; if blank, it uses the global default. The rate applied may differ from what the workshop expected if the settings are mismatched.
• "We got a Stripe webhook but nothing happened" → The webhook checks the origin site against known production sites. If the workshop's site URL has changed or is misconfigured, the webhook returns 200 OK but does nothing. Check the site URL in settings.