PayPal Suite Expansion

Paid pluginsize Mplanned, not built

Indicative price, not an offer: $199–399/year

Generated from docs/plan/paid/paypal-suite-expansion/PLAN.md in the AstroBaaS repository. Nothing described below is implemented — it is the written plan for it.

Core ships only one PayPal integration (standard checkout). This paid module adds Express Checkout, Payments Standard, Payflow Link, and subscription support for merchants with advanced PayPal workflows.

The problem

I need PayPal Express Checkout for one-click login + payment, and Payflow Link for invoiced customers. Core only has the basic integration, and I need PayPal support to implement each variant.

What it does

• PayPal Express Checkout: one-click login + payment, redirect to PayPal, return with address + email prefilled
• PayPal Payments Standard: form-based subscription billing (recurring, not one-time)
• Payflow Link: generate a payment link for invoiced customers (e.g., email a link, customer pays via Payflow)
• Recurring payments: support for subscriptions (Klarna Advanced already covers installments; this adds PayPal’s native subscription model)
• Multi-currency: PayPal settlement in merchant’s preferred currency (configure in settings)
• Webhook handling: each variant sends different webhook types; verify and apply uniformly

What it deliberately does NOT do

Each boundary carries its reason. A boundary without a reason gets crossed by the next person who reads this.

• PayPal Adaptive Payments (marketplace model) — outside scope, complex payout logic.
• PayPal Here (POS) — that’s in-store payment, not e-commerce checkout.

Data model

Add to Order: paypal_variant (enum: ‘standard’, ‘express_checkout’, ‘payflow_link’, ‘subscriptions’). Webhook routing distinguishes by variant.

API

• POST /api/payments/start — body includes paypal_variant to choose which mode
• POST /api/payments/paypal/subscription — create a recurring payment plan (admin only or storefront for subscriptions module)
• POST /api/payments/webhook/paypal — handles all PayPal webhook variants (dispatch internally by variant)

Every route added here must also appear in src/pages/openapi.json.ts — a test fails the build if it does not.

Admin

Settings panel for PayPal: ‘Integration Variant’ dropdown (standard, express, payflow, subscriptions). Each variant requires different credentials (API signature, API certificate, etc.); form shows required fields per variant. Admin can enable/disable each variant independently.

The seam — why this is paid

Core owns the generic payment flow. Paid module owns variant-specific session creation and webhook handling.

Requires new payment credential(s) and OAuth flows. Support commitment includes PCI DSS compliance, webhook signature handling, and PayPal API deprecation migration.

Dependencies

• payment-status-tracking
• production-payment-gateway-certification — PayPal’s live variants require production credential setup

Acceptance checks

Each of these must be able to fail. Before claiming this is done, break the code deliberately and watch each one go red.

• Express Checkout enabled: customer clicks ‘PayPal’, is taken to PayPal login + review, returns with email + address prefilled
• Payflow Link generated: admin creates link, sends to customer; customer pays via link; webhook confirms payment
• Subscription created: customer enrolled in monthly payments; webhook confirms each charge; order status=‘processing’ after first charge
• Merchant switches variant from ‘Standard’ to ‘Express’: new orders use Express, old ones unchanged

Risks

Credential confusion: each variant needs different API credentials. If merchant sets up the wrong one, checkout fails silently. Validation at boot must catch this. Webhook variants: PayPal sends different event types per variant (IPN vs. API vs. Adaptive). A mistake in routing breaks payments. Subscription edge cases: if a subscription payment fails after initial success, what happens to the order? Retry, cancel, hold? Merchant policy varies; module must not assume.

Commercial context

The anchor is what the nearest equivalent charges on Shopify or Magento today. It is context for a pricing decision, not the decision.

---

Generated from the commerce plan. See docs/COMMERCE-PLAN.md for the full catalogue and ../../AI-GUIDE.md for how to work on this repository.