Vai al contenuto principale

Requisiti

Per integrare l’API Dodo Payments, avrai bisogno di:
  • Un account commerciante Dodo Payments
  • Credenziali API (chiave API e chiave segreta webhook) dal dashboard

Configurazione del Dashboard

  1. Naviga al Dashboard Dodo Payments
  2. Crea un prodotto (pagamento una tantum o abbonamento)
  3. Genera la tua chiave API:
    • Vai su Sviluppatore > API
    • Guida dettagliata
    • Copia la chiave API nell’ambiente denominato DODO_PAYMENTS_API_KEY
  4. Configura i webhook:
    • Vai su Sviluppatore > Webhook
    • Crea un URL webhook per le notifiche di pagamento
    • Copia la chiave segreta webhook nell’ambiente

Integrazione

Scegli il percorso di integrazione che si adatta al tuo caso d’uso:
  • Sessioni di checkout (raccomandato): Migliore per la maggior parte delle integrazioni. Crea una sessione sul tuo server e reindirizza i clienti a un checkout sicuro e ospitato.
  • Checkout Overlay (incorporato): Utilizza quando hai bisogno di un’esperienza in pagina che incorpora il checkout ospitato sul tuo sito.
  • Link di pagamento statici: URL condivisibili istantaneamente senza codice per una rapida raccolta di pagamenti.
  • Link di pagamento dinamici: Link creati programmaticamente. Tuttavia, le sessioni di checkout sono raccomandate e offrono maggiore flessibilità.

1. Sessioni di checkout

Utilizza le sessioni di checkout per creare un’esperienza di checkout sicura e ospitata per pagamenti una tantum o abbonamenti. Crei una sessione sul tuo server, quindi reindirizzi il cliente al checkout_url.
Le sessioni di checkout sono valide per 24 ore per impostazione predefinita. Se passi confirm=true, le sessioni sono valide per 15 minuti e tutti i campi richiesti devono essere forniti.
1

Crea una sessione di checkout

Scegli il tuo SDK preferito o chiama l’API REST.
import DodoPayments from 'dodopayments';

const client = new DodoPayments({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'test_mode', // defaults to 'live_mode'
});

const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'prod_123', quantity: 1 }],
  customer: { email: '[email protected]', name: 'John Doe' },
  return_url: 'https://yourapp.com/checkout/success',
});
2

Reindirizza il cliente al checkout

Dopo la creazione della sessione, reindirizza a checkout_url per avviare il flusso ospitato.
// Example in a browser context
window.location.href = session.checkout_url;
Preferisci le sessioni di checkout per il modo più veloce e affidabile per iniziare a ricevere pagamenti. Per personalizzazioni avanzate, consulta la guida completa sulle Sessioni di checkout e la Riferimento API.

2. Checkout Overlay

Per un’esperienza di checkout in pagina senza soluzione di continuità, esplora la nostra integrazione Checkout Overlay che consente ai clienti di completare i pagamenti senza lasciare il tuo sito web. I link di pagamento statici ti consentono di accettare rapidamente pagamenti condividendo un semplice URL. Puoi personalizzare l’esperienza di checkout passando parametri di query per precompilare i dettagli del cliente, controllare i campi del modulo e aggiungere metadati personalizzati.
1

Costruisci il tuo link di pagamento

Inizia con l’URL di base e aggiungi il tuo ID prodotto:
https://checkout.dodopayments.com/buy/{productid}
2

Aggiungi parametri core

Includi parametri di query essenziali:
  • quantity
    integer
    predefinito:"1"
    Numero di articoli da acquistare.
  • redirect_url
    string
    obbligatorio
    URL a cui reindirizzare dopo il completamento del pagamento.
L’URL di reindirizzamento includerà i dettagli del pagamento come parametri di query, ad esempio:
https://example.com/?payment_id=pay_ts2ySpzg07phGeBZqePbH&status=succeeded
3

Precompila le informazioni del cliente (opzionale)

Aggiungi campi cliente o di fatturazione come parametri di query per semplificare il checkout.
  • fullName
    string
    Nome completo del cliente (ignorato se sono forniti firstName o lastName).
  • firstName
    string
    Nome del cliente.
  • lastName
    string
    Cognome del cliente.
  • email
    string
    Indirizzo email del cliente.
  • country
    string
    Paese del cliente.
  • addressLine
    string
    Indirizzo.
  • city
    string
    Città.
  • state
    string
    Stato o provincia.
  • zipCode
    string
    Codice postale.
  • showDiscounts
    boolean
    true o false
4

Controlla i campi del modulo (opzionale)

Puoi disabilitare campi specifici per renderli di sola lettura per il cliente. Questo è utile quando hai già i dettagli del cliente (ad esempio, utenti con accesso).
Per disabilitare un campo, fornisci il suo valore e imposta il corrispondente flag disable… su true:
&[email protected]&disableEmail=true
CampoFlag di disabilitazioneParametro richiesto
Nome completodisableFullNamefullName
NomedisableFirstNamefirstName
CognomedisableLastNamelastName
EmaildisableEmailemail
PaesedisableCountrycountry
IndirizzodisableAddressLineaddressLine
CittàdisableCitycity
StatodisableStatestate
Codice postaledisableZipCodezipCode
Disabilitare i campi aiuta a prevenire modifiche accidentali e garantisce la coerenza dei dati.
Impostare showDiscounts=false disabiliterà e nasconderà la sezione sconti nel modulo di checkout. Utilizza questo se vuoi impedire ai clienti di inserire codici coupon o promozionali durante il checkout.
5

Aggiungi controlli avanzati (opzionale)

  • paymentCurrency
    string
    Specifica la valuta di pagamento. Per impostazione predefinita, è la valuta del paese di fatturazione.
  • showCurrencySelector
    boolean
    predefinito:"true"
    Mostra o nascondi il selettore di valuta.
  • paymentAmount
    integer
    Importo in centesimi (solo per prezzi Pay What You Want).
  • metadata_*
    string
    Campi di metadati personalizzati (ad esempio, metadata_orderId=123).
6

Condividi il link

Invia il link di pagamento completato al tuo cliente. Quando lo visitano, tutti i parametri di query vengono raccolti e memorizzati con un ID di sessione. L’URL viene quindi semplificato per includere solo il parametro di sessione (ad esempio, ?session=sess_1a2b3c4d). Le informazioni memorizzate persistono attraverso i refresh della pagina e sono accessibili durante l’intero processo di checkout.
L’esperienza di checkout del cliente è ora semplificata e personalizzata in base ai tuoi parametri.
Preferisci le sessioni di checkout per la maggior parte dei casi d’uso, offrono maggiore flessibilità e controllo.
Creati tramite chiamata API o il nostro SDK con i dettagli del cliente. Ecco un esempio: Ci sono due API per creare link di pagamento dinamici: La guida seguente è per la creazione di link di pagamento una tantum. Per istruzioni dettagliate sull’integrazione degli abbonamenti, consulta questa Guida all’integrazione degli abbonamenti.
Assicurati di passare payment_link = true per ottenere il link di pagamento
import DodoPayments from 'dodopayments';

const client = new DodoPayments({
bearerToken: process.env['DODO_PAYMENTS_API_KEY'], // This is the default and can be omitted
environment: 'test_mode', // defaults to 'live_mode'
});

async function main() {
const payment = await client.payments.create({
payment_link: true,
billing: { city: 'city', country: 'AF', state: 'state', street: 'street', zipcode: 0 },
customer: { email: '[email protected]', name: 'name' },
product_cart: [{ product_id: 'product_id', quantity: 0 }],
});

console.log(payment.payment_id);
}

main();
Dopo aver creato il link di pagamento, reindirizza i tuoi clienti per completare il pagamento.

Implementazione dei Webhook

Imposta un endpoint API per ricevere notifiche di pagamento. Ecco un esempio utilizzando Next.js:
import { Webhook } from "standardwebhooks";
import { headers } from "next/headers";
import { WebhookPayload } from "@/types/api-types";

const webhook = new Webhook(process.env.DODO_WEBHOOK_KEY!); // Replace with your secret key generated from the Dodo Payments Dashboard

export async function POST(request: Request) {
  const headersList = headers();
  const rawBody = await request.text();

  const webhookHeaders = {
    "webhook-id": headersList.get("webhook-id") || "",
    "webhook-signature": headersList.get("webhook-signature") || "",
    "webhook-timestamp": headersList.get("webhook-timestamp") || "",
  };

  await webhook.verify(rawBody, webhookHeaders);
  const payload = JSON.parse(rawBody) as WebhookPayload;
  
  // Process the payload according to your business logic
}
La nostra implementazione dei webhook segue la specifica Standard Webhooks. Per le definizioni dei tipi di webhook, consulta la nostra Guida agli eventi webhook. Puoi fare riferimento a questo progetto con implementazione demo su GitHub utilizzando Next.js e TypeScript. Puoi controllare l’implementazione live qui.