Guide d'intégration mobile

​

Prérequis

• Un compte Dodo Payments.
• Une clé API disponible dans Developer → API Keys et un secret de signature de webhook disponible dans Developer → Webhooks.
• Une application Android, iOS, React Native ou Flutter.
• Un serveur backend qui crée les sessions de checkout. La clé API reste sur ce serveur.

​

Workflow 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 mobile

Minimal Mobile Checkout - fastest path to payment

Utilisez cette recette pour obtenir le formulaire le plus court : moyens de paiement en haut, uniquement un code postal pour l’adresse, aucun champ de réduction et un thème qui suit 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 recette lorsque la page de checkout doit sembler intégrée à votre application. Elle définit les couleurs de votre marque, un rayon de bordure et un libellé personnalisé pour le bouton de paiement.

• 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 suive l’apparence de l’appareil. Pour connaître toutes les clés de couleur et l’option de police, consultez Checkout Sessions.

One-Click Returning Customer - saved card, instant confirmation

Utilisez cette recette pour les clients connectés ayant déjà effectué un paiement. Transmettez le customer_id du client, leur payment_method_id enregistré et confirm: true pour ignorer le formulaire de checkout. Avec un payment_method_id, la session débite directement le moyen enregistré et ne renvoie aucun checkout_url ; votre application n’a donc rien à ouvrir. Découvrez le résultat grâce aux webhooks.

• 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' },
  // confirm: true requires a complete billing address
  billing_address: {
    country: 'US',
    state: 'CA',
    city: 'San Francisco',
    street: '123 Main St',
    zipcode: '94102',
  },
  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 18 lines

session = client.checkout_sessions.create(
    product_cart=[{"product_id": "pdt_your_product_id", "quantity": 1}],
    customer={"customer_id": "cus_returning_customer_id"},
    # confirm=True requires a complete billing address
    billing_address={
        "country": "US",
        "state": "CA",
        "city": "San Francisco",
        "street": "123 Main St",
        "zipcode": "94102",
    },
    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 18 lines

Accordez l’accès lorsque votre backend reçoit le webhook payment.succeeded. Tout status affiché par votre application n’est qu’un indice d’interface.

Subscription with Free Trial - trial before first charge

Utilisez cette recette pour un produit d’abonnement avec une période d’essai gratuite avant le premier prélèvement. trial_period_days définit la durée de l’essai pour cette session.

• 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 lorsque votre backend reçoit le webhook subscription.active, et non lorsque le SDK mobile renvoie son résultat. Pour connaître le workflow complet des webhooks, consultez le Subscription Integration Guide.

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

Utilisez cette recette pour enregistrer le moyen de paiement d’un client en vue de prélèvements ultérieurs, comme les recharges de portefeuille, le pay-as-you-go ou le BNPL, sans afficher de libellé d’abonnement. Le client autorise le moyen de paiement une fois, puis vous prélevez des montants variables ultérieurement.

Les applications qui facturent selon l’utilisation suivent ce modèle. Par exemple, une application d’astrologie débite une carte préautorisée pour chaque session plutôt qu’à intervalles fixes.

• 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 24 lines

Un prélèvement à la demande doit être d’au moins 100 dans la plus petite unité monétaire ($1.00 pour USD). L’API rejette un product_price inférieur avec "product_price: value out of range". Pour autoriser le paiement sans prélever, utilisez mandate_only: true comme indiqué ci-dessus, puis prélevez au moins ce minimum ultérieurement.

Pour connaître le workflow complet des prélèvements, les événements webhook et les politiques de nouvelle tentative, consultez On-Demand Subscriptions.

​

Parcours d’abonnement depuis un mobile

​

Abonnements récurrents classiques

​

Abonnements à la demande

• Définissez show_on_demand_tag: false afin que la page de checkout n’affiche ni formulation d’abonnement ni formulation à la demande. Les clients qui enregistrent une carte pour effectuer des recharges ne s’attendent pas à voir des conditions d’abonnement.
• Après l’autorisation du mandat par le client, votre backend reçoit subscription.active. Enregistrez subscription_id, car chaque prélèvement ultérieur l’utilise.

​

Abonnement avec période d’essai gratuite

​

Montées et descentes en gamme

​

Réduire les abandons 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 existants : définissez customer.customer_id pour utiliser les informations enregistrées du client.
• Devise : transmettez billing_currency et billing_address.country ensemble.

​

Outils de récupération

​

Bonnes pratiques

• Sécurité : ne distribuez jamais de clé API dans votre application. Créez les sessions de paiement sur votre backend et transmettez uniquement l’checkout_url à l’application.
• Autorité : considérez CheckoutResult.status comme un simple indice d’interface utilisateur. N’accordez l’accès qu’après confirmation du paiement par votre backend.
• Expérience utilisateur : affichez un état de chargement pendant que votre backend crée la session. Ne considérez pas cancelled comme un échec, car le paiement peut malgré tout avoir été effectué.
• Tests : utilisez le mode test et des cartes de test, puis vérifiez le parcours aller-retour de l’URL de retour sur un appareil réel ainsi que sur un simulateur.
• Conversion : définissez show_order_details: false et minimal_address: true. Ensemble, ils placent les moyens de paiement au-dessus de la ligne de flottaison et suppriment la plupart des champs d’adresse.
• Devise : transmettez à la fois billing_currency et billing_address.country. Si vous omettez l’un des deux, Adaptive Currency peut sélectionner la devise de facturation à partir de l’adresse IP du client.
• Facturation à la demande : définissez show_on_demand_tag: false lorsque vous utilisez des abonnements à la demande uniquement pour enregistrer une carte. Les clients qui rechargent un portefeuille ne s’attendent pas à voir un texte faisant référence à un abonnement.
• Récupération : activez Abandoned Cart Recovery dans le tableau de bord pour envoyer un e-mail aux clients qui ne terminent pas leur paiement.

​

Dépannage

​

Problèmes courants

• Le callback n’arrive jamais : le schéma dans returnUrl doit correspondre au schéma que vous avez enregistré. Sur Android, il s’agit du placeholder de manifeste dodoCallbackScheme. Sur iOS, il s’agit du type d’URL Info.plist. Les applications React Native et Flutter ont besoin des deux et, dans Expo, le plugin de configuration définit les deux.
• Le paiement revient au navigateur au lieu de revenir à votre application (iOS) : votre application ne transmet pas l’URL entrante. Appelez DodoCheckout.handleOpenURL(url) depuis .onOpenURL, scene(_:openURLContexts:) ou un listener React Native Linking.
• PLATFORM_ERROR sur Android : la cause la plus courante est une incompatibilité de schéma. Cela se produit également lorsque votre MainActivity définit android:taskAffinity="" (la valeur par défaut flutter create), ce qui peut faire perdre le paiement en cours à certaines versions Android des fabricants.
• ALREADY_IN_PROGRESS : un paiement est toujours ouvert. Attendez la fin du précédent ou fermez-le avant d’en démarrer un autre.
• La compilation échoue à cause d’un placeholder non résolu : vous avez ajouté le SDK Android, mais vous n’avez pas défini manifestPlaceholders["dodoCallbackScheme"].
• Le paiement a été effectué, mais l’accès n’a pas été accordé : votre application accorde l’accès à partir du résultat mobile. Accordez plutôt l’accès à partir du webhook payment.succeeded ou subscription.active.
• Apple Pay ou Google Pay n’apparaît pas sur mobile : vérifiez si le paiement se charge dans une WebView intégrée (WKWebView ou Android WebView). Ouvrez-le avec le SDK ou dans le navigateur système : dans un Custom Tab sur Android, ou dans SFSafariViewController ou ASWebAuthenticationSession sur iOS.

​

Ressources supplémentaires

• Guide d’intégration des paiements
• Documentation des webhooks
• Processus de test
• FAQ techniques
• Personnalisation de la session de paiement
• Abonnements à la demande
• Mise à niveau/rétrogradation d’un abonnement
• Abandoned Cart Recovery
• Customer Portal