Checkout Sessions

Quick Start Guide

Get your first checkout session running in under 5 minutes

API Reference & Live Testing

Explore the full API documentation and interactively test Checkout Session requests and responses.

Preview Checkout

Calculate pricing, taxes, and totals before creating a session.

Session Validity: Checkout sessions are valid for 24 hours by default. If you pass confirm=true in your request, the session will only be valid for 15 minutes.

Liens à usage unique : le checkout_url renvoyé par l’API n’est pas réutilisable et expire dans les 24 heures (ou après 15 minutes lorsque confirm=true). Il est destiné à un seul client pour effectuer un paiement. Générez une nouvelle session de paiement pour chaque client et chaque tentative de paiement au lieu de partager ou de réutiliser un lien.

Prérequis

Dodo Payments Account

Vous devez disposer d’un compte marchand Dodo Payments actif avec un accès à l’API.

API Credentials

Générez vos identifiants API depuis le tableau de bord Dodo Payments :

Products Setup

Créez vos produits dans le tableau de bord Dodo Payments avant d’implémenter les sessions de paiement.

Créer votre première session de paiement

Node.js SDK
Python SDK
REST API

import DodoPayments from 'dodopayments';

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

async function createCheckoutSession() {
  try {
    const session = await client.checkoutSessions.create({
      // Products to sell - use IDs from your Dodo Payments dashboard
      product_cart: [
        {
          product_id: 'prod_123', // Replace with your actual product ID
          quantity: 1
        }
      ],
      
      // Pre-fill customer information to reduce friction
      customer: {
        email: 'customer@example.com',
        name: 'John Doe',
        phone_number: '+1234567890'
      },
      
      // Billing address for tax calculation and compliance
      billing_address: {
        street: '123 Main St',
        city: 'San Francisco',
        state: 'CA',
        country: 'US', // Required: ISO 3166-1 alpha-2 country code
        zipcode: '94102'
      },
      
      // Where to redirect after successful payment
      return_url: 'https://yoursite.com/checkout/success',
      
      // Custom data for your internal tracking
      metadata: {
        order_id: 'order_123',
        source: 'web_app'
      }
    });

    // Redirect your customer to this URL to complete payment
    console.log('Checkout URL:', session.checkout_url);
    console.log('Session ID:', session.session_id);
    
    return session;
    
  } catch (error) {
    console.error('Failed to create checkout session:', error);
    throw error;
  }
}

// Example usage in an Express.js route
app.post('/create-checkout', async (req, res) => {
  try {
    const session = await createCheckoutSession();
    res.json({ checkout_url: session.checkout_url });
  } catch (error) {
    res.status(500).json({ error: 'Failed to create checkout session' });
  }
});

import os
from dodopayments import DodoPayments

# Initialize the Dodo Payments client
client = DodoPayments(
    bearer_token=os.environ.get("DODO_PAYMENTS_API_KEY"),  # This is the default and can be omitted
    environment="test_mode",  # defaults to "live_mode"
)

def create_checkout_session():
    """
    Create a checkout session for a single product with customer data pre-filled.
    Returns the session object containing checkout_url for customer redirection.
    """
    try:
        session = client.checkout_sessions.create(
            # Products to sell - use IDs from your Dodo Payments dashboard
            product_cart=[
                {
                    "product_id": "prod_123",  # Replace with your actual product ID
                    "quantity": 1
                }
            ],
            
            # Pre-fill customer information to reduce checkout friction
            customer={
                "email": "customer@example.com",
                "name": "John Doe",
                "phone_number": "+1234567890"
            },
            
            # Billing address for tax calculation and compliance
            billing_address={
                "street": "123 Main St",
                "city": "San Francisco", 
                "state": "CA",
                "country": "US",  # Required: ISO 3166-1 alpha-2 country code
                "zipcode": "94102"
            },
            
            # Where to redirect after successful payment
            return_url="https://yoursite.com/checkout/success",
            
            # Custom data for your internal tracking
            metadata={
                "order_id": "order_123",
                "source": "web_app"
            }
        )
        
        # Redirect your customer to this URL to complete payment
        print(f"Checkout URL: {session.checkout_url}")
        print(f"Session ID: {session.session_id}")
        
        return session
        
    except Exception as error:
        print(f"Failed to create checkout session: {error}")
        raise error

# Example usage in a Flask route
from flask import Flask, jsonify, request

app = Flask(__name__)

@app.route('/create-checkout', methods=['POST'])
def create_checkout():
    try:
        session = create_checkout_session()
        return jsonify({"checkout_url": session.checkout_url})
    except Exception as error:
        return jsonify({"error": "Failed to create checkout session"}), 500

// Direct API call using fetch - useful for any JavaScript environment
async function createCheckoutSession() {
  try {
    const response = await fetch('https://test.dodopayments.com/checkouts', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${process.env.DODO_PAYMENTS_API_KEY}`
      },
      body: JSON.stringify({
        // Products to sell - use IDs from your Dodo Payments dashboard
        product_cart: [
          {
            product_id: 'prod_123', // Replace with your actual product ID
            quantity: 1
          }
        ],
        
        // Pre-fill customer information to reduce checkout friction
        customer: {
          email: 'customer@example.com',
          name: 'John Doe',
          phone_number: '+1234567890'
        },
        
        // Billing address for tax calculation and compliance
        billing_address: {
          street: '123 Main St',
          city: 'San Francisco',
          state: 'CA', 
          country: 'US', // Required: ISO 3166-1 alpha-2 country code
          zipcode: '94102'
        },
        
        // Where to redirect after successful payment
        return_url: 'https://yoursite.com/checkout/success',
        
        // Custom data for your internal tracking
        metadata: {
          order_id: 'order_123',
          source: 'web_app'
        }
      })
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    const session = await response.json();
    
    // Redirect your customer to this URL to complete payment
    console.log('Checkout URL:', session.checkout_url);
    console.log('Session ID:', session.session_id);
    
    return session;
    
  } catch (error) {
    console.error('Failed to create checkout session:', error);
    throw error;
  }
}

// Example: Redirect user to checkout
createCheckoutSession().then(session => {
  window.location.href = session.checkout_url;
});

Réponse de l’API

Toutes les méthodes ci-dessus renvoient la même structure de réponse :

{
  "session_id": "cks_Gi6KGJ2zFJo9rq9Ukifwa",
  "checkout_url": "https://test.checkout.dodopayments.com/session/cks_Gi6KGJ2zFJo9rq9Ukifwa"
}

Le checkout_url généré est à usage unique et expire dans les 24 heures. Ne le mettez pas en cache et ne le réutilisez pas entre plusieurs clients ou tentatives de paiement : créez une nouvelle session de paiement chaque fois que vous avez besoin d’un nouveau lien.

Get the checkout URL

Extrayez le checkout_url de la réponse de l’API.

Redirect your customer

Dirigez votre client vers l’URL de paiement pour terminer son achat.

// Redirect immediately
window.location.href = session.checkout_url;

// Or open in new window
window.open(session.checkout_url, '_blank');

Options d’intégration alternatives : au lieu d’effectuer une redirection, vous pouvez intégrer directement le paiement dans votre page avec Overlay Checkout (superposition modale) ou Inline Checkout (entièrement intégré). Dans une application mobile native, transmettez la même URL aux SDK Mobile Checkout pour Android, iOS, React Native ou Flutter. Toutes ces options utilisent la même URL de session de paiement.

Handle the return

Après le paiement, les clients sont redirigés vers votre return_url avec des paramètres de requête comprenant l’ID du paiement ou de l’abonnement, le statut, l’adresse e-mail du client et les éventuelles clés de licence. Consultez la documentation des paramètres return_url pour obtenir la liste complète.

Corps de la requête

Required Fields

Champs essentiels nécessaires pour chaque session de paiement

Optional Fields

Configuration supplémentaire pour personnaliser votre expérience de paiement

Champs obligatoires

array

requis

Tableau de produits à inclure dans la session de paiement. Chaque produit doit avoir un product_id valide provenant de votre tableau de bord Dodo Payments.

Paiement mixte : vous pouvez combiner des produits avec paiement unique et des produits par abonnement dans une même session de paiement. Cela permet des cas d’utilisation avancés, comme des frais de configuration associés à des abonnements, des offres groupées de matériel et de SaaS, et bien plus encore.

Afficher Product Cart Item Properties

string

requis

Identifiant unique du produit provenant de votre tableau de bord Dodo Payments.Exemple : "prod_123abc456def"

integer

requis

Quantité du produit.Exemple : 1 pour un seul article, 3 pour plusieurs quantités

array

Tableau d’addons à associer au produit. Valide uniquement si le produit est un abonnement.

Afficher Addon item properties

string

requis

integer

requis

integer

Montant payé par le client lorsque pay_what_you_want est activé. Si cette option est désactivée, ce champ est ignoré.Format : représenté dans la plus petite unité de la devise (par exemple, les centimes pour USD). Pour facturer 1,00 $, transmettez 100.

array

Remplacements par session de paiement pour les droits de crédit déjà associés à ce produit. Utilisez ce champ pour accorder un nombre différent de crédits pour cette session uniquement — par exemple, une offre promotionnelle accordant 1 000 crédits API au lieu des 500 crédits par défaut du produit — sans créer de produit distinct.

Chaque credit_entitlement_id doit déjà être associé au produit. Ce champ remplace uniquement le credits_amount accordé lors de la finalisation de cette session ; les paramètres des droits de crédit au niveau du produit (expiration, report, etc.) continuent de s’appliquer.

Afficher Credit entitlement override properties

string

requis

ID du droit de crédit à remplacer. Il doit déjà être associé au produit.

string

requis

Nombre de crédits à accorder pour cette session de paiement, en remplacement du credits_amount défini au niveau du produit. Doit être supérieur à zéro.

Trouver les ID de vos produits : vous trouverez les ID des produits dans votre tableau de bord Dodo Payments, sous Produits → Afficher les détails, ou en utilisant l’API List Products.

Champs facultatifs

Configurez ces champs pour personnaliser l’expérience de paiement et ajouter une logique métier à votre flux de paiement.

Customer Information

object

Informations sur le client. Vous pouvez associer un client existant à l’aide de son ID ou créer un nouvel enregistrement client pendant le paiement.

Attach Existing Customer
New Customer

Associez un client existant à la session de paiement à l’aide de son ID.

Afficher Existing Customer Properties

string

requis

Identifiant unique d’un client existant. Utilisez-le pour associer la session de paiement à un client existant au lieu d’en créer un nouveau.

Créez un nouvel enregistrement client pendant le paiement.

Afficher New Customer Properties

string

requis

Adresse e-mail du client. Obligatoire lors de la création d’un nouveau client.

string

Nom complet du client, tel qu’il doit apparaître sur les reçus et les factures.Exemple : "John Doe" ou "Jane Smith"

string

Numéro de téléphone du client au format international. Obligatoire pour certains moyens de paiement et la prévention de la fraude.Format : incluez l’indicatif du pays, par exemple "+1234567890" pour les numéros américains

object

Informations sur l’adresse de facturation pour un calcul précis des taxes, la prévention de la fraude et la conformité réglementaire.

Lorsque confirm est défini sur true, tous les champs de l’adresse de facturation deviennent obligatoires pour créer la session.

Afficher Billing address object properties

string

Adresse complète, avec numéro et nom de rue, ainsi que numéro d’appartement ou d’unité, le cas échéant.Exemple : "123 Main St, Apt 4B" ou "456 Oak Avenue"

string

Nom de la ville ou de la municipalité.Exemple : "San Francisco", "New York", "London"

string

Nom de l’État, de la province ou de la région. Utilisez les noms complets ou les abréviations standard.Exemple : "California" ou "CA", "Ontario" ou "ON"

string

requis

Code pays ISO à deux lettres (ISO 3166-1 alpha-2). Ce champ est toujours obligatoire lorsqu’une billing_address est fournie.Exemples : "US" (États-Unis), "CA" (Canada), "GB" (Royaume-Uni), "DE" (Allemagne)

Country Code Reference

Afficher la liste complète des pays pris en charge et leurs codes ISO

string

Code postal, ZIP code ou équivalent selon les exigences du pays.Exemples : "94102" (États-Unis), "M5V 3A8" (Canada), "SW1A 1AA" (Royaume-Uni)

Payment Configuration

array

Contrôlez les moyens de paiement disponibles pour les clients lors du paiement. Cela permet d’optimiser l’expérience pour certains marchés ou exigences commerciales.Options disponibles : credit, debit, upi_collect, apple_pay, google_pay, amazon_pay, klarna, affirm, afterpay_clearpay, cashapp, multibanco, bancontact_card, eps, ideal, przelewy24, paypal

Important : incluez toujours credit et debit comme options de secours afin d’éviter les échecs de paiement lorsque les moyens de paiement privilégiés ne sont pas disponibles.

Exemple :

["apple_pay", "google_pay", "credit", "debit"]

string

Remplacez la sélection de devise par défaut par une devise de facturation fixe. Utilise les codes de devise ISO 4217.Devises prises en charge : USD, EUR, GBP, CAD, AUD, INR, et bien d’autresExemple : "USD" pour les dollars américains, "EUR" pour les euros

Ce champ n’est pris en compte que lorsque la tarification adaptative est activée. Si elle est désactivée, la devise par défaut du produit est utilisée.

boolean

défaut:"false"

Affichez les moyens de paiement précédemment enregistrés pour les clients récurrents afin d’accélérer le paiement et d’améliorer l’expérience utilisateur.

Session Management

string

URL vers laquelle rediriger les clients après la finalisation du paiement. Dodo Payments ajoute les paramètres de requête suivants à votre URL lors de la redirection :

Paramètre	Type	Condition
`payment_id`	`string`	Toujours présent pour les paiements uniques
`subscription_id`	`string`	Toujours présent pour les paiements par abonnement
`status`	`string`	Toujours présent
`license_key`	`string`	Présent si le produit dispose de clés de licence activées. Séparé par des virgules si plusieurs clés sont présentes
`email`	`string`	Présent si l’adresse e-mail du client est enregistrée

Exemples d’URL de redirection :

# One-time payment with license key
https://yoursite.com/return?payment_id=pay_xxx&status=succeeded&license_key=LK-001&email=customer%40example.com

# Subscription payment with multiple license keys
https://yoursite.com/return?subscription_id=sub_xxx&status=active&license_key=LK-001,LK-002&email=customer%40example.com

# Payment without license keys
https://yoursite.com/return?payment_id=pay_xxx&status=succeeded&email=customer%40example.com

Utilisez les paramètres de requête license_key et email pour afficher les clés de licence ou envoyer immédiatement une confirmation sur votre page de retour, sans appel API supplémentaire.

string

URL vers laquelle rediriger les clients lorsqu’ils cliquent sur le bouton de retour ou annulent la session de paiement. Si elle n’est pas fournie, le bouton de retour ne sera pas affiché.

Définissez un cancel_url pour offrir aux clients un moyen clair de revenir sur votre site sans terminer leur achat. Cela améliore l’expérience de paiement et réduit les frictions.

boolean

défaut:"false"

Si la valeur est true, finalise immédiatement tous les détails de la session. L’API génère une erreur si des données obligatoires sont manquantes.

array

Appliquez un ou plusieurs codes de réduction cumulés à la session de paiement. Les codes sont appliqués dans l’ordre du tableau (le premier code réduit le prix de base, le deuxième réduit le prix déjà remisé, et ainsi de suite), dans la limite de 20 codes par session.

discount_codes: ['WELCOME10', 'BLACKFRIDAY20']

Le champ discount_code ci-dessous, au singulier, est obsolète, mais reste entièrement pris en charge — les intégrations existantes continuent de fonctionner sans modification. Il ne peut pas être combiné avec discount_codes dans la même requête. Migrez vers discount_codes lorsque cela vous convient pour profiter du cumul.

string

obsolète

Obsolète — préférez discount_codes pour les nouvelles intégrations. Ce champ fonctionne toujours pour assurer la rétrocompatibilité, mais ne peut pas être combiné avec discount_codes dans la même requête.

object

Paires clé-valeur personnalisées permettant de stocker des informations supplémentaires sur la session.

boolean

Remplacez le comportement 3DS par défaut du marchand pour cette session.

boolean

défaut:"false"

Activez le mode de collecte d’adresse minimale. Lorsqu’il est activé, le paiement ne collecte que :

Pays : toujours obligatoire pour la détermination des taxes
Code ZIP/code postal : uniquement dans les régions où il est nécessaire pour calculer la taxe de vente, la TVA ou la GST

Cela réduit considérablement les frictions lors du paiement en supprimant les champs de formulaire inutiles.

Activez l’adresse minimale pour accélérer la finalisation du paiement. La collecte de l’adresse complète reste disponible pour les entreprises qui exigent des informations de facturation complètes.

UI Customization & Features

object

Personnalisez l’apparence et le comportement de l’interface de paiement.

Afficher Customization object properties

string

défaut:"system"

Thème de l’interface de paiement. Options : light, dark ou system.

boolean

défaut:"true"

Affichez la section des détails de la commande dans l’interface de paiement.

boolean

défaut:"true"

Affichez le tag « à la demande » pour les produits concernés.

string

Forcez l’affichage de l’interface de paiement dans une langue spécifique. Par défaut, le paiement détecte automatiquement la langue du navigateur du client.Codes de langue pris en charge : ar (arabe), ca (catalan), de (allemand), en (anglais), es (espagnol), fr (français), he (hébreu), id (indonésien), it (italien), ja (japonais), ko (coréen), ms (malais), nl (néerlandais), pl (polonais), pt (portugais), ro (roumain), ru (russe), sv (suédois), th (thaï), tr (turc), zh (chinois)Exemple : "es" pour l’espagnol, "ja" pour le japonais

object

Configurez des fonctionnalités et des comportements spécifiques pour la session de paiement.

Afficher Feature flags object properties

boolean

défaut:"true"

Permettez aux clients de sélectionner leur devise préférée lors du paiement.

boolean

défaut:"true"

Affichez le champ de saisie du code de réduction dans l’interface de paiement.

boolean

défaut:"false"

Permettez aux clients d’ajouter ou de supprimer des addons d’un produit par abonnement lors du paiement. S’applique uniquement aux produits par abonnement.

boolean

défaut:"true"

Collectez les numéros de téléphone des clients lors du paiement.

boolean

défaut:"true"

Permettez aux clients de saisir leurs numéros d’identification fiscale.

boolean

défaut:"false"

Forcez la création d’un nouvel enregistrement client au lieu de mettre à jour les enregistrements existants.

boolean

Permettez aux clients de modifier leur adresse e-mail lors du paiement.

boolean

Permettez aux clients de modifier leur nom lors du paiement.

boolean

Permettez aux clients de modifier leur adresse lors du paiement.

boolean

Permettez aux clients de modifier leur ville lors du paiement.

boolean

Permettez aux clients de modifier leur État lors du paiement.

boolean

Permettez aux clients de modifier leur pays lors du paiement.

boolean

Permettez aux clients de modifier leur code postal lors du paiement.

boolean

défaut:"false"

Ignorez la page de réussite du paiement par défaut et redirigez immédiatement les clients vers votre return_url une fois le paiement terminé.

Utilisez cette option si vous disposez d’une page de réussite personnalisée offrant une meilleure expérience utilisateur, ou pour les applications mobiles et les flux de paiement intégrés.

Custom Fields

array

Collectez des informations supplémentaires auprès des clients lors du paiement à l’aide 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 payloads webhook et disponibles via l’API.

Afficher Custom field object properties

string

requis

Identifiant unique de ce champ. Utilisé comme clé dans les payloads webhook et les réponses de l’API.Exemple : "company_name", "referral_source", "team_size"

string

requis

Libellé affiché au client dans le formulaire de paiement.Exemple : "Company Name", "How did you hear about us?", "Team Size"

string

requis

Type de champ déterminant les règles de validation de la saisie.Types disponibles :

text - Champ de texte sur une seule ligne
number - Saisie numérique
email - Adresse e-mail avec validation
url - URL avec validation
date - Sélecteur de date
dropdown - Sélection parmi des options prédéfinies
boolean - Bouton Oui/Non

boolean

défaut:"false"

Indique si ce champ doit être rempli avant la finalisation du paiement.

string

Texte d’espace réservé affiché dans le champ de saisie.

array

Liste d’options pour le type de champ dropdown. Obligatoire lorsque field_type est dropdown, ignorée pour les autres types.Exemple : ["Google", "Twitter", "Friend referral", "Other"]

Les réponses des clients aux champs personnalisés sont incluses dans :

Webhooks : payment.succeeded, subscription.active et les autres payloads d’événements pertinents contiennent le tableau custom_field_responses
Réponses de l’API : les objets de paiement et d’abonnement incluent custom_field_responses

Subscription Configuration

object

Configuration supplémentaire pour les sessions de paiement contenant des produits par abonnement.

Afficher Subscription data object properties

integer

Nombre de jours de la période d’essai avant le premier prélèvement. Doit être compris entre 0 et 10 000 jours.Un montant d’essai payant ne peut pas être défini par session — configurez trial_amount sur le prix récurrent du produit. Consultez Essais payants.

object

Configuration d’abonnement à la demande pour la facturation basée sur l’utilisation ou au compteur.

Afficher On-demand object properties

boolean

requis

Si la valeur est true, aucun prélèvement n’est effectué et seuls les détails du moyen de paiement sont autorisés pour une utilisation ultérieure.

integer

Prix du produit pour le prélèvement initial du client. Si aucune valeur n’est indiquée, le prix enregistré du produit est utilisé.Format : représenté dans la plus petite unité de la devise (par exemple, les centimes pour USD). Pour facturer 1,00 $, transmettez 100.

string

Devise facultative du prix du produit. Si aucune valeur n’est indiquée, la devise du produit est utilisée par défaut.

string

Remplacement facultatif de la description du produit pour la facturation et les lignes de commande. Si aucune valeur n’est indiquée, la description enregistrée du produit est utilisée.

boolean

Indique si les frais de devise adaptive currency doivent être inclus dans le prix du produit (true) ou ajoutés en supplément (false). Ignoré si la tarification adaptive currency n’est pas activée.

Exemples d’utilisation

Voici 10 exemples complets présentant différentes configurations de sessions de paiement pour divers scénarios commerciaux :

1. Paiement simple pour un seul produit

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_ebook_guide',
      quantity: 1
    }
  ],
  customer: {
    email: 'customer@example.com',
    name: 'John Doe'
  },
  return_url: 'https://yoursite.com/success'
});

2. Panier multi-produits

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_laptop',
      quantity: 1
    },
    {
      product_id: 'prod_mouse',
      quantity: 2
    },
    {
      product_id: 'prod_warranty',
      quantity: 1
    }
  ],
  customer: {
    email: 'customer@example.com',
    name: 'John Doe',
    phone_number: '+1234567890'
  },
  billing_address: {
    street: '123 Tech Street',
    city: 'San Francisco',
    state: 'CA',
    country: 'US',
    zipcode: '94102'
  },
  return_url: 'https://electronics-store.com/order-confirmation'
});

3. Abonnement avec période d’essai

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_monthly_plan',
      quantity: 1
    }
  ],
  subscription_data: {
    trial_period_days: 14
  },
  customer: {
    email: 'user@startup.com',
    name: 'Jane Smith'
  },
  return_url: 'https://saas-app.com/onboarding',
  metadata: {
    plan_type: 'professional',
    referral_source: 'google_ads'
  }
});

4. Paiement préconfirmé

Lorsque confirm est défini sur true, le client est directement dirigé vers la page de paiement, sans passer par les étapes de confirmation.

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_premium_course',
      quantity: 1
    }
  ],
  customer: {
    email: 'student@university.edu',
    name: 'Alex Johnson',
    phone_number: '+1555123456'
  },
  billing_address: {
    street: '456 University Ave',
    city: 'Boston',
    state: 'MA',
    country: 'US',
    zipcode: '02134'
  },
  confirm: true,
  return_url: 'https://learning-platform.com/course-access',
  metadata: {
    course_category: 'programming',
    enrollment_date: '2024-01-15'
  }
});

5. Paiement avec remplacement de devise

Le remplacement billing_currency ne prend effet que lorsque la devise adaptive currency est activée dans les paramètres de votre compte. Si elle est désactivée, ce paramètre n’a aucun effet.

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_consulting_service',
      quantity: 1
    }
  ],
  customer: {
    email: 'client@company.co.uk',
    name: 'Oliver Williams'
  },
  billing_address: {
    street: '789 Business Park',
    city: 'London',
    state: 'England',
    country: 'GB',
    zipcode: 'SW1A 1AA'
  },
  billing_currency: 'GBP',
  feature_flags: {
    allow_currency_selection: true,
    allow_tax_id: true
  },
  return_url: 'https://consulting-firm.com/service-confirmation'
});

6. Moyens de paiement enregistrés pour les clients récurrents

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_monthly_subscription',
      quantity: 1
    }
  ],
  customer: {
    email: 'returning.customer@example.com',
    name: 'Robert Johnson',
    phone_number: '+1555987654'
  },
  show_saved_payment_methods: true,
  feature_flags: {
    allow_phone_number_collection: true,
    always_create_new_customer: false
  },
  return_url: 'https://subscription-service.com/welcome-back',
  metadata: {
    customer_tier: 'premium',
    account_age: 'returning'
  }
});

7. Paiement B2B avec collecte de l’ID fiscal

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_enterprise_license',
      quantity: 5
    }
  ],
  customer: {
    email: 'procurement@enterprise.com',
    name: 'Sarah Davis',
    phone_number: '+1800555000'
  },
  billing_address: {
    street: '1000 Corporate Blvd',
    city: 'New York',
    state: 'NY',
    country: 'US',
    zipcode: '10001'
  },
  feature_flags: {
    allow_tax_id: true,
    allow_phone_number_collection: true,
    always_create_new_customer: false
  },
  return_url: 'https://enterprise-software.com/license-delivery',
  metadata: {
    customer_type: 'enterprise',
    contract_id: 'ENT-2024-001',
    sales_rep: 'john.sales@company.com'
  }
});

8. Paiement avec thème sombre et codes de réduction cumulés

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_gaming_chair',
      quantity: 1
    }
  ],
  discount_codes: ['BLACKFRIDAY2024'],
  customization: {
    theme: 'dark',
    show_order_details: true,
    show_on_demand_tag: false
  },
  feature_flags: {
    allow_discount_code: true
  },
  customer: {
    email: 'gamer@example.com',
    name: 'Mike Chen'
  },
  return_url: 'https://gaming-store.com/order-complete'
});

9. Moyens de paiement régionaux (UPI pour l’Inde)

Pour plus d’informations sur la configuration et les tests d’UPI, consultez la page Moyens de paiement en Inde.

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_online_course_hindi',
      quantity: 1
    }
  ],
  allowed_payment_method_types: [
    'upi_collect',
    'credit',
    'debit'
  ],
  customer: {
    email: 'student@example.in',
    name: 'Priya Sharma',
    phone_number: '+919876543210'
  },
  billing_address: {
    street: 'MG Road',
    city: 'Bangalore',
    state: 'Karnataka',
    country: 'IN',
    zipcode: '560001'
  },
  billing_currency: 'INR',
  return_url: 'https://education-platform.in/course-access',
  metadata: {
    region: 'south_india',
    language: 'hindi'
  }
});

10. Paiement BNPL (Achetez maintenant, payez plus tard)

Pour plus d’informations sur la configuration et les tests de BNPL, consultez la page Achetez maintenant, payez plus tard (BNPL).

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_luxury_watch',
      quantity: 1
    }
  ],
  allowed_payment_method_types: [
    'klarna',
    'afterpay_clearpay',
    'credit',
    'debit'
  ],
  customer: {
    email: 'fashion.lover@example.com',
    name: 'Emma Thompson',
    phone_number: '+1234567890'
  },
  billing_address: {
    street: '555 Fashion Ave',
    city: 'Los Angeles',
    state: 'CA',
    country: 'US',
    zipcode: '90210'
  },
  feature_flags: {
    allow_phone_number_collection: true
  },
  return_url: 'https://luxury-store.com/purchase-confirmation',
  metadata: {
    product_category: 'luxury',
    price_range: 'high_value'
  }
});

11. Utiliser des moyens de paiement existants pour un paiement instantané

Utilisez le moyen de paiement enregistré d’un client pour créer une session de paiement traitée immédiatement, sans collecte du moyen de paiement :

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_premium_plan',
      quantity: 1
    }
  ],
  customer: {
    customer_id: 'cus_123'  // Required when using payment_method_id
  },
  payment_method_id: 'pm_abc123',  // Use customer's saved payment method
  confirm: true,  // Required when using payment_method_id
  return_url: 'https://yourapp.com/success'
});

Lorsque vous utilisez payment_method_id, confirm doit être défini sur true et un customer_id existant doit être fourni. Le moyen de paiement est vérifié pour déterminer s’il est compatible avec la devise du paiement.

Le moyen de paiement doit appartenir au client et être compatible avec la devise du paiement. Cela permet les achats en un clic pour les clients récurrents.

12. Liens courts pour des URL de paiement plus propres

Générez des liens de paiement raccourcis et partageables avec des slugs personnalisés :

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_monthly_subscription',
      quantity: 1
    }
  ],
  short_link: true,  // Generate a shortened payment link
  return_url: 'https://yourapp.com/success',
  customer: {
    email: 'customer@example.com',
    name: 'John Doe'
  }
});

// The checkout_url will be a shortened, cleaner link
console.log(session.checkout_url);  // e.g., https://checkout.dodopayments.com/buy/abc123

Les liens courts sont parfaits pour le partage par SMS, e-mail ou sur les réseaux sociaux. Ils sont plus faciles à retenir et inspirent davantage confiance aux clients que les URL longues.

13. Ignorer la page de réussite du paiement avec redirection immédiate

Redirigez immédiatement les clients une fois le paiement terminé, sans afficher la page de réussite par défaut :

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_digital_product',
      quantity: 1
    }
  ],
  feature_flags: {
    redirect_immediately: true  // Skip success page, redirect immediately
  },
  return_url: 'https://yourapp.com/success',
  customer: {
    email: 'customer@example.com',
    name: 'Jane Smith'
  }
});

Utilisez redirect_immediately: true lorsque vous disposez d’une page de réussite personnalisée offrant une meilleure expérience utilisateur que la page de réussite par défaut. Cette option est particulièrement utile pour les applications mobiles et les flux de paiement intégrés.

Lorsque redirect_immediately est activé, les clients sont redirigés vers votre return_url immédiatement après la finalisation du paiement, en ignorant complètement la page de réussite par défaut.

14. Forcer une langue

Forcez l’affichage du paiement dans une langue spécifique, en remplaçant la détection de la langue du navigateur du client :

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_subscription',
      quantity: 1
    }
  ],
  customization: {
    force_language: 'ja'  // Force Japanese language
  },
  customer: {
    email: 'customer@example.jp',
    name: 'Tanaka Yuki'
  },
  return_url: 'https://yourapp.com/success'
});

Utilisez force_language lorsque vous connaissez la langue préférée de votre client (par exemple, depuis les paramètres de son compte) ou lorsque vous ciblez certains marchés régionaux.

Langues prises en charge : arabe (ar), catalan (ca), chinois (zh), néerlandais (nl), anglais (en), français (fr), allemand (de), hébreu (he), indonésien (id), italien (it), japonais (ja), coréen (ko), malais (ms), polonais (pl), portugais (pt), roumain (ro), russe (ru), espagnol (es), suédois (sv), thaï (th), turc (tr)

15. Collecter des champs personnalisés

Collectez des informations supplémentaires auprès des clients pendant le paiement à l’aide de champs personnalisés :

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_saas_plan',
      quantity: 1
    }
  ],
  custom_fields: [
    {
      key: 'company_name',
      label: 'Company Name',
      field_type: 'text',
      required: true,
      placeholder: 'Acme Inc.'
    },
    {
      key: 'team_size',
      label: 'Team Size',
      field_type: 'dropdown',
      required: true,
      options: ['1-10', '11-50', '51-200', '201-500', '500+']
    },
    {
      key: 'referral_source',
      label: 'How did you hear about us?',
      field_type: 'dropdown',
      required: false,
      options: ['Google', 'Twitter', 'Friend referral', 'Blog post', 'Other']
    },
    {
      key: 'website',
      label: 'Company Website',
      field_type: 'url',
      required: false,
      placeholder: 'https://example.com'
    }
  ],
  customer: {
    email: 'buyer@company.com',
    name: 'Jane Doe'
  },
  return_url: 'https://yourapp.com/success'
});

Les réponses aux champs personnalisés sont automatiquement incluses dans les payloads webhook (payment.succeeded, subscription.active, etc.) et peuvent être récupérées via l’API. Utilisez-les pour enrichir votre CRM, déclencher des flux d’intégration ou personnaliser l’expérience client.

Types de champs disponibles : text, number, email, url, date, dropdown, boolean

Prévisualiser les sessions de paiement

Avant de créer une session de paiement, vous pouvez prévisualiser le détail des prix, notamment les taxes, les remises et les totaux. Cette fonctionnalité est utile pour afficher des prix exacts aux clients avant qu’ils ne passent au paiement.

Lorsque le panier contient un produit par abonnement, la réponse de prévisualisation renvoie également un next_billing_date — un aperçu de la prochaine date de facturation, afin que vous puissiez l’afficher avant la création de l’abonnement. Il est calculé par rapport à l’heure actuelle : now + trial period lorsqu’un essai s’applique, sinon now + one payment frequency. Le champ est omis pour les paniers composés uniquement de paiements uniques. Il s’agit d’une estimation basée sur l’heure de 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 (le montant de l’essai par unité après remises, 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 total taxé effectivement dû aujourd’hui.

Node.js SDK
Python SDK

const preview = await client.checkoutSessions.preview({
  product_cart: [
    { product_id: 'prod_123', quantity: 1 }
  ],
  billing_address: {
    country: 'US',
    state: 'CA',
    zipcode: '94102'
  },
  discount_codes: ['SAVE20']
});

console.log('Subtotal:', preview.subtotal);
console.log('Tax:', preview.tax);
console.log('Discount:', preview.discount);
console.log('Total:', preview.total);

// Present only when the cart contains a subscription product
console.log('Next billing date:', preview.next_billing_date);

preview = client.checkout_sessions.preview(
    product_cart=[
        {"product_id": "prod_123", "quantity": 1}
    ],
    billing_address={
        "country": "US",
        "state": "CA",
        "zipcode": "94102"
    },
    discount_codes=["SAVE20"]
)

print(f"Subtotal: {preview.subtotal}")
print(f"Tax: {preview.tax}")
print(f"Discount: {preview.discount}")
print(f"Total: {preview.total}")

# Present only when the cart contains a subscription product
print(f"Next billing date: {preview.next_billing_date}")

Preview API Reference

Consultez la documentation complète de l’endpoint de prévisualisation.

Passer des liens dynamiques aux sessions de paiement

Principales différences

Auparavant, lors de la création d’un lien de paiement avec Dynamic Links, vous deviez fournir l’adresse de facturation complète du client. Avec les sessions de paiement, cela n’est plus nécessaire. Vous pouvez simplement transmettre les informations dont vous disposez et nous nous chargeons du reste. Par exemple :

Si vous connaissez uniquement le pays de facturation du client, fournissez simplement cette information.
Le flux de paiement collecte automatiquement les informations manquantes avant de diriger le client vers la page de paiement.
En revanche, si vous disposez déjà de toutes les informations requises et souhaitez accéder directement à la page de paiement, vous pouvez transmettre l’ensemble des données et inclure confirm=true dans le corps de votre requête.

Processus de migration

La migration de Dynamic Links vers les sessions de paiement est simple :

Update your integration

Mettez à jour votre intégration pour utiliser la nouvelle méthode de l’API ou du SDK.

Adjust request payload

Adaptez le payload de la requête au format des sessions de paiement.

That's it!

Oui. Aucune gestion supplémentaire ni étape de migration particulière n’est nécessaire de votre côté.

Référence API associée

Create Checkout Session

Référence API complète pour créer des sessions de paiement avec tous les paramètres et options disponibles

Preview Checkout Session

Référence API pour prévisualiser les prix, les taxes et les totaux avant de créer une session

Integration Guides

Billing Deconstructions

Cookbooks

Quick Start Guide

API Reference & Live Testing

Preview Checkout

Prérequis

Créer votre première session de paiement

Réponse de l’API

Corps de la requête

Required Fields

Optional Fields

Champs obligatoires

Champs facultatifs

Country Code Reference

Exemples d’utilisation

1. Paiement simple pour un seul produit

2. Panier multi-produits

3. Abonnement avec période d’essai

4. Paiement préconfirmé

5. Paiement avec remplacement de devise

6. Moyens de paiement enregistrés pour les clients récurrents

7. Paiement B2B avec collecte de l’ID fiscal

8. Paiement avec thème sombre et codes de réduction cumulés

9. Moyens de paiement régionaux (UPI pour l’Inde)

10. Paiement BNPL (Achetez maintenant, payez plus tard)

11. Utiliser des moyens de paiement existants pour un paiement instantané

12. Liens courts pour des URL de paiement plus propres

13. Ignorer la page de réussite du paiement avec redirection immédiate

14. Forcer une langue

15. Collecter des champs personnalisés

Prévisualiser les sessions de paiement

Preview API Reference

Passer des liens dynamiques aux sessions de paiement

Principales différences

Processus de migration

Référence API associée

Create Checkout Session

Preview Checkout Session

Quick Start Guide

API Reference & Live Testing

Preview Checkout

​Prérequis

​Créer votre première session de paiement

​Réponse de l’API

​Corps de la requête

Required Fields

Optional Fields

​Champs obligatoires

​Champs facultatifs

Country Code Reference

​Exemples d’utilisation

​1. Paiement simple pour un seul produit

​2. Panier multi-produits

​3. Abonnement avec période d’essai

​4. Paiement préconfirmé

​5. Paiement avec remplacement de devise

​6. Moyens de paiement enregistrés pour les clients récurrents

​7. Paiement B2B avec collecte de l’ID fiscal

​8. Paiement avec thème sombre et codes de réduction cumulés

​9. Moyens de paiement régionaux (UPI pour l’Inde)

​10. Paiement BNPL (Achetez maintenant, payez plus tard)

​11. Utiliser des moyens de paiement existants pour un paiement instantané

​12. Liens courts pour des URL de paiement plus propres

​13. Ignorer la page de réussite du paiement avec redirection immédiate

​14. Forcer une langue

​15. Collecter des champs personnalisés

​Prévisualiser les sessions de paiement

Preview API Reference

​Passer des liens dynamiques aux sessions de paiement

​Principales différences

​Processus de migration

​Référence API associée

Create Checkout Session

Preview Checkout Session

Prérequis

Créer votre première session de paiement

Réponse de l’API

Corps de la requête

Champs obligatoires

Champs facultatifs

Exemples d’utilisation

1. Paiement simple pour un seul produit

2. Panier multi-produits

3. Abonnement avec période d’essai

4. Paiement préconfirmé

5. Paiement avec remplacement de devise

6. Moyens de paiement enregistrés pour les clients récurrents

7. Paiement B2B avec collecte de l’ID fiscal

8. Paiement avec thème sombre et codes de réduction cumulés

9. Moyens de paiement régionaux (UPI pour l’Inde)

10. Paiement BNPL (Achetez maintenant, payez plus tard)

11. Utiliser des moyens de paiement existants pour un paiement instantané

12. Liens courts pour des URL de paiement plus propres

13. Ignorer la page de réussite du paiement avec redirection immédiate

14. Forcer une langue

15. Collecter des champs personnalisés

Prévisualiser les sessions de paiement

Passer des liens dynamiques aux sessions de paiement

Principales différences

Processus de migration

Référence API associée