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:
  • Checkout Sessions (raccomandato): Migliore per la maggior parte delle integrazioni. Crea una sessione sul tuo server e reindirizza i clienti a un checkout sicuro e ospitato.
  • Overlay Checkout: Utilizza quando hai bisogno di un’esperienza in-page che apre il checkout come un overlay modale sul tuo sito.
  • Inline Checkout: Integra direttamente il checkout nel layout della tua pagina per esperienze di checkout completamente integrate e brandizzate.
  • Static Payment Links: URL condivisibili istantaneamente senza codice per una rapida raccolta dei pagamenti.
  • Dynamic Payment Links: Link creati programmaticamente. Tuttavia, le Checkout Sessions 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.

3. Inline Checkout

Per esperienze di checkout completamente integrate incorporate direttamente nella tua pagina, utilizza la nostra integrazione Inline Checkout. Questo ti consente di costruire riepiloghi degli ordini personalizzati e avere il controllo completo sul layout del checkout mentre Dodo Payments gestisce in modo sicuro la raccolta dei pagamenti. 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 fornito firstName o lastName).
  • firstName
    string
    Nome di battesimo 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/CAP.
  • 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 disable… flag 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. Di default è 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 tutto il processo di checkout.
L’esperienza di checkout del cliente è ora semplificata e personalizzata in base ai tuoi parametri.
Preferisci le Checkout Sessions 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 qui sotto è per la creazione di link di pagamento una tantum. Per istruzioni dettagliate sull’integrazione degli abbonamenti, fai riferimento a 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, fai riferimento alla 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.