Passer au contenu principal
Validité de la session : Les sessions de paiement sont valides pendant 24 heures par défaut. Si vous passez confirm=true dans votre requête, la session ne sera valide que pendant 15 minutes.

Prérequis

1

Compte Dodo Payments

Vous aurez besoin d’un compte marchand Dodo Payments actif avec accès API.
2

Identifiants API

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

Configuration des produits

Créez vos produits dans le tableau de bord Dodo Payments avant de mettre en œuvre les sessions de paiement.

Création de votre première session de paiement

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: '[email protected]',
        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' });
  }
});

Réponse API

Tous les méthodes ci-dessus retournent la même structure de réponse :
{
  "session_id": "cks_Gi6KGJ2zFJo9rq9Ukifwa",
  "checkout_url": "https://test.checkout.dodopayments.com/session/cks_Gi6KGJ2zFJo9rq9Ukifwa"
}
1

Obtenez l'URL de paiement

Extraire le checkout_url de la réponse API.
2

Redirigez votre client

Dirigez votre client vers l’URL de paiement pour finaliser son achat.
// Redirect immediately
window.location.href = session.checkout_url;

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

Gérez le retour

Après le paiement, les clients sont redirigés vers votre return_url avec des paramètres de requête supplémentaires pour le statut de paiement.

Corps de la requête

Champs requis

Champs essentiels nécessaires pour chaque session de paiement

Champs optionnels

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

Champs requis

product_cart
array
required
Tableau de produits à inclure dans la session de paiement. Chaque produit doit avoir un product_id valide depuis votre tableau de bord Dodo Payments.
Important : Plusieurs paniers de produits ne peuvent contenir que des produits à paiement unique. Vous ne pouvez pas mélanger des produits d’abonnement avec des produits uniques dans la même session de paiement.
Trouvez vos identifiants de produit : Vous pouvez trouver les identifiants de produit dans votre tableau de bord Dodo Payments sous Produits → Voir les détails, ou en utilisant l’API Liste des produits.

Champs optionnels

Configurez ces champs pour personnaliser l’expérience de paiement et ajouter une logique commerciale à votre flux de paiement.
customer
object
Informations sur le client. Vous pouvez soit attacher un client existant en utilisant son identifiant, soit créer un nouvel enregistrement client lors du paiement.
Attachez un client existant à la session de paiement en utilisant son identifiant.
billing_address
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 d’adresse de facturation deviennent requis pour la création réussie de la session.
allowed_payment_method_types
array
Contrôlez quels modes de paiement sont disponibles pour les clients lors du paiement. Cela aide à optimiser pour des marchés ou des exigences commerciales spécifiques.Options disponibles : credit, debit, upi_collect, upi_intent, apple_pay, google_pay, amazon_pay, klarna, affirm, afterpay_clearpay, sepa, ach, cashapp, multibanco, bancontact_card, eps, ideal, przelewy24, paypal
Critique : Incluez toujours credit et debit comme options de secours pour éviter les échecs de paiement lorsque les méthodes de paiement préférées ne sont pas disponibles.
Exemple :
["apple_pay", "google_pay", "credit", "debit"]
billing_currency
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 plusExemple : "USD" pour les dollars américains, "EUR" pour les euros
Ce champ n’est efficace que lorsque le prix adaptatif est activé. Si le prix adaptatif est désactivé, la devise par défaut du produit sera utilisée.
show_saved_payment_methods
boolean
default:"false"
Affichez les méthodes de paiement précédemment enregistrées pour les clients récurrents, améliorant la vitesse de paiement et l’expérience utilisateur.
return_url
string
URL pour rediriger les clients après un paiement réussi ou une annulation.
confirm
boolean
default:"false"
Si vrai, finalise immédiatement tous les détails de la session. L’API renverra une erreur si des données requises sont manquantes.
discount_code
string
Appliquez un code de réduction à la session de paiement.
metadata
object
Paires clé-valeur personnalisées pour stocker des informations supplémentaires sur la session.
force_3ds
boolean
Remplacez le comportement 3DS par défaut du marchand pour cette session.
minimal_address
boolean
default:"false"
Activez le mode de collecte d’adresse minimale. Lorsqu’il est activé, le paiement ne collecte que :
  • Pays : Toujours requis pour la détermination des taxes
  • Code postal : Seulement dans les régions où cela est nécessaire pour le calcul de la taxe de vente, de la TVA ou de la GST
Cela réduit considérablement les frictions de paiement en éliminant les champs de formulaire inutiles.
Activez l’adresse minimale pour un achèvement plus rapide du paiement. La collecte complète d’adresse reste disponible pour les entreprises qui nécessitent des détails de facturation complets.
customization
object
Personnalisez l’apparence et le comportement de l’interface de paiement.
feature_flags
object
Configurez des fonctionnalités et des comportements spécifiques pour la session de paiement.
subscription_data
object
Configuration supplémentaire pour les sessions de paiement contenant des produits d’abonnement.

Exemples d’utilisation

Voici 10 exemples complets montrant différentes configurations de session de paiement pour divers scénarios commerciaux :

1. Paiement simple pour un produit unique

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_ebook_guide',
      quantity: 1
    }
  ],
  customer: {
    email: '[email protected]',
    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: '[email protected]',
    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: '[email protected]',
    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 sera directement dirigé vers la page de paiement, contournant toute étape de confirmation.
const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_premium_course',
      quantity: 1
    }
  ],
  customer: {
    email: '[email protected]',
    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 adaptative est activée dans vos paramètres de compte. Si la devise adaptative est désactivée, ce paramètre n’aura aucun effet.
const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_consulting_service',
      quantity: 1
    }
  ],
  customer: {
    email: '[email protected]',
    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. Méthodes de paiement enregistrées pour les clients récurrents

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_monthly_subscription',
      quantity: 1
    }
  ],
  customer: {
    email: '[email protected]',
    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 d’identification fiscale

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_enterprise_license',
      quantity: 5
    }
  ],
  customer: {
    email: '[email protected]',
    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: '[email protected]'
  }
});

8. Paiement en thème sombre avec code de réduction

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

9. Méthodes de paiement régionales (UPI pour l’Inde)

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_online_course_hindi',
      quantity: 1
    }
  ],
  allowed_payment_method_types: [
    'upi_collect',
    'upi_intent',
    'credit',
    'debit'
  ],
  customer: {
    email: '[email protected]',
    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)

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_luxury_watch',
      quantity: 1
    }
  ],
  allowed_payment_method_types: [
    'klarna',
    'affirm',
    'afterpay_clearpay',
    'credit',
    'debit'
  ],
  customer: {
    email: '[email protected]',
    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'
  }
});

Passer des liens dynamiques aux sessions de paiement

Différences clés

Auparavant, lors de la création d’un lien de paiement avec des liens dynamiques, 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 occuperons du reste. Par exemple :
  • Si vous ne connaissez que le pays de facturation du client, fournissez simplement cela.
  • Le flux de paiement collectera automatiquement les détails manquants avant de déplacer le client vers la page de paiement.
  • D’autre part, si vous avez déjà toutes les informations requises et souhaitez passer 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

Migrer des liens dynamiques vers des sessions de paiement est simple :
1

Mettez à jour votre intégration

Mettez à jour votre intégration pour utiliser la nouvelle méthode API ou SDK.
2

Ajustez le payload de la requête

Ajustez le payload de la requête selon le format des sessions de paiement.
3

C'est tout !

Oui. Aucune gestion supplémentaire ou étape de migration spéciale n’est nécessaire de votre part.