> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Express Adaptor

> Scopri come integrare Dodo Payments con il tuo progetto Express App Router utilizzando il nostro Express Adaptor. Copre checkout, portale clienti, webhook e configurazione dell'ambiente sicuro.

<CardGroup cols={2}>
  <Card title="Checkout Handler" icon="cart-shopping" href="#checkout-route-handler">
    Integra il checkout di Dodo Payments nella tua app Express.
  </Card>

  <Card title="Customer Portal" icon="user" href="#customer-portal-route-handler">
    Consenti ai clienti di gestire abbonamenti e dettagli.
  </Card>

  <Card title="Webhooks" icon="bell" href="#webhook-route-handler">
    Ricevi ed elabora in modo sicuro gli eventi webhook di Dodo Payments.
  </Card>
</CardGroup>

## Installazione

<Steps>
  <Step title="Install the package">
    Esegui il seguente comando nella root del tuo progetto:

    ```bash theme={null}
    npm install @dodopayments/express
    ```
  </Step>

  <Step title="Set up environment variables">
    Crea un file <code>.env</code> nella root del tuo progetto:

    ```env expandable theme={null}
    DODO_PAYMENTS_API_KEY=your-api-key
    DODO_PAYMENTS_WEBHOOK_KEY=your-webhook-secret
    DODO_PAYMENTS_ENVIRONMENT="test_mode" or "live_mode"
    DODO_PAYMENTS_RETURN_URL=your-return-url
    ```

    <Warning>
      Non eseguire mai il commit del tuo file <code>.env</code> o dei segreti nel controllo versione.
    </Warning>
  </Step>
</Steps>

## Esempi di Gestore Route

<Tabs>
  <Tab title="Checkout Handler">
    <Info>
      Usa questo handler per integrare il checkout di Dodo Payments nella tua app Express. Supporta i flussi di pagamento statici (GET), dinamici (POST) e sessione (POST).
    </Info>

    <CodeGroup>
      ```typescript Express Route Handler expandable theme={null}
      import { checkoutHandler } from '@dodopayments/express';

      app.get('/api/checkout', checkoutHandler({
          bearerToken: process.env.DODO_PAYMENTS_API_KEY,
          returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
          environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
          type: "static"
      }))

      app.post('/api/checkout', checkoutHandler({
          bearerToken: process.env.DODO_PAYMENTS_API_KEY,
          returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
          environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
          type: "dynamic"
      }))

      app.post('/api/checkout', checkoutHandler({
          bearerToken: process.env.DODO_PAYMENTS_API_KEY,
          returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
          environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
          type: "session"
      }))
      ```
    </CodeGroup>

    <CodeGroup>
      ```curl Static Checkout Curl example expandable theme={null}
      curl --request GET \
      --url 'https://example.com/api/checkout?productId=pdt_fqJhl7pxKWiLhwQR042rh' \
      --header 'User-Agent: insomnia/11.2.0' \
      --cookie mode=test
      ```
    </CodeGroup>

    <CodeGroup>
      ```curl Dynamic Checkout Curl example expandable theme={null}
      curl --request POST \
      --url https://example.com/api/checkout \
      --header 'Content-Type: application/json' \
      --header 'User-Agent: insomnia/11.2.0' \
      --cookie mode=test \
      --data '{
      "billing": {
        "city": "Texas",
        "country": "US",
        "state": "Texas",
        "street": "56, hhh",
        "zipcode": "560000"
      },
      "customer": {
        "email": "test@example.com",
        	"name": "test"
      },
      "metadata": {},
      "payment_link": true,
        "product_id": "pdt_QMDuvLkbVzCRWRQjLNcs",
        "quantity": 1,
        "billing_currency": "USD",
        "discount_codes": ["IKHZ23M9GQ"],
        "return_url": "https://example.com",
        "trial_period_days": 10
      }'
      ```
    </CodeGroup>

    <CodeGroup>
      ```curl Checkout Session Curl example expandable theme={null}
      curl --request POST \
      --url https://example.com/api/checkout \
      --header 'Content-Type: application/json' \
      --header 'User-Agent: insomnia/11.2.0' \
      --cookie mode=test \
      --data '{
      "product_cart": [
        {
          "product_id": "pdt_QMDuvLkbVzCRWRQjLNcs",
          "quantity": 1
        }
      ],
      "customer": {
        "email": "test@example.com",
        "name": "test"
      },
      "return_url": "https://example.com/success"
      }'
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Customer Portal Handler">
    <Info>
      Usa questo handler per consentire ai clienti di gestire i propri abbonamenti e dettagli tramite il portale clienti di Dodo Payments.
    </Info>

    <CodeGroup>
      ```typescript Express Route Handler expandable theme={null}
      import { CustomerPortal } from "@dodopayments/express";

      app.get('/api/customer-portal', CustomerPortal({
          bearerToken: process.env.DODO_PAYMENTS_API_KEY,
          environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
      }))
      ```
    </CodeGroup>

    <CodeGroup>
      ```curl Customer Portal Curl example expandable theme={null}
      curl --request GET \
      --url 'https://example.com/api/customer-portal?customer_id=cus_9VuW4K7O3GHwasENg31m&send_email=true' \
      --header 'User-Agent: insomnia/11.2.0' \
      --cookie mode=test
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Webhook Handler">
    <Info>
      Usa questo handler per ricevere ed elaborare in modo sicuro gli eventi webhook di Dodo Payments nella tua app Express.
    </Info>

    <CodeGroup>
      ```typescript Express Route Handler expandable theme={null}
      import { Webhooks } from "@dodopayments/express";

      app.post('/api/webhook',Webhooks({
          webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
          onPayload: async (payload) => {
              // handle the payload
          },
          // ... other event handlers for granular control
      }))
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Gestore Route Checkout

<Info>
  Dodo Payments supporta tre tipi di flussi di pagamento per integrare i pagamenti nel tuo sito: questo adattatore supporta tutti i tipi di flussi di pagamento.
</Info>

* **Link di Pagamento Statici:** URL condivisibili istantaneamente per una rapida raccolta di pagamenti senza codice.
* **Link di Pagamento Dinamici:** Genera programmaticamente link di pagamento con dettagli personalizzati utilizzando l'API o gli SDK.
* **Sessioni di Checkout:** Crea esperienze di checkout sicure e personalizzabili con carrelli prodotti preconfigurati e dettagli del cliente.

<AccordionGroup>
  <Accordion title="Static Checkout (GET)">
    ### Parametri di query supportati

    <ParamField query="productId" type="string" required>
      Identificatore del prodotto (es. <code>?productId=pdt\_nZuwz45WAs64n3l07zpQR</code>).
    </ParamField>

    <ParamField query="quantity" type="integer">
      Quantità del prodotto.
    </ParamField>

    <ParamField query="fullName" type="string">
      Nome completo del cliente.
    </ParamField>

    <ParamField query="firstName" type="string">
      Nome del cliente.
    </ParamField>

    <ParamField query="lastName" type="string">
      Cognome del cliente.
    </ParamField>

    <ParamField query="email" type="string">
      Indirizzo email del cliente.
    </ParamField>

    <ParamField query="country" type="string">
      Paese del cliente.
    </ParamField>

    <ParamField query="addressLine" type="string">
      Linea d'indirizzo del cliente.
    </ParamField>

    <ParamField query="city" type="string">
      Città del cliente.
    </ParamField>

    <ParamField query="state" type="string">
      Stato/provincia del cliente.
    </ParamField>

    <ParamField query="zipCode" type="string">
      CAP/codice postale del cliente.
    </ParamField>

    <ParamField query="disableFullName" type="boolean">
      Disabilita il campo del nome completo.
    </ParamField>

    <ParamField query="disableFirstName" type="boolean">
      Disabilita il campo del nome.
    </ParamField>

    <ParamField query="disableLastName" type="boolean">
      Disabilita il campo del cognome.
    </ParamField>

    <ParamField query="disableEmail" type="boolean">
      Disabilita il campo dell'email.
    </ParamField>

    <ParamField query="disableCountry" type="boolean">
      Disabilita il campo del paese.
    </ParamField>

    <ParamField query="disableAddressLine" type="boolean">
      Disabilita il campo della linea d'indirizzo.
    </ParamField>

    <ParamField query="disableCity" type="boolean">
      Disabilita il campo della città.
    </ParamField>

    <ParamField query="disableState" type="boolean">
      Disabilita il campo dello stato.
    </ParamField>

    <ParamField query="disableZipCode" type="boolean">
      Disabilita il campo del CAP.
    </ParamField>

    <ParamField query="paymentCurrency" type="string">
      Specifica la valuta del pagamento (es. <code>USD</code>).
    </ParamField>

    <ParamField query="showCurrencySelector" type="boolean">
      Mostra il selettore della valuta.
    </ParamField>

    <ParamField query="paymentAmount" type="integer">
      Specifica l'importo del pagamento (es. <code>1000</code> per \$10.00).
    </ParamField>

    <ParamField query="showDiscounts" type="boolean">
      Mostra i campi per lo sconto.
    </ParamField>

    <ParamField query="metadata_*" type="string">
      Qualsiasi parametro di query che inizia con <code>metadata\_</code> verrà passato come metadata.
    </ParamField>

    <Warning>
      Se manca <code>productId</code>, l'handler restituisce una risposta 400. Anche parametri di query non validi generano una risposta 400.
    </Warning>

    ### Formato di Risposta

    Il checkout statico restituisce una risposta JSON con l'URL di checkout:

    ```json theme={null}
    {
      "checkout_url": "https://checkout.dodopayments.com/..."
    }
    ```
  </Accordion>

  <Accordion title="Dynamic Checkout (POST)">
    * Invia i parametri come corpo JSON in una richiesta POST.
    * Supporta sia pagamenti one-time che ricorrenti.
    * Per un elenco completo dei campi supportati nel corpo POST, consulta:
      * [Request body for a One Time Payment Product](https://docs.dodopayments.com/api-reference/payments/post-payments)
      * [Request body for a Subscription Product](https://docs.dodopayments.com/api-reference/subscriptions/post-subscriptions)

    ### Formato di Risposta

    Il checkout dinamico restituisce una risposta JSON con l'URL di checkout:

    ```json theme={null}
    {
      "checkout_url": "https://checkout.dodopayments.com/..."
    }
    ```
  </Accordion>

  <Accordion title="Checkout Sessions (POST)">
    Le sessioni di checkout offrono un'esperienza di checkout ospitata più sicura che gestisce l'intero flusso di pagamento sia per acquisti una tantum che per abbonamenti, con pieno controllo sulla personalizzazione.

    Fare riferimento alla [Guida all'integrazione delle sessioni di checkout](https://docs.dodopayments.com/developer-resources/checkout-session) per ulteriori dettagli e un elenco completo dei campi supportati.

    ### Formato di Risposta

    Le sessioni di checkout restituiscono una risposta JSON con l'URL di checkout:

    ```json theme={null}
    {
      "checkout_url": "https://checkout.dodopayments.com/session/..."
    }
    ```
  </Accordion>
</AccordionGroup>

## Gestore Route Portale Clienti

Il Gestore Route Portale Clienti ti consente di integrare senza problemi il portale clienti di Dodo Payments nella tua applicazione Express.

### Parametri di query

<ParamField query="customer_id" type="string" required>
  L'ID cliente per la sessione del portale (es. <code>?customer\_id=cus\_123</code>).
</ParamField>

<ParamField query="send_email" type="boolean">
  Se impostato su <code>true</code>, invia un'email al cliente con il link del portale.
</ParamField>

<Warning>
  Restituisce 400 se manca <code>customer\_id</code>.
</Warning>

## Gestore Route Webhook

* **Metodo:** Solo le richieste POST sono supportate. Altri metodi restituiscono 405.
* **Verifica della Firma:** Verifica la firma del webhook utilizzando <code>webhookKey</code>. Restituisce 401 se la verifica fallisce.
* **Validazione del Payload:** Validato con Zod. Restituisce 400 per payload non validi.
* **Gestione degli Errori:**
  * 401: Firma non valida
  * 400: Payload non valido
  * 500: Errore interno durante la verifica
* **Routing degli Eventi:** Chiama il gestore di eventi appropriato in base al tipo di payload.

### Handler di eventi webhook supportati

<CodeGroup>
  ```typescript Typescript expandable theme={null}
  onPayload?: (payload: WebhookPayload) => Promise<void>;
  onPaymentSucceeded?: (payload: WebhookPayload) => Promise<void>;
  onPaymentFailed?: (payload: WebhookPayload) => Promise<void>;
  onPaymentProcessing?: (payload: WebhookPayload) => Promise<void>;
  onPaymentCancelled?: (payload: WebhookPayload) => Promise<void>;
  onRefundSucceeded?: (payload: WebhookPayload) => Promise<void>;
  onRefundFailed?: (payload: WebhookPayload) => Promise<void>;
  onDisputeOpened?: (payload: WebhookPayload) => Promise<void>;
  onDisputeExpired?: (payload: WebhookPayload) => Promise<void>;
  onDisputeAccepted?: (payload: WebhookPayload) => Promise<void>;
  onDisputeCancelled?: (payload: WebhookPayload) => Promise<void>;
  onDisputeChallenged?: (payload: WebhookPayload) => Promise<void>;
  onDisputeWon?: (payload: WebhookPayload) => Promise<void>;
  onDisputeLost?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionActive?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionOnHold?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionRenewed?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionPlanChanged?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionCancelled?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionFailed?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionExpired?: (payload: WebhookPayload) => Promise<void>;
  onLicenseKeyCreated?: (payload: WebhookPayload) => Promise<void>;
  ```
</CodeGroup>

***

## Prompt per LLM

```
Sei un assistente esperto nello sviluppo di Express.js. Il tuo compito è guidare un utente nell'integrazione dell'adattatore @dodopayments/express nel loro progetto Express.js esistente.

L'adattatore @dodopayments/express fornisce gestori di route per le funzionalità di Checkout, Portale Clienti e Webhook di Dodo Payments, progettati per integrarsi direttamente in un'app Express.

Per prima cosa, installa il pacchetto necessario. Usa il gestore di pacchetti appropriato per il progetto dell'utente (npm, yarn o bun):

npm install @dodopayments/express

---

Ecco come dovresti strutturare la tua risposta:

1. Chiedi all'utente quali funzionalità desidera integrare.

"Quali parti dell'adattatore @dodopayments/express desideri integrare nel tuo progetto? Puoi scegliere una o più delle seguenti:

- Gestore Route Checkout (per gestire i checkout dei prodotti)
- Gestore Route Portale Clienti (per gestire abbonamenti/dettagli dei clienti)
- Gestore Route Webhook (per ricevere eventi webhook di Dodo Payments)
- Tutto (integra tutte e tre)"

---

2. In base alla selezione dell'utente, fornisci passaggi dettagliati per l'integrazione di ciascuna funzionalità scelta.

---

**Se è selezionato il Gestore Route Checkout:**

**Scopo**: Questo gestore gestisce diversi tipi di flussi di checkout. Tutti i tipi di checkout (statici, dinamici e sessioni) restituiscono risposte JSON con URL di checkout per la gestione programmatica.

**Integrazione**:
Crea route nella tua app Express per checkout statici (GET), dinamici (POST) e sessioni di checkout (POST).

import { checkoutHandler } from '@dodopayments/express';

app.get('/api/checkout', checkoutHandler({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
  environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
  type: "static"
}));

app.post('/api/checkout', checkoutHandler({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
  environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
  type: "dynamic"
}));

// Per sessioni di checkout
app.post('/api/checkout', checkoutHandler({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
  environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
  type: "session"
}));

Opzioni di Configurazione:

    bearerToken: La tua chiave API di Dodo Payments (si consiglia di memorizzarla nella variabile d'ambiente DODO_PAYMENTS_API_KEY).

    returnUrl (opzionale): URL per reindirizzare l'utente dopo un checkout riuscito.

    environment: "test_mode" o "live_mode"

    type: "static" (GET), "dynamic" (POST) o "session" (POST)

GET (checkout statico) si aspetta parametri di query:

    productId (obbligatorio)

    quantity, campi cliente (fullName, email, ecc.) e metadati (metadata_*) sono opzionali.

    Restituisce: {"checkout_url": "https://checkout.dodopayments.com/..."}

POST (checkout dinamico) si aspetta un corpo JSON con dettagli di pagamento (una tantum o abbonamento). Fai riferimento alla documentazione per lo schema completo del POST:

    Pagamenti una tantum: https://docs.dodopayments.com/api-reference/payments/post-payments

    Abbonamenti: https://docs.dodopayments.com/api-reference/subscriptions/post-subscriptions

    Restituisce: {"checkout_url": "https://checkout.dodopayments.com/..."}

POST (sessioni di checkout) - (Consigliato) Un'esperienza di checkout più personalizzabile. Restituisce JSON con checkout_url: I parametri vengono inviati come corpo JSON. Supporta sia pagamenti una tantum che ricorrenti. Restituisce: {"checkout_url": "https://checkout.dodopayments.com/session/..."}. Per un elenco completo dei campi supportati, fare riferimento a:

  Guida all'integrazione delle sessioni di checkout: https://docs.dodopayments.com/developer-resources/checkout-session

Se è selezionato il Gestore Route Portale Clienti:

Scopo: Questa route consente ai clienti di gestire i loro abbonamenti tramite il portale di Dodo Payments.

Integrazione:

import { CustomerPortal } from "@dodopayments/express";

app.get('/api/customer-portal', CustomerPortal({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
}));

Parametri di Query:

    customer_id (obbligatorio): ad es., ?customer_id=cus_123

    send_email (opzionale): se true, il cliente riceve via email il link del portale

Restituisce 400 se customer_id è mancante.

Se è selezionato il Gestore Route Webhook:

Scopo: Elabora gli eventi webhook in arrivo da Dodo Payments per attivare eventi nella tua app.

Integrazione:

import { Webhooks } from "@dodopayments/express";

app.post('/api/webhook', Webhooks({
  webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
  onPayload: async (payload) => {
    // Gestisci il payload generico
  },
  // Puoi anche fornire gestori specifici per ciascun tipo di evento qui sotto
}));

Caratteristiche:

    Solo il metodo POST è consentito — gli altri restituiscono 405

    La verifica della firma viene eseguita utilizzando webhookKey. Restituisce 401 se non valida.

    Validazione del payload basata su Zod. Restituisce 400 se lo schema non è valido.

    Tutti i gestori sono funzioni async.

Gestori di Eventi Webhook Supportati:

Puoi passare in qualsiasi dei seguenti gestori:

    onPayload

    onPaymentSucceeded

    onPaymentFailed

    onPaymentProcessing

    onPaymentCancelled

    onRefundSucceeded

    onRefundFailed

    onDisputeOpened, onDisputeExpired, onDisputeAccepted, onDisputeCancelled, onDisputeChallenged, onDisputeWon, onDisputeLost

    onSubscriptionActive, onSubscriptionOnHold, onSubscriptionRenewed, onSubscriptionPlanChanged, onSubscriptionCancelled, onSubscriptionFailed, onSubscriptionExpired

    onLicenseKeyCreated

Impostazione delle Variabili d'Ambiente:

Assicurati di definire queste variabili d'ambiente nel tuo progetto:

DODO_PAYMENTS_API_KEY=your-api-key
DODO_PAYMENTS_WEBHOOK_KEY=your-webhook-secret
DODO_PAYMENTS_ENVIRONMENT="test_mode" o "live_mode"
DODO_PAYMENTS_RETURN_URL=your-return-url

Usa questi all'interno del tuo codice come:

process.env.DODO_PAYMENTS_API_KEY
process.env.DODO_PAYMENTS_WEBHOOK_SECRET

Nota di Sicurezza: Non impegnare segreti nel controllo di versione. Usa file .env localmente e gestori di segreti negli ambienti di distribuzione (ad es., AWS, Vercel, Heroku, ecc.).

Usa questi all'interno del tuo codice come:

process.env.DODO_PAYMENTS_API_KEY
process.env.DODO_PAYMENTS_WEBHOOK_SECRET

Nota di Sicurezza: NON eseguire il commit dei segreti nel controllo versione. Usa i file .env localmente e i gestori di segreti negli ambienti di distribuzione (ad esempio, AWS, Vercel, Heroku, ecc.).
```