PayPal Commerce
Some workspaces may use PayPal for commerce checkout alongside or instead of Stripe-backed flows. Use this guide to verify provider readiness before exposing product checkout to customers.
Provider Rule
Document which payment provider owns each customer path. Product checkout, booking deposits, booking final payments, invoices, refunds, tax, wallets, and payout reporting may not all support the same provider in the same way.
Where To Configure
PayPal should be treated as a checkout provider with workspace-level readiness and per-flow behavior. Review provider status first, then confirm that the specific product, booking, refund, or tax path is allowed to use PayPal.
- Provider status
- Payments, Shop > Payments
- Product checkout
- Products, Shop, Checkout and Tax
- Order management
- Orders, Payments
- Refunds
- Orders, Payments
- Tax and shipping
- Checkout and Tax, Shipping, product shipping settings
- Provider fallback
- Payments, feature flags, checkout configuration
Console Setup Preview
Use this preview before enabling PayPal as a visible payment option.
Payments or Shop > Payments
What should be visible: PayPal connection status and provider availability
Customer proof: PayPal appears only on supported checkout paths
Checkout and Tax
What should be visible: Return/cancel behavior, taxes, shipping, discounts, and provider fallback are understood
Customer proof: Customer totals match the order record
Product catalog
What should be visible: Products have valid prices, variants, fulfillment rules, visibility, and inventory
Customer proof: Product checkout can create an order and return to the site
Orders
What should be visible: Provider payment state, refund path, and operator owner are clear
Customer proof: Customer portal order history matches payment outcome
Provider matrix
What should be visible: Operators know which payment paths still require Stripe, invoice, or manual payment
Customer proof: Customers do not see unsupported provider options
If the PayPal path is incomplete, hide PayPal and keep the tested Stripe or manual-payment path available only where appropriate.
When To Use PayPal
Use PayPal when:
- The workspace wants PayPal as a visible payment option for product checkout.
- The workspace’s product catalog, shipping, and tax setup are compatible with the PayPal path.
- Operators understand where orders, refunds, and provider status appear in console.
- Launch QA has proven the exact product checkout path customers will use.
Use Stripe when the workflow depends on Stripe-specific connected-account capabilities, booking payment flows, hosted invoices, wallets, application-fee behavior, or tax/account sessions that are not supported by the PayPal path in the workspace.
Setup Flow
- Open Payments or Shop > Payments.
- Start or resume PayPal onboarding.
- Confirm provider status after returning to the console.
- Review product checkout settings.
- Confirm checkout, tax, shipping, and order confirmation behavior.
- Run a customer-path test through the approved payment boundary.
- Verify the order, provider state, notification, and customer portal history.
Product Checkout Checklist
Before Enabling PayPal Checkout
- PayPal status is connected or ready in console.
- Products have valid prices, variants, inventory, visibility, tax posture, and shipping rules.
- Checkout page shows only payment options that are actually available.
- Success, return, and cancel routes use the production domain.
- Order record is created under the correct workspace and customer.
- Refund owner, provider process, and customer communication are understood.
- Operators know which flows still require Stripe, manual payment, or invoices.
Provider Decision Matrix
Product checkout
Stripe Connect: Common provider for card, wallet, connected-account, and refund workflows
PayPal: Use when the PayPal checkout path is enabled and tested
Booking deposit
Stripe Connect: Use when booking payment flow requires Stripe-backed payment intent or checkout
PayPal: Confirm support before offering as a booking payment path
Booking final payment
Stripe Connect: Use for pay links, final invoice, and Stripe-backed booking balances
PayPal: Confirm support before exposing to customers
Hosted invoice
Stripe Connect: Stripe-backed invoice flow
PayPal: Use only when PayPal invoice behavior is explicitly supported
Refunds
Stripe Connect: Managed from order/payment state
PayPal: Confirm PayPal refund path and operator owner
Tax/account sessions
Stripe Connect: Stripe-specific in many flows
PayPal: Confirm tax behavior before launch
Launch QA
Run this with a product that exercises the riskiest checkout combination:
- Product with variants.
- Physical fulfillment when shipping applies.
- Taxable product when tax applies.
- Discount or coupon when promotions are enabled.
- Customer account or guest checkout path.
- Return/cancel behavior.
- Refund or void process when the payment owner approves the test.
Troubleshooting
PayPal button is missing
Provider status, checkout settings, product visibility, feature flag
Checkout opens but cannot complete
Provider account status, product price, shipping, tax, return URL
Order missing after payment
Provider event delivery, order creation, customer email, workspace scope
Refund unavailable
Payment status, provider refund support, order state, permissions
Customer sees both providers unexpectedly
Checkout settings and feature flags
Booking payment uses wrong provider
Scheduling payment settings and provider support matrix
Related Guides
Use these guides when PayPal behavior depends on the broader commerce, payment, or launch surface rather than the provider connection alone. Start with the workflow that owns the broken customer path, then use the provider guide to compare PayPal behavior with Stripe-backed checkout expectations.