Quick Start
API Reference
Preview Endpoint
Session Validity: Checkout sessions expire after 24 hours by default, or 15 minutes when
confirm: true.Prerequisites
You need:- An active Dodo Payments merchant account
- API credentials from Developer → API Keys in the dashboard
- At least one product created in Products
Creating Your First Checkout Session
- Node.js SDK
- Python SDK
- REST API
API Response
All methods return:session_id is guaranteed to be present. When payment_method_id is provided, the charge processes immediately and checkout_url is null. Use the returned payment_id instead.
When confirm: true, the payment is created at session-creation time, and the response also includes payment_id, client_secret, and publishable_key for use with the Dodo Payments checkout SDK.
Redirect Your Customer
1
Extract the checkout URL
Get
checkout_url from the API response.2
Redirect to checkout
Send your customer to the URL:Alternatively, open in a new window:
3
Handle the return
After payment, customers are redirected to your
return_url with query parameters:Example redirect:
Check Session Status
To check a session’s status, call Get Checkout Session (GET /checkouts/{id}). The response has the session id, created_at, customer_email, and customer_name, plus payment_id and payment_status. Both payment fields are null while the customer is still entering details. After the customer submits payment, payment_status holds the payment’s status, such as succeeded, failed, or processing. Use webhooks as the source of truth for fulfillment.
Request Body
Required Fields
array
requis
Array of products to include in the checkout session. Each product must have a valid
product_id from your dashboard.Vous pouvez combiner des produits de paiement ponctuel avec un produit d’abonnement dans la même session. Un panier peut également contenir deux produits d’abonnement ou plus, mais il ne peut alors pas contenir de produits ponctuels. Consultez Panier multi-abonnement. Un panier contient au maximum 20 produits.Optional Fields
Customer Information
Customer Information
object
Customer information. You can either attach an existing customer using their ID or create a new customer record during checkout.
- Attach Existing Customer
- Create New Customer
object
Billing address information for accurate tax calculation, fraud prevention, and regulatory compliance.Lorsque
confirm: true, tous les champs d’adresse de facturation deviennent obligatoires, sauf si minimal_address est true.Payment Configuration
Payment Configuration
array
Control which payment methods are available to customers during checkout. This helps optimize for specific markets or business requirements.Common options:
credit, debit, upi_collect, apple_pay, google_pay, amazon_pay, klarna, affirm, afterpay_clearpay, cashapp, ach, multibanco, bancontact_card, eps, ideal, blik, gcash, ali_pay_hk, fps, touch_n_go, paypalSee the Create Checkout Session API reference for the complete list.Example:string
Override the default currency selection with a fixed billing currency. Uses ISO 4217 currency codes.Supported Currencies:
USD, EUR, GBP, CAD, AUD, INR, and moreExample: "USD" for US Dollars, "EUR" for EurosCe champ n’est pris en compte que lorsque la tarification adaptative est activée. Si la tarification adaptative est désactivée, l’API ignore ce champ et la devise provient du prix du produit ou du pays de facturation.boolean
défaut:"false"
Display previously saved payment methods for returning customers, improving checkout speed and user experience.
Session Management
Session Management
string
URL to redirect customers after payment completion. Dodo Payments appends query parameters to your URL on redirect (see the redirect table above).Example redirect URLs:Use the
license_key and email query parameters to display license keys or send a confirmation immediately on your return page, without needing an extra API call.string
URL to redirect customers when they click the back button or cancel the checkout session. If not provided, the back button will not be displayed.Set a
cancel_url to give customers a clear way to return to your site without completing the purchase.boolean
défaut:"false"
If true, finalizes all session details immediately. The API throws an error if required data is missing.Lorsque
confirm: true :- Tous les champs d’adresse de facturation deviennent obligatoires (uniquement
countryetzipcodelorsqueminimal_addressesttrue) payment_method_idpeut être fourni pour traiter immédiatement le paiement- La session expire après 15 minutes au lieu de 24 heures
- Un
customer_idexistant est requis sipayment_method_idest fourni
array
Apply one or more stacked discount codes to the checkout session. Codes are applied in array order (the first code reduces the starting price, the second reduces the already-discounted price, and so on), up to a maximum of 20 codes per session.When Purchasing Power Parity is enabled, the starting price is the PPP-adjusted amount, not the base price.The singular
discount_code field below is deprecated but still fully supported. It cannot be combined with discount_codes in the same request.string
obsolète
Deprecated — prefer
discount_codes for new integrations. This field still works for backward compatibility, but cannot be combined with discount_codes in the same request.object
Custom key-value pairs to store additional information about the session.
boolean
Override merchant default 3DS behaviour for this session.
boolean
défaut:"false"
Enable minimal address collection mode. When enabled, the checkout only collects:
- Country: Always required for tax determination
- ZIP/Postal code: Only in regions where it’s necessary for sales tax, VAT, or GST calculation
confirm: true, seul zipcode (ainsi que country) est obligatoire ; les autres champs d’adresse de facturation restent facultatifs.string
Un moyen de paiement enregistré appartenant au client associé. Nécessite
confirm: true et un customer.customer_id existant. L’éligibilité du moyen de paiement est validée avec la devise du paiement. Lorsqu’il est défini, le paiement est traité immédiatement et checkout_url est renvoyé en tant que null. Utilisez plutôt le payment_id renvoyé.boolean
défaut:"false"
Si cette valeur est vraie, renvoie une URL de paiement raccourcie au lieu de l’URL complète de la session.
string
ID de collection de produits pour le parcours de paiement basé sur une collection. Lorsque vous le définissez, transmettez un tableau
product_cart vide. Les codes de réduction ne peuvent pas être appliqués à l’avance lors de la création de la session. Consultez Collections de produits.string
Identifiant fiscal du client (par exemple, un numéro de TVA). Nécessite
billing_address avec un country.string
Nom commercial ou nom légal facultatif associé à l’identifiant fiscal, limité à 250 caractères. Lorsqu’il est fourni avec un
tax_id valide, il apparaît sur la facture à la place du nom personnel du client.integer
Remplace le seuil minimal de mandat défini au niveau du marchand (en paises INR) pour les e-mandats INR sur les cartes indiennes.Le montant du mandat envoyé au processeur est
max(this_floor, actual_billing_amount) ; il s’agit donc effectivement du plafond d’autorisation visible par le client lorsque la facturation est inférieure. Si cette valeur n’est pas définie, le paramètre du marchand s’applique ; s’il ne l’est pas non plus, la valeur par défaut du système, ₹15,000, s’applique.UI Customization
UI Customization
object
Personnalisez l’apparence et le comportement de l’interface de paiement.
Feature Flags
Feature Flags
object
Configurez des fonctionnalités et des comportements spécifiques pour la session de paiement.
Custom Fields
Custom Fields
array
Collectez des informations supplémentaires auprès des clients lors du paiement au moyen de champs de formulaire personnalisés. Vous pouvez définir jusqu’à 5 champs personnalisés par session de paiement. Les réponses des clients sont incluses dans les charges utiles des webhooks et disponibles via l’API.
- Webhooks :
payment.succeeded,subscription.activeet les autres charges utiles d’événements pertinentes contiennent le tableaucustom_field_responses - Réponses de l’API : les objets de paiement et d’abonnement incluent
custom_field_responses
Subscription Configuration
Subscription Configuration
object
Configuration supplémentaire pour les sessions de paiement contenant des produits d’abonnement.
Exemples d’utilisation
Paiement simple pour un seul produit
Panier multi-produit
Panier multi-abonnement
Pour vendre plusieurs produits d’abonnement lors d’un même paiement, ajoutez au moins deux produits d’abonnement àproduct_cart. Le client paie une seule fois, et Dodo Payments crée un paiement, une facture et un abonnement pour chaque produit. Chaque abonnement possède son propre cycle de facturation et se renouvelle séparément ; un produit mensuel et un produit annuel peuvent donc partager un panier.
- Il ne peut pas contenir de produits ponctuels. L’API rejette la requête avec un
422. - Il contient au maximum 20 produits d’abonnement.
- Il ne peut pas répertorier deux fois le même produit. Pour vendre plusieurs unités d’un produit, définissez plutôt
quantity. - Il ne peut pas utiliser la facturation à la demande (
subscription_data.on_demand). - Un code de réduction appliqué au panier compte comme une utilisation.
subscription_data.trial_period_days s’applique à chaque abonnement du panier. Sans cette valeur, chaque abonnement utilise l’essai défini sur son propre produit. Si vous ne la définissez pas et que Empêcher l’utilisation abusive des essais est activé, un produit déjà essayé par le client démarre sans période d’essai.
Le paiement obtenu possède is_multi_subscription: true et répertorie chaque abonnement qu’il démarre dans subscription_ids. Sa valeur subscription_id est null, car aucun abonnement unique ne possède le paiement. Le webhook payment.succeeded contient les mêmes champs. Consultez is_multi_subscription pour connaître le type de paiement, et non la longueur de subscription_ids.
Une fois le paiement réussi, vous recevez un événement payment.succeeded pour le panier et un événement subscription.active pour chaque abonnement. Ensuite, chaque abonnement se renouvelle, change de plan et est annulé indépendamment, avec sa propre facture pour chaque renouvellement.
Tous les abonnements d’un même panier partagent le moyen de paiement utilisé par le client lors du paiement. Lorsque vous mettez à jour le moyen de paiement de l’un d’eux, Dodo Payments transfère le nouveau moyen de paiement à chaque abonnement du même panier qui possède la même devise de règlement et la même devise de facturation et qui est active, on_hold, past_due ou paused. Chaque abonnement d’un panier commence avec la même devise de règlement et la même devise de facturation, même lorsque les produits ont des devises de prix différentes. Une modification ultérieure, telle qu’un changement de plan, peut déplacer un abonnement vers une autre devise de règlement ou de facturation. Cet abonnement conserve son ancien moyen de paiement ; mettez-le donc à jour séparément. Pour un abonnement on_hold, la mise à jour réessaie uniquement la facture impayée de cet abonnement.
Abonnement avec période d’essai
Paiement préconfirmé
Paiement avec remplacement de devise
Moyens de paiement enregistrés pour les clients existants
Paiement B2B avec collecte de l’identifiant fiscal
Paiement avec thème sombre et codes de réduction empilés
Moyens de paiement régionaux (UPI pour l’Inde)
Pour obtenir des informations détaillées sur la configuration et les tests UPI, consultez la page Moyens de paiement en Inde.Paiement BNPL (Buy Now Pay Later)
Pour obtenir des informations détaillées sur la configuration et les tests BNPL, consultez la page Buy Now Pay Later (BNPL).Paiement instantané avec un moyen de paiement existant
Liens courts pour des URL de paiement plus lisibles
Ignorer la page de confirmation de paiement et rediriger immédiatement
Forcer une langue
Collecter des champs personnalisés
Prévisualiser les sessions de paiement
Utilisez l’endpoint Preview Checkout Session pour calculer les prix, les taxes et les totaux avant de créer une session. Cela est utile pour afficher des informations tarifaires précises sur votre site.Le
current_breakup.subtotal prévisualisé tient déjà compte de la parité de pouvoir d’achat et de la tarification psychologique lorsqu’elles s’appliquent au produit.Lorsque le panier contient un produit d’abonnement, la réponse de prévisualisation renvoie également un
next_billing_date — un aperçu de la prochaine date de facturation, que vous pouvez afficher avant la création de l’abonnement. Il est calculé par rapport à maintenant : now + trial period lorsqu’un essai s’applique, sinon now + one payment frequency. Le champ est omis pour les paniers composés uniquement de produits ponctuels. Il s’agit d’une estimation basée sur l’heure de la prévisualisation ; le next_billing_date faisant foi est défini lors de l’activation de l’abonnement.La prévisualisation renvoie également
trial_period_days (la durée effective de l’essai, gratuit ou payant) et trial_amount (les frais d’essai par unité après réduction, dans les unités mineures de la devise du prix). trial_amount est présent uniquement pour un essai payant et vaut null pour un essai gratuit ou en l’absence d’essai. Utilisez current_breakup pour connaître le montant total taxé effectivement dû aujourd’hui.Pour un panier multi-abonnement, la réponse renvoie également un tableau
subscriptions contenant une entrée par abonnement : product_id, amount_due_now, tax_due_now, recurring_amount, recurring_tax, trial_period_days et next_billing_date. Le next_billing_date de niveau supérieur correspond à la date la plus proche dans le panier, tandis que trial_period_days et trial_amount de niveau supérieur valent null. Lisez les montants dans subscriptions et current_breakup. recurring_breakup additionne les montants de renouvellement de chaque abonnement, même lorsque leurs dates de renouvellement diffèrent ; lisez donc chaque renouvellement dans subscriptions.- Node.js SDK
- Python SDK
- REST API
Migrer depuis Dynamic Links
Si vous utilisez Dynamic Links, les Checkout Sessions offrent davantage de flexibilité. Avec Dynamic Links, vous deviez fournir l’adresse de facturation complète du client. Avec les Checkout Sessions, vous pouvez transmettre les informations dont vous disposez et le parcours de paiement collecte le reste. Par exemple :- Fournissez uniquement le pays de facturation du client ; le paiement collecte les informations restantes.
- Ou fournissez toutes les informations et définissez
confirm: truepour accéder directement à la page de paiement.