Guide d'intégration mobile

​

Prérequis

• Compte Dodo Payments : compte marchand actif avec accès à l’API
• Identifiants API : clé API et clé secrète de webhook depuis votre tableau de bord
• Projet d’application mobile : application Android, iOS, React Native ou Flutter
• Serveur backend : pour gérer de manière sécurisée la création des sessions de checkout

​

Flux d’intégration

func getCheckoutURL(productId: String, customerEmail: String, customerName: String) async throws -> String {
    let url = URL(string: "https://your-backend.com/api/create-checkout-session")!
    var request = URLRequest(url: url)
    request.httpMethod = "POST"
    request.setValue("application/json", forHTTPHeaderField: "Content-Type")
    request.setValue("Bearer \(userSessionToken)", forHTTPHeaderField: "Authorization")
    
    let requestData: [String: Any] = [
        "productId": productId,
        "customerEmail": customerEmail,
        "customerName": customerName
    ]
    request.httpBody = try JSONSerialization.data(withJSONObject: requestData)
    
    let (data, _) = try await URLSession.shared.data(for: request)
    let response = try JSONDecoder().decode(CheckoutResponse.self, from: data)
    return response.checkout_url
}

suspend fun getCheckoutURL(productId: String, customerEmail: String, customerName: String): String {
    val client = OkHttpClient()
    val requestBody = JSONObject().apply {
        put("productId", productId)
        put("customerEmail", customerEmail)
        put("customerName", customerName)
    }.toString().toRequestBody("application/json".toMediaType())
    
    val request = Request.Builder()
        .url("https://your-backend.com/api/create-checkout-session")
        .header("Authorization", "Bearer $userSessionToken")
        .post(requestBody)
        .build()
    
    val response = client.newCall(request).execute()
    val responseBody = response.body?.string()
    val jsonResponse = JSONObject(responseBody ?: "")
    return jsonResponse.getString("checkout_url")
}

const getCheckoutURL = async (productId, customerEmail, customerName) => {
  try {
    const response = await fetch('https://your-backend.com/api/create-checkout-session', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${userSessionToken}`,
      },
      body: JSON.stringify({
        productId,
        customerEmail,
        customerName
      })
    });
    
    const data = await response.json();
    return data.checkout_url;
  } catch (error) {
    console.error('Failed to get checkout URL:', error);
    throw error;
  }
};

import 'dart:convert';
import 'package:http/http.dart' as http;

Future<String> getCheckoutUrl({
  required String productId,
  required String customerEmail,
  required String customerName,
}) async {
  final response = await http.post(
    Uri.parse('https://your-backend.com/api/create-checkout-session'),
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer $userSessionToken',
    },
    body: jsonEncode({
      'productId': productId,
      'customerEmail': customerEmail,
      'customerName': customerName,
    }),
  );

  if (response.statusCode != 200) {
    throw Exception('Failed to get checkout URL: ${response.statusCode}');
  }
  return jsonDecode(response.body)['checkout_url'] as String;
}

​

Choisissez votre SDK

​

Enregistrement d’un schéma d’URL de callback

android {
    defaultConfig {
        manifestPlaceholders["dodoCallbackScheme"] = "myapp"
    }
}

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLName</key>
    <string>myapp</string>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>myapp</string>
    </array>
  </dict>
</array>

{
  "expo": {
    "scheme": "myapp",
    "plugins": [
      [
        "@dodopayments/react-native-checkout",
        { "scheme": "myappcheckout" }
      ]
    ]
  }
}

​

Personnalisation de l’apparence

const result = await DodoCheckout.start({
  checkoutUrl,
  returnUrl: 'myapp://checkout/return',
  customization: {
    android: { toolbarColor: '#6366F1', closeButtonStyle: 'back' },
    ios: { presentationStyle: 'fullScreen', colorScheme: 'dark' },
  },
});

final result = await DodoCheckout.instance.start(
  CheckoutParams(
    checkoutUrl: Uri.parse(checkoutUrl),
    returnUrl: Uri.parse('myapp://checkout/return'),
    customization: BrowserCustomization(
      android: AndroidBrowserOptions(
        toolbarColor: Color(0xFF6366F1),
        closeButtonStyle: CloseButtonStyle.back,
      ),
      ios: IosBrowserOptions(
        presentationStyle: PresentationStyle.fullScreen,
        colorScheme: BrowserColorScheme.dark,
      ),
    ),
  ),
);

val result = DodoCheckout.start(
    activity,
    CheckoutParams(
        checkoutUrl = checkoutUrl,
        returnUrl = "myapp://checkout/return",
        customization = BrowserCustomization(
            toolbarColor = Color.parseColor("#6366F1"),
            closeButtonStyle = BrowserCustomization.CloseButtonStyle.BACK,
        )
    )
) { event -> }

let result = try await DodoCheckout.start(
    checkoutUrl: checkoutUrl,
    returnUrl: URL(string: "myapp://checkout/return")!,
    customization: BrowserCustomization(
        presentationStyle: .fullScreen,
        colorScheme: .dark
    )
)

​

Personnalisation de la page de checkout

​

Recettes optimisées pour le mobile

Minimal Mobile Checkout - fastest path to payment

Utilisez cette configuration pour obtenir le formulaire le plus court possible : moyens de paiement en haut, seul un code postal requis pour l’adresse, aucun champ de réduction et un thème correspondant à l’appareil.

• Node.js SDK
• Python SDK

import DodoPayments from 'dodopayments';

const client = new DodoPayments({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'test_mode',
});

const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_your_product_id', quantity: 1 }],
  customer: { email: 'user@example.com', name: 'Jane Smith' },
  billing_address: { country: 'US' },
  return_url: 'myapp://checkout/success',
  cancel_url: 'myapp://checkout/cancelled',
  billing_currency: 'USD',
  minimal_address: true,
  customization: {
    show_order_details: false,
    theme: 'system',
  },
  feature_flags: {
    allow_discount_code: false,
    allow_currency_selection: false,
  },
});

console.log(session.checkout_url);

See all 26 lines

import os
import dodopayments

client = dodopayments.DodoPayments(
    bearer_token=os.environ.get("DODO_PAYMENTS_API_KEY"),
    environment="test_mode",
)

session = client.checkout_sessions.create(
    product_cart=[{"product_id": "pdt_your_product_id", "quantity": 1}],
    customer={"email": "user@example.com", "name": "Jane Smith"},
    billing_address={"country": "US"},
    return_url="myapp://checkout/success",
    cancel_url="myapp://checkout/cancelled",
    billing_currency="USD",
    minimal_address=True,
    customization={
        "show_order_details": False,
        "theme": "system",
    },
    feature_flags={
        "allow_discount_code": False,
        "allow_currency_selection": False,
    },
)

print(session.checkout_url)

See all 27 lines

Consultez Checkout Sessions pour connaître tous les paramètres disponibles et leurs valeurs par défaut.

Branded Mobile Checkout - custom colors, fonts, and button label

Utilisez cette configuration lorsque la page de checkout doit sembler intégrée à votre application. Définissez les couleurs de votre marque, une police personnalisée et un libellé de bouton de paiement localisé.

• Node.js SDK
• Python SDK

const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_your_product_id', quantity: 1 }],
  customer: { email: 'user@example.com', name: 'Jane Smith' },
  billing_address: { country: 'US' },
  billing_currency: 'USD',
  return_url: 'myapp://checkout/success',
  minimal_address: true,
  customization: {
    show_order_details: false,
    theme: 'dark',
    theme_config: {
      dark: {
        button_primary: '#7C3AED',
        button_primary_hover: '#6D28D9',
        button_text_primary: '#FFFFFF',
        bg_primary: '#1A1A2E',
        bg_secondary: '#16213E',
        text_primary: '#E2E8F0',
      },
      pay_button_text: 'Complete Purchase',
      radius: '8px',
    },
  },
});

See all 24 lines

session = client.checkout_sessions.create(
    product_cart=[{"product_id": "pdt_your_product_id", "quantity": 1}],
    customer={"email": "user@example.com", "name": "Jane Smith"},
    billing_address={"country": "US"},
    billing_currency="USD",
    return_url="myapp://checkout/success",
    minimal_address=True,
    customization={
        "show_order_details": False,
        "theme": "dark",
        "theme_config": {
            "dark": {
                "button_primary": "#7C3AED",
                "button_primary_hover": "#6D28D9",
                "button_text_primary": "#FFFFFF",
                "bg_primary": "#1A1A2E",
                "bg_secondary": "#16213E",
                "text_primary": "#E2E8F0",
            },
            "pay_button_text": "Complete Purchase",
            "radius": "8px",
        },
    },
)

See all 24 lines

theme_config accepte des objets dark et light distincts afin que la palette s’adapte à l’apparence actuelle de l’appareil. Consultez Checkout Sessions pour la référence complète des couleurs.

One-Click Returning Customer - saved card, instant confirmation

Utilisez cette configuration pour les utilisateurs connectés ayant déjà payé. Combinez un identifiant client, leur moyen de paiement enregistré et confirm: true pour ignorer entièrement le formulaire de checkout.

• Node.js SDK
• Python SDK

const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_your_product_id', quantity: 1 }],
  customer: { customer_id: 'cus_returning_customer_id' },
  billing_address: { country: 'US' },
  billing_currency: 'USD',
  return_url: 'myapp://checkout/success',
  payment_method_id: 'pm_saved_payment_method_id',
  confirm: true,
  show_saved_payment_methods: true,           // top-level parameter
  feature_flags: { redirect_immediately: true },
});

See all 11 lines

session = client.checkout_sessions.create(
    product_cart=[{"product_id": "pdt_your_product_id", "quantity": 1}],
    customer={"customer_id": "cus_returning_customer_id"},
    billing_address={"country": "US"},
    billing_currency="USD",
    return_url="myapp://checkout/success",
    payment_method_id="pm_saved_payment_method_id",
    confirm=True,
    show_saved_payment_methods=True,           # top-level parameter
    feature_flags={"redirect_immediately": True},
)

See all 11 lines

Le status du retour par deep link est uniquement un indice d’interface. Confirmez l’accès en écoutant le webhook payment.succeeded sur votre backend.

Subscription with Free Trial - trial before first charge

Utilisez cette configuration pour les produits d’abonnement qui proposent une période d’essai gratuite avant le premier cycle de facturation.

• Node.js SDK
• Python SDK

const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_your_subscription_product_id', quantity: 1 }],
  customer: { email: 'user@example.com', name: 'Jane Smith' },
  billing_address: { country: 'US' },
  billing_currency: 'USD',
  return_url: 'myapp://subscription/activated',
  cancel_url: 'myapp://subscription/cancelled',
  minimal_address: true,
  customization: {
    show_order_details: false,
    theme: 'system',
  },
  subscription_data: { trial_period_days: 14 },
});

See all 14 lines

session = client.checkout_sessions.create(
    product_cart=[{"product_id": "pdt_your_subscription_product_id", "quantity": 1}],
    customer={"email": "user@example.com", "name": "Jane Smith"},
    billing_address={"country": "US"},
    billing_currency="USD",
    return_url="myapp://subscription/activated",
    cancel_url="myapp://subscription/cancelled",
    minimal_address=True,
    customization={"show_order_details": False, "theme": "system"},
    subscription_data={"trial_period_days": 14},
)

See all 11 lines

Accordez l’accès à la fonctionnalité lorsque votre backend reçoit le webhook subscription.active — et non lorsque le SDK mobile renvoie un résultat. Consultez le Guide d’intégration des abonnements pour connaître le flux complet des webhooks.

On-Demand Mandate - save a card for future variable charges

Utilisez cette configuration pour tokeniser la carte d’un client en vue de paiements ultérieurs (rechargements de portefeuille, paiement à l’usage, BNPL) sans afficher de libellé « abonnement ». Le client autorise son moyen de paiement une seule fois ; vous facturez ensuite des montants variables à la demande.

C’est le modèle utilisé par les applications qui facturent selon l’utilisation — par exemple une application d’astrologie qui facture chaque session à partir d’une carte préautorisée, plutôt que selon un calendrier fixe.

• Node.js SDK
• Python SDK

// Step 1: Authorize the mandate (no charge yet)
const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_your_subscription_product_id', quantity: 1 }],
  customer: { email: 'user@example.com', name: 'Jane Smith' },
  billing_address: { country: 'US' },
  billing_currency: 'USD',
  return_url: 'myapp://mandate/authorized',
  cancel_url: 'myapp://mandate/cancelled',
  minimal_address: true,
  customization: {
    show_order_details: false,
    show_on_demand_tag: false, // hides the "on-demand" / "subscription" label
    theme: 'system',
  },
  subscription_data: {
    on_demand: { mandate_only: true },
  },
});

// Step 2: Later, charge any amount using the subscription ID
// (received via the subscription.active webhook after mandate authorization)
// await client.subscriptions.charge(subscriptionId, {
//   product_price: 2000,         // $20.00 in cents
//   product_currency: 'USD',
//   product_description: 'Session credits',
// });

See all 26 lines

# Step 1: Authorize the mandate (no charge yet)
session = client.checkout_sessions.create(
    product_cart=[{"product_id": "pdt_your_subscription_product_id", "quantity": 1}],
    customer={"email": "user@example.com", "name": "Jane Smith"},
    billing_address={"country": "US"},
    billing_currency="USD",
    return_url="myapp://mandate/authorized",
    cancel_url="myapp://mandate/cancelled",
    minimal_address=True,
    customization={
        "show_order_details": False,
        "show_on_demand_tag": False,  # hides the "on-demand" / "subscription" label
        "theme": "system",
    },
    subscription_data={"on_demand": {"mandate_only": True}},
)

# Step 2: Later, charge any amount using the subscription ID
# client.subscriptions.charge(subscription_id, {
#     "product_price": 2000,  # $20.00 in cents
#     "product_currency": "USD",
#     "product_description": "Session credits",
# })

See all 23 lines

Les frais à la demande nécessitent un minimum de 1 USD (100 cents). Les montants inférieurs à 1 USD seront rejetés avec "value out of range". Pour une autorisation d’un montant nul, utilisez mandate_only: true comme indiqué ci-dessus, puis facturez au moins 1 USD lors des appels suivants.

Consultez Abonnements à la demande pour découvrir le flux complet des frais, les événements de webhook et les politiques de nouvelle tentative.

​

Flux d’abonnement depuis un appareil mobile

​

Abonnements récurrents classiques

​

Abonnements à la demande

• Définissez show_on_demand_tag: false afin que la page de checkout n’affiche pas les termes « abonnement » ou « à la demande ». Pour les cas d’usage de tokenisation de cartes, les clients ne s’attendent pas à voir une terminologie liée aux abonnements.
• Une fois le mandat autorisé, votre backend reçoit subscription.active. Enregistrez subscription_id : vous l’utiliserez pour tous les frais ultérieurs.

​

Abonnement avec essai gratuit

​

Mises à niveau et rétrogradations

​

Réduire les abandons lors du checkout

​

Optimiser le formulaire

​

Préremplir les données client

• Nouveaux clients — définissez customer.email et customer.name à partir de votre session d’authentification.
• Clients récurrents — définissez customer.customer_id pour préremplir automatiquement toutes les informations enregistrées.
• Devise — transmettez toujours billing_currency et billing_address.country ensemble.

​

Outils de récupération

​

Bonnes pratiques

• Sécurité : n’intégrez jamais de clé API dans votre application. Créez les sessions de checkout sur votre backend et transmettez uniquement le checkout_url obtenu au client.
• Autorité : considérez CheckoutResult.status comme un indice d’interface. Accordez l’accès uniquement après confirmation du paiement par votre backend.
• Expérience utilisateur : affichez un état de chargement pendant que votre backend crée la session et traitez cancelled comme un résultat normal, et non comme une erreur.
• Tests : utilisez le mode test et des cartes de test, puis vérifiez le parcours de l’URL de retour sur un appareil réel et dans un simulateur.
• Conversion : définissez show_order_details: false et minimal_address: true pour obtenir les meilleurs taux de finalisation du checkout mobile. Placer les moyens de paiement au-dessus de la ligne de flottaison et réduire le nombre de champs sont les deux changements les plus efficaces.
• Devise : transmettez toujours explicitement billing_currency et billing_address.country ; si l’un des deux manque, la devise adaptative peut modifier la devise de facturation selon l’adresse IP du client.
• Facturation à la demande : définissez show_on_demand_tag: false lorsque vous utilisez des abonnements à la demande pour la tokenisation de cartes. Les clients qui utilisent un flux de rechargement de portefeuille ne s’attendent pas à voir le terme « abonnement ».
• Récupération : activez la récupération des paniers abandonnés dans votre tableau de bord Dodo Payments afin de réengager automatiquement les clients qui ne finalisent pas leur checkout.

​

Résolution des problèmes

​

Problèmes courants

• Le callback n’arrive jamais : le schéma dans returnUrl doit correspondre à celui que vous avez enregistré. Sur Android, il s’agit du placeholder de manifest dodoCallbackScheme ; sur iOS et React Native, il s’agit du type d’URL Info.plist.
• Le checkout revient dans le navigateur au lieu de revenir dans votre application (iOS) : vous n’avez pas transmis l’URL entrante. Appelez DodoCheckout.handleOpenURL(url) depuis .onOpenURL, scene(_:openURLContexts:) ou un écouteur React Native Linking.
• PLATFORM_ERROR sur Android : il s’agit le plus souvent d’une incompatibilité de schéma. Cela peut également se produire lorsque votre MainActivity définit android:taskAffinity="" (la valeur par défaut standard flutter create), ce qui peut faire perdre le checkout en cours à certaines versions OEM.
• ALREADY_IN_PROGRESS : un checkout est encore ouvert. Attendez sa fin ou fermez-le avant d’en démarrer un autre.
• Échec de compilation avec un placeholder non résolu : vous avez ajouté le SDK Android sans jamais définir manifestPlaceholders["dodoCallbackScheme"].
• Paiement réussi, mais accès non accordé : c’est attendu si vous vous basez sur le résultat mobile. Accordez plutôt l’accès à partir du webhook payment.succeeded / subscription.active.
• Apple Pay / Google Pay ne s’affichent pas sur mobile : le checkout est chargé dans une WebView intégrée (WKWebView / Android WebView), qui masque les wallets et peut empêcher 3-D Secure de fonctionner. Ouvrez-le avec le SDK ou dans le navigateur système (Custom Tabs / SFSafariViewController).

​

Ressources supplémentaires

• Guide d’intégration des paiements
• Documentation des webhooks
• Processus de test
• FAQ techniques
• Personnalisation de la session de checkout
• Abonnements à la demande
• Mise à niveau/rétrogradation d’un abonnement
• Récupération des paniers abandonnés
• Customer Portal