Skip to main content

Quick Start

Create your first checkout session in under 5 minutes

API Reference

Full API documentation and interactive testing

Preview Endpoint

Calculate pricing and taxes before creating a session
Session Validity: Checkout sessions expire after 24 hours by default, or 15 minutes when confirm: true.
Single-Use Links: The checkout_url is not reusable. Generate a fresh session for each customer and payment attempt rather than sharing or reusing a link.

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

API Response

All methods return:
Only 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:
Instead of redirecting, you can embed checkout directly in your page using Overlay Checkout (modal), Inline Checkout (embedded), or Mobile SDKs (native apps). All consume the same session URL.

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.
Find Your Product IDs: You can find product IDs in your Dodo Payments dashboard under Products → View Details, or by using the List Products API.

Optional Fields

object
Customer information. You can either attach an existing customer using their ID or create a new customer record during checkout.
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.
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.
Always include credit and debit as fallback options to prevent checkout failures when preferred payment methods are unavailable.
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.
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 country et zipcode lorsque minimal_address est true)
  • payment_method_id peut être fourni pour traiter immédiatement le paiement
  • La session expire après 15 minutes au lieu de 24 heures
  • Un customer_id existant est requis si payment_method_id est 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
Cela réduit considérablement les frictions lors du paiement en éliminant les champs de formulaire inutiles.Avec 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é.
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.
object
Personnalisez l’apparence et le comportement de l’interface de paiement.
object
Configurez des fonctionnalités et des comportements spécifiques pour la session de paiement.
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.
Les réponses des clients aux champs personnalisés sont incluses dans :
  • Webhooks : payment.succeeded, subscription.active et les autres charges utiles d’événements pertinentes contiennent le tableau custom_field_responses
  • Réponses de l’API : les objets de paiement et d’abonnement incluent custom_field_responses
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.
Un panier multi-abonnement est soumis aux limites suivantes :
  • 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.
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: true pour accéder directement à la page de paiement.
La migration est simple : mettez à jour votre intégration pour utiliser la méthode API ou SDK Checkout Sessions, adaptez la charge utile de la requête au format Checkout Sessions, et le tour est joué. Aucun traitement supplémentaire n’est nécessaire.

Ressources associées

Overlay Checkout

Ouvrir le paiement sous forme de fenêtre modale superposée à votre page

Inline Checkout

Intégrer directement le paiement à votre page

Mobile Integration

Intégrer le paiement dans des applications mobiles natives

Webhooks

Écouter les événements de paiement et d’abonnement

Payment Methods

Moyens de paiement pris en charge par région

Subscriptions

Facturation récurrente et gestion des abonnements
Dernière modification le 8 octobre 2026