Checkout Sessions
Payment Links
Webhooks
API Reference
Prerequisiti
Prima di iniziare, ti servono:- Un account Dodo Payments.
- Almeno un prodotto. Crealo nella sezione Products della dashboard. Un prodotto in abbonamento con un prezzo diverso da zero deve rispettare il minimo per gli abbonamenti per la valuta utilizzata dal cliente: $1.00 per USD. Le valute diverse da USD, EUR e GBP devono inoltre avere un valore di almeno $1.00. Sono supportati anche gli abbonamenti da $0.
- Una chiave API. Creala nella sezione Developer → API Keys e salvala nella variabile d’ambiente
DODO_PAYMENTS_API_KEY. Crea la chiave in modalità test durante lo sviluppo: gli esempi in questa pagina usano la modalità test e una chiave in modalità test funziona solo con la modalità test. Consulta Authentication. - L’SDK per il tuo linguaggio. L’SDK Node.js richiede Node.js 20 o versioni successive, l’SDK Python richiede Python 3.9 o versioni successive e l’SDK Go richiede Go 1.22 o versioni successive. Gli esempi cURL non richiedono alcun SDK.
standardwebhooks. Installalo con npm install standardwebhooks.
Scegli un percorso di integrazione
Il checkout in overlay e quello inline funzionano solo in una pagina web. In un’app mobile nativa, crea la sessione Checkout sul tuo server e apri il relativo
checkout_url con un SDK Checkout per dispositivi mobili.
Per fare in modo che un coding agent crei questa integrazione per te, installa il Plugin per agent.
Sessioni Checkout
Crea un’esperienza di checkout sicura e ospitata. Crea una sessione sul tuo server, quindi reindirizza il cliente all’checkout_url restituito.
Crea una sessione Checkout
- Node.js SDK
- Python SDK
- cURL
Reindirizza al Checkout
Dopo aver creato una sessione, reindirizza il cliente all’checkout_url:
Gestisci gli errori
Quando una richiesta non va a buon fine, l’API restituisce un codice di stato HTTP e un corpo JSON con uncode e un message. Basa la gestione degli errori su code, non su message. Per ogni codice, la relativa causa e come risolverlo, consulta Codici di errore. Un pagamento non riuscito viene segnalato separatamente: il relativo status è failed, il relativo error_code indica il motivo e ricevi un payment.failed webhook. Per decidere se riprovare, consulta Gestisci i pagamenti non riusciti.
Link di pagamento
Un link di pagamento è un URL che apre il checkout per un prodotto, così puoi riscuotere pagamenti senza scrivere codice. I parametri di query precompilano i dati del cliente e controllano il modulo di checkout. Quando un cliente apre il link, il checkout salva i parametri in una sessione e accorcia l’URL in un parametrosession, così vengono mantenuti anche dopo un aggiornamento della pagina.
Link di pagamento statici
Un link di pagamento statico è un URL che crei una volta e condividi più volte. L’URL di base è:integer
predefinito:"1"
Numero di articoli da acquistare.
string
obbligatorio
I link di pagamento usano
redirect_url. L’API Checkout Sessions usa return_url allo stesso scopo.URL a cui reindirizzare dopo il pagamento. Dodo Payments aggiunge i dettagli del pagamento come parametri di query, ad esempio https://example.com/?payment_id=pay_ts2ySpzg07phGeBZqePbH&status=succeeded&email=customer%40example.com. Se il prodotto emette chiavi di licenza, viene aggiunto anche un parametro license_key, con più chiavi separate da virgole.string
Specifica la valuta del pagamento. Per impostazione predefinita usa la valuta del paese di fatturazione.
boolean
predefinito:"true"
Mostra o nasconde il selettore della valuta.
boolean
predefinito:"true"
Mostra o nasconde la sezione degli sconti. Imposta su
false per impedire ai clienti di inserire codici coupon.number
Fissa l’importo addebitato, nelle unità principali della valuta, ad esempio
12.5 per $12.50. Funziona solo con i prodotti Pay What You Want e viene ignorato se è inferiore al prezzo minimo del prodotto.string
Campi di metadati personalizzati, ad esempio
metadata_orderId=123.Precompila le informazioni del cliente
Aggiungi i campi del cliente come parametri di query per velocizzare il checkout:string
Nome completo del cliente (ignorato se vengono forniti firstName o lastName).
string
Nome del cliente.
string
Cognome del cliente.
string
Indirizzo email del cliente.
string
Paese del cliente (codice ISO 3166-1 alpha-2).
string
Indirizzo.
string
Città.
string
Stato o provincia.
string
Codice postale o ZIP.
Disabilita i campi del modulo
Per impedire ai clienti di modificare le informazioni precompilate, disabilita un campo fornendo il relativo valore e impostando il flagdisable... corrispondente su true:
Esempio di link di pagamento statico
Link di pagamento dinamici (deprecati)
Per le integrazioni esistenti che usano link di pagamento dinamici, passapayment_link: true a Crea pagamento una tantum o Crea abbonamento per creare un link. Gli esempi seguenti creano un link di pagamento una tantum. Per gli abbonamenti, consulta la Guida all’integrazione degli abbonamenti.
- Node.js SDK
- Python SDK
- Go SDK
Webhook
I webhook informano il tuo server quando un pagamento va a buon fine o non va a buon fine, così puoi evadere l’ordine.Crea un endpoint webhook
Vai a Developer → Webhooks nella dashboard e aggiungi l’URL del tuo endpoint. Copia il secret di firma dell’endpoint nella variabile d’ambienteDODO_PAYMENTS_WEBHOOK_KEY.
Ecco un esempio con Next.js:
app/api/webhooks/dodo/route.ts
Eventi da ascoltare
Come minimo, ascolta questi eventi in un flusso di pagamento una tantum:
Se vendi prodotti con chiavi di licenza, gestisci anche
license_key.created. Per l’elenco completo degli eventi, inclusi quelli relativi ad abbonamenti, entitlement, crediti, recupero e solleciti di pagamento, consulta la Guida agli eventi webhook.
Per un esempio completo con Next.js e TypeScript, consulta il repository demo e il relativo deployment live.
Valuta e indirizzo di fatturazione
Per addebitare una valuta specifica, passabilling_currency e billing_address.country quando crei la sessione Checkout. Se li ometti, Adaptive Currency sceglie la valuta e il paese dall’indirizzo IP del cliente, che potrebbe non corrispondere alla valuta che intendi addebitare.
Gli importi Pay What You Want sono espressi nella valuta di base del prodotto, che deve essere USD, GBP o EUR. Per riscuotere un importo fisso in un’altra valuta, usa Adaptive Currency, che converte il prezzo di base ai tassi di cambio correnti, oppure Prezzi localizzati, che imposta un prezzo fisso per valuta. I Prezzi localizzati non funzionano con Pay What You Want.
Acquisto ripetuto con un clic
Per addebitare un cliente di ritorno con un metodo di pagamento salvato, passa il relativopayment_method_id insieme a confirm: true. payment_method_id è accettato solo quando confirm è true e devi inoltre passare l’customer_id del cliente esistente. Poiché confirm è true, devi passare anche un billing_address completo oppure solo country e zipcode quando minimal_address è true. La sessione addebita direttamente il metodo di pagamento salvato, quindi non restituisce alcun checkout_url. Usa i webhook per sapere se il pagamento è andato a buon fine.