Express Adaptor

Checkout Handler

Integra il checkout di Dodo Payments nella tua app Express.

Customer Portal

Consenti ai clienti di gestire abbonamenti e dettagli.

Webhooks

Ricevi ed elabora in modo sicuro gli eventi webhook di Dodo Payments.

Installazione

Install the package

Esegui il seguente comando nella root del tuo progetto:

npm install @dodopayments/express

Set up environment variables

Crea un file .env nella root del tuo progetto:

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

Non eseguire mai il commit del tuo file .env o dei segreti nel controllo versione.

Esempi di Gestore Route

Checkout Handler
Customer Portal Handler
Webhook Handler

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).

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"
}))

curl --request GET \
--url 'https://example.com/api/checkout?productId=pdt_fqJhl7pxKWiLhwQR042rh' \
--header 'User-Agent: insomnia/11.2.0' \
--cookie mode=test

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
}'

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"
}'

Usa questo handler per consentire ai clienti di gestire i propri abbonamenti e dettagli tramite il portale clienti di Dodo Payments.

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

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

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

Usa questo handler per ricevere ed elaborare in modo sicuro gli eventi webhook di Dodo Payments nella tua app Express.

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
}))

Gestore Route Checkout

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.

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.

Static Checkout (GET)

Parametri di query supportati

string

obbligatorio

Identificatore del prodotto (es. ?productId=pdt_nZuwz45WAs64n3l07zpQR).

integer

Quantità del prodotto.

string

Nome completo del cliente.

string

Nome del cliente.

string

Cognome del cliente.

string

Indirizzo email del cliente.

string

Paese del cliente.

string

Linea d’indirizzo del cliente.

string

Città del cliente.

string

Stato/provincia del cliente.

string

CAP/codice postale del cliente.

boolean

Disabilita il campo del nome completo.

boolean

Disabilita il campo del nome.

boolean

Disabilita il campo del cognome.

boolean

Disabilita il campo dell’email.

boolean

Disabilita il campo del paese.

boolean

Disabilita il campo della linea d’indirizzo.

boolean

Disabilita il campo della città.

boolean

Disabilita il campo dello stato.

boolean

Disabilita il campo del CAP.

string

Specifica la valuta del pagamento (es. USD).

boolean

Mostra il selettore della valuta.

integer

Specifica l’importo del pagamento (es. 1000 per $10.00).

boolean

Mostra i campi per lo sconto.

string

Qualsiasi parametro di query che inizia con metadata_ verrà passato come metadata.

Se manca productId, l’handler restituisce una risposta 400. Anche parametri di query non validi generano una risposta 400.

Formato di Risposta

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

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

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
- Request body for a Subscription Product

Formato di Risposta

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

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

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 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:

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

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

string

obbligatorio

L’ID cliente per la sessione del portale (es. ?customer_id=cus_123).

boolean

Se impostato su true, invia un’email al cliente con il link del portale.

Restituisce 400 se manca customer_id.

Gestore Route Webhook

Metodo: Solo le richieste POST sono supportate. Altri metodi restituiscono 405.
Verifica della Firma: Verifica la firma del webhook utilizzando webhookKey. 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

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>;

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.).

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Checkout Handler

Customer Portal

Webhooks

Installazione

Esempi di Gestore Route

Gestore Route Checkout

Parametri di query supportati

Formato di Risposta

Formato di Risposta

Formato di Risposta

Gestore Route Portale Clienti

Parametri di query

Gestore Route Webhook

Handler di eventi webhook supportati

Prompt per LLM

Checkout Handler

Customer Portal

Webhooks

​Installazione

​Esempi di Gestore Route

​Gestore Route Checkout

​Parametri di query supportati

​Formato di Risposta

​Formato di Risposta

​Formato di Risposta

​Gestore Route Portale Clienti

​Parametri di query

​Gestore Route Webhook

​Handler di eventi webhook supportati

​Prompt per LLM

Installazione

Esempi di Gestore Route

Gestore Route Checkout

Parametri di query supportati

Formato di Risposta

Formato di Risposta

Formato di Risposta

Gestore Route Portale Clienti

Parametri di query

Gestore Route Webhook

Handler di eventi webhook supportati

Prompt per LLM