← Tutti gli articoli

Sviluppatori · 6 min · 18 agosto 2026

Perché ho costruito un checkout PayPal completo su Cloudflare Workers invece di usare Stripe

Quando ho migrato su Webround un e-commerce attivo da 4 anni, il cliente aveva un requisito non negoziabile: PayPal doveva funzionare. I suoi clienti erano abituati a usarlo e toglierlo avrebbe significato perdere conversioni fin dal primo giorno.

Pensavo fosse una cosa semplice, e invece non lo era.

Il vicolo cieco di Stripe Connect

Webround usa Stripe Connect in modalità standard: la piattaforma trattiene una commissione, ma il merchant mantiene il proprio account Stripe e riceve i pagamenti direttamente. È un'architettura pulita, tiene Webround fuori dalle questioni non tecniche e non crea problemi.

Tranne che con PayPal.

Stripe Connect in modalità standard non supporta PayPal a meno che tu non sia un merchant of record, cioè incassi i soldi per conto dei tuoi merchant e li ridistribuisci tu. È un modello di business completamente diverso, che comporta un'intera serie di responsabilità. Mi sembrava abbastanza strano da dover chiedere conferma al supporto di Stripe. Dopo una telefonata (sì, Stripe ti chiama, ovunque tu sia), ho avuto la conferma che ciò di cui aveva bisogno il mio cliente richiedeva un cambiamento nel modello di responsabilità interno di Webround.

Non era una strada percorribile, ma per fortuna, con Webround dalla mia parte, trovare una soluzione alternativa non è stato difficile.

L'equivalente di PayPal

La seconda idea che ho avuto è stata integrare a livello di piattaforma l'equivalente di Stripe Connect di PayPal (PayPal Marketplace), così il merchant avrebbe potuto collegare il proprio account PayPal in modo nativo. In teoria aveva senso, in pratica un po' meno: c'è un processo di approvazione, devi parlare con qualcuno del team commerciale, raggiungere una soglia minima di volume e passare da un onboarding partner che richiede settimane. Non percorribile.

L'approccio standalone

Terza opzione: costruire un flusso di checkout PayPal standalone che aggira del tutto sia Stripe sia qualsiasi modello Connect. Il merchant usa direttamente il proprio account PayPal. In pratica, un normalissimo processo di pagamento PayPal da orchestrare correttamente.

Da qualche anno uso Cloudflare Workers per questo genere di cose: leggeri, distribuiti sull'edge, perfetti per integrazioni serverless stateless.

Ho pubblicato il codice sorgente completo su GitHub: github.com/WebroundAdmin/wr-paypal-integration. Usalo pure come punto di partenza.

Come funziona il flusso

  1. Il cliente clicca su PayPal: il Worker valida il carrello tramite l'API di Webround. Non si fida mai di quello che dice il frontend.
  2. Il Worker crea l'ordine Webround (stato: created) e l'ordine PayPal.
  3. L'ID dell'ordine PayPal torna al frontend, che apre la pagina di pagamento.
  4. Il cliente approva e il frontend cattura il pagamento. Non ci fidiamo del frontend per il cambio di stato dell'ordine. Usiamo i webhook!
  5. PayPal invia il webhook firmato e il Worker verifica la firma HMAC.
  6. Il Worker aggiorna l'ordine Webround a paid.
  7. Webround emette l'evento order.paid verso le tue integrazioni esistenti.

Step 1. Validare il carrello lato server

Non fidarti mai dei prezzi inviati dal client, perché qualsiasi richiesta può manipolarli. Quando il cliente avvia il checkout, il Worker recupera direttamente dall'API di Webround il vero prezzo netto, l'aliquota fiscale e la disponibilità a magazzino di ogni articolo.

typescript
const verifiedItems = await Promise.all(
  items.map(async item => {
    const { unitNet, taxRate, packageWeight } = await fetchVariantData( // Method that calls the Webround API
      env,
      item.variantId,
      item.productId,
      item.priceId,
      currencyCode,
      shippingAddress.countryCode
    );
    return { ...item, netAmount: unitNet, taxRate, packageWeight };
  })
);

Step 2. Calcolare il totale (e la trappola degli arrotondamenti)

Qui le cose si fanno interessanti.

Stripe e PayPal calcolano i totali degli ordini in modo diverso:

Stripe:

plaintext
unitGross = round(netAmount × (1 + taxRate/100) × 100) / 100
lineTotal = unitGross × quantity

PayPal:

plaintext
lineTotal = round(netAmount × quantity × (1 + taxRate/100) × 100) / 100

È un dettaglio implementativo: potresti semplicemente inviare il totale direttamente alla sessione di checkout di Stripe, ma nell'integrazione Stripe nativa di Webround la pagina di pagamento mostra il dettaglio completo del carrello: immagini, nome, prezzo unitario e totale di riga. Quindi Stripe, che lavora in centesimi quando si paga in EUR, ha bisogno di conoscere il totale IVA inclusa di una singola unità prima di poter mostrare il totale su tutte le quantità acquistate.

Su un acquisto di una sola unità la differenza è zero. Su un carrello con quantità miste e prezzi decimali, i totali divergono.

Me ne sono accorto in produzione. Non perché un cliente si fosse lamentato... dal suo punto di vista il checkout funzionava benissimo. Me ne sono accorto perché l'export degli ordini ricalcolava i totali lato server e i numeri non corrispondevano a quanto PayPal aveva effettivamente addebitato. Discrepanze silenziose nell'export contabile.

Ecco un esempio:

plaintext
Take a product with a net price of €8.17 and a 22% VAT rate:
Exact gross: 8.17 × 1.22 = €9.9674

PayPal method: multiply first, round after:
9.9674 × 3 = 29.9022 → rounded: €29.90

Stripe method: round first, multiply after:
9.9674 → rounded to 2 decimals: €9.97
9.97 × 3 = €29.91

A difference of €0.01 per order. Silent, systematic, and impossible to catch in happy-path testing.

La soluzione: allineare il calcolo di PayPal al metodo di Stripe, che è l'integrazione nativa di Webround, quindi è PayPal che si adatta.

typescript
const grandTotal = verifiedItems.reduce((sum, item) => {
  // Stripe-compatible rounding: round unit gross first, then multiply by quantity
  const unitGrossCents = Math.round(item.netAmount * (1 + item.taxRate / 100) * 100);
  return sum + (unitGrossCents / 100) * item.quantity;
}, 0);

Applica lo stesso metodo quando crei gli articoli dell'ordine:

typescript
const unitGrossCents = Math.round(item.netAmount * (1 + item.taxRate / 100) * 100);
const unitGross = unitGrossCents / 100;
const unitNet   = item.taxRate > 0 ? unitGross / (1 + item.taxRate / 100) : unitGross;
const unitTax   = unitGross - unitNet;

Scegli un metodo e applicalo in modo coerente ovunque. È proprio la discrepanza a causare il bug.

Step 3. Creare l'ordine Webround e l'ordine PayPal in parallelo

typescript
const [wrCustomerId, paypalToken] = await Promise.all([
  ensureCustomer(env, customerEmail, billingAddress, customerId),
  getPayPalToken(env),
]);

const [wrOrder, paypalOrder] = await Promise.all([
  createOrder(env, wrCustomerId, customerEmail, currencyCode, grandTotalStr, shippingCostStr, billingAddress, shippingAddress),
  createPayPalOrder(env, paypalToken, grandTotalStr, currencyCode),
]);

Salviamo la corrispondenza tra l'ID dell'ordine PayPal e l'ID dell'ordine Webround in una tabella Cloudflare D1: ci servirà quando arriverà il webhook.

typescript
await Promise.all([
  createOrderItems(env, wrOrder.id, verifiedItems),
  saveOrderMapping(env, paypalOrder.id, wrOrder.id),
]);

Il Worker restituisce l'ID dell'ordine PayPal al frontend, che lo passa all'SDK JS di PayPal per aprire la pagina di pagamento.

Step 4. Gestire il webhook

Dopo che il cliente approva e il frontend cattura il pagamento, PayPal invia un evento webhook firmato. Questo è il segnale autorevole che il pagamento è andato a buon fine. Non fidarti mai di ciò che succede sul client!

typescript
const body  = await request.text();
const token = await getPayPalToken(env);

const valid = await verifyWebhookSignature(env, request, body, token);
if (!valid) return new Response("Unauthorized", { status: 401 });

const event = JSON.parse(body) as { event_type: string; resource: any };

const wrStatus = WEBHOOK_STATUS_MAP[event.event_type];
// PAYMENT.CAPTURE.COMPLETED → "paid"
// PAYMENT.CAPTURE.DENIED    → "failed"
// CHECKOUT.ORDER.CANCELLED  → "canceled"

const mapping = await getOrderMapping(env, paypalOrderId);

await Promise.all([
  updateMappingStatus(env, paypalOrderId, wrStatus),
  updateOrderStatus(env, mapping.wr_order_id, wrStatus),
]);

Quando lo stato dell'ordine Webround diventa paid, Webround emette l'evento order.paid verso tutti i webhook registrati: email di conferma, aggiornamenti di magazzino, sincronizzazioni CRM, tutto resta in ascolto lì. Il flusso PayPal si inserisce in un sistema di eventi parallelo a quello nativo di Stripe, grazie all'architettura di Webround e ai suoi webhook.

Il componente frontend

Lato Webround, si tratta di un componente React custom inserito nell'IDE integrato e aggiunto alla pagina del carrello sotto il pulsante di checkout nativo.

tsx
export default function PayPalButton({ wr }: { wr: Wr }) {
    const [message, setMessage] = useState("");
    const currencyCode = wr.customer.cart.items[0]?.currencyCode ?? "EUR";

    const cartItems = wr.customer.cart.items.map((item) => ({
        variantId: item.variantId,
        productId: item.productId,
        priceId: item.priceId,
        quantity: item.quantity,
    }));

    const payload = {
        items: cartItems,
        currencyCode,
        customerEmail: wr.cart.customerEmail,
        customerId: wr.customer.isLoggedIn ? wr.customer.profile?.id : undefined,
        customerJwt: wr.customer.isLoggedIn ? wr.customer.accessToken : undefined,
        billingAddress: wr.cart.selectedBillingAddress,
        shippingAddress: wr.cart.selectedShippingAddress,
    };

    return (
        <PayPalScriptProvider options={{ clientId: PAYPAL_CLIENT_ID, currency: currencyCode }}>
            <PayPalButtons
                createOrder={async () => {
                    const res = await fetch(`${WORKER_URL}/api/orders`, {
                        method: "POST",
                        headers: { "Content-Type": "application/json" },
                        body: JSON.stringify(payload),
                    });
                    const data = await res.json();
                    if (data.id) return data.id;
                    throw new Error(JSON.stringify(data));
                }}
                onApprove={async (data, actions) => {
                    const res = await fetch(`${WORKER_URL}/api/orders/${data.orderID}/capture`, {
                        method: "POST",
                    });
                    const orderData = await res.json();
                    const errorDetail = orderData?.details?.[0];

                    if (errorDetail?.issue === "INSTRUMENT_DECLINED") return actions.restart();
                    if (errorDetail) throw new Error(errorDetail.description);

                    window.location.href = "/checkout/success?clean_cart=true";
                }}
            />
        </PayPalScriptProvider>
    );
}

Cosa ha sbloccato

Il Worker è diventato la base dell'intero livello di pagamento del cliente al di fuori di Stripe. Separazione netta: Stripe ha il suo microservizio isolato, PayPal passa dal Worker. Entrambi convergono sul sistema ordini di Webround e fanno scattare lo stesso evento order.paid a valle, con la differenza che PayPal fa tutto dall'esterno tramite API REST.

Ora il cliente gestisce entrambi i metodi di pagamento in parallelo, con piena copertura dei webhook e tracciamento corretto degli eventi su entrambi i lati.

In sintesi

Se stai costruendo su una piattaforma che usa Stripe Connect in modalità standard, non dare per scontato che PayPal sia solo questione di un plugin. Non lo è. Ma non è nemmeno impossibile: basta occuparsi in prima persona dell'orchestrazione.

Cloudflare Workers è una buona scelta per questo caso d'uso perché la logica è stateless, la latenza conta al checkout e gestione dei secret e D1 sono già inclusi.

Testa gli arrotondamenti prima di andare in produzione. Non emergeranno nei test del percorso ideale. Confronta esplicitamente i totali tra il calcolo della tua piattaforma e quello di PayPal, con dati di prodotto reali e quantità miste, prima di rilasciare.

Il sorgente completo del Worker, il componente React, lo schema D1 e la configurazione wrangler sono su GitHub: github.com/WebroundAdmin/wr-paypal-integration

Costruito su Webround, una piattaforma e-commerce API-first. Tutti gli endpoint di ordini, catalogo e checkout sono documentati pubblicamente su docs.webround.com.