Stripe Integration (Phase B) #

Componenti #

HWBillingStripeStripeClient #

Wrapper REST minimale (no Composer). Implementa solo gli endpoint usati:

• Products: product_create, product_update, product_get
• Prices: price_create, price_get, price_archive
• Checkout: checkout_session_create, checkout_session_get
• Customers: customer_create, customer_get
• Subscriptions: subscription_get, subscription_cancel
• verify_webhook($payload, $sig_header, $secret) — HMAC-SHA256 con tolerance 5min anti-replay

API key letta da wp_option('hwbi_stripe_secret_key'). Tutte le request:

• Header Stripe-Version: 2024-12-18.acacia
• Bracket notation per nested arrays (metadata[order_id]=42)
• Audit log su errori HTTP/API

HWBillingStripeStripeProductSync #

Push one-way: piano locale → Stripe Product + Price.

• Idempotent: se stripe_product_id esiste, update invece di create
• Price immutable: se cambia prezzo, archivia vecchio + crea nuovo
• Salva refs (stripe_product_id, stripe_price_id) nel piano locale
• sync_all() per bulk sync di tutti i piani attivi

HWBillingRestCheckoutController #

Endpoint: POST /wp-json/hostwebo-billing/v1/checkout/stripe/create-session

Auth: logged-in + BillingMode::should_use_v2() (V2 mode attivo per utente).

Flow:

1. Recupera piano (per plan_id o plan_slug)
2. Verifica stripe_price_id presente (cioè: sincronizzato)
3. Crea ordine locale pending_payment + line item
4. Crea Stripe Checkout Session (mode subscription se recurring, payment se one-time)
5. Salva session_id sull’ordine come payment_reference
6. Ritorna { ok, order_id, checkout_url } → browser redirect

Metadata Stripe Session: hwbi_order_id, hwbi_plan_id, hwbi_user_id, hwbi_plesk_plan per matching post-payment.

HWBillingRestWebhookController #

Endpoint: POST /wp-json/hostwebo-billing/v1/webhooks/stripe (no auth WP, auth via Stripe-Signature HMAC).

Idempotency: webhook_event_id UNIQUE in wp_hwbi_payments → replay silenti.

Eventi gestiti:

Errori → 500 response (Stripe retries). Signature invalid → 400 (no retry).

HWBillingProvisioningProvisioningWorker #

Cron hwbi_provisioning_worker ogni minuto (usa hwai_1min se hostwebo-ai attivo).

Per ogni provisioning_jobs.status='pending':

1. Claim atomico (UPDATE … WHERE status=’pending’)
2. Dispatch al handler per job_type
3. Su success: status=done, salva result
4. Su failure: incremento attempts, exponential backoff (scheduled_at = now + 2^attempts min, max 1h). Quando attempts >= max_attempts: status=failed definitivo.

Handlers Phase B:

• create_plesk_subscription: ensure Plesk client exists (auto-detect via email OR create new via PleskBridge). Full domain creation deferred a Phase D.
• cancel: log-only (Phase D farà suspend/cancel reale).

Setup (admin) #

1. Configura API keys #

1. wp-admin → Hostwebo Billing → Impostazioni
2. Stripe section:

• Recupera sk_live_… da https://dashboard.stripe.com/apikeys
• Recupera pk_live_… da stessa pagina

1. Salva

2. Crea webhook su Stripe #

1. https://dashboard.stripe.com/webhooks → “Add endpoint”
2. URL: https://hostwebo.it/wp-json/hostwebo-billing/v1/webhooks/stripe
3. Eventi da listenare:

• checkout.session.completed
• invoice.paid
• invoice.payment_failed
• customer.subscription.created
• customer.subscription.updated
• customer.subscription.deleted

1. Copia whsec_… → incolla in Impostazioni → “Webhook signing secret”

3. Sync piani verso Stripe #

1. wp-admin → Hostwebo Billing → Piani
2. Click “💳 Sync to Stripe (all)” → tutti i piani attivi diventano Products + Prices su Stripe

4. Attiva V2 #

1. Impostazioni → V2 enabled = ON
2. Modalità: “Parallelo” + aggiungi il tuo user_id ai beta users
3. Vai su frontend, click “Acquista ora” su un piano → ti porta a /v2-checkout/ invece di Upmind

Test end-to-end #

1. Stripe test mode: usa sk_test_… + pk_test_… + webhook test
2. Crea ordine da frontend (beta user)
3. Pagamento con carta test 4242 4242 4242 4242
4. Verifica:

• wp_hwbi_orders ha record status='paid'
• wp_hwbi_payments ha record con gateway='stripe' + webhook_event_id valorizzato
• wp_hwbi_provisioning_jobs ha job create_plesk_subscription con status='done' (entro 1 min)
• wp_hwbi_subscriptions ha record per i piani recurring

Filter hooks esposti #

Action hooks emessi #

Altri plugin (hostwebo-dashboard, hostwebo-ai) possono add_action() per reagire (es. inviare email di benvenuto, abilitare AI features extra).