Mobile Integration Guide

​

Requisitos previos

• Cuenta de Dodo Payments: Cuenta de comerciante activa con acceso a la API
• Credenciales de API: Clave de API y clave secreta de webhook desde tu dashboard
• Proyecto de aplicación móvil: Aplicación Android, iOS, React Native o Flutter
• Servidor backend: Para gestionar de forma segura la creación de sesiones de checkout

​

Flujo de integración

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;
}

​

Elige tu SDK

​

Registrar un esquema de 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" }
      ]
    ]
  }
}

​

Personalización de la apariencia

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
    )
)

​

Personalización de la página de checkout

​

Recetas optimizadas para móviles

Minimal Mobile Checkout - fastest path to payment

Úsala cuando quieras el formulario más corto posible: métodos de pago en la parte superior, solo se requiere un código postal para la dirección, sin campo de descuento y con un tema que coincide con el dispositivo.

• 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

Consulta Checkout Sessions para ver todos los parámetros disponibles y sus valores predeterminados.

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

Úsala cuando la página de checkout deba sentirse integrada en tu aplicación. Establece los colores de tu marca, una fuente personalizada y una etiqueta localizada para el botón de pago.

• 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 acepta objetos separados dark y light para que la paleta se adapte a la apariencia actual del dispositivo. Consulta Checkout Sessions para ver la referencia completa de las claves de color.

One-Click Returning Customer - saved card, instant confirmation

Úsala para usuarios autenticados que ya hayan pagado anteriormente. Combina un ID de cliente, su método de pago guardado e confirm: true para omitir por completo el formulario 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

El status del retorno mediante deep link es únicamente una indicación de UI. Confirma el acceso escuchando el webhook payment.succeeded en tu backend.

Subscription with Free Trial - trial before first charge

Úsala para productos de suscripción que ofrecen un periodo de prueba gratuito antes del primer ciclo de facturación.

• 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

Concede acceso a las funcionalidades cuando tu backend reciba el webhook subscription.active, no cuando el SDK móvil devuelva el resultado. Consulta la Subscription Integration Guide para ver el flujo completo del webhook.

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

Úsala para tokenizar la tarjeta de un cliente para cargos posteriores (recargas de wallet, pago por uso, BNPL) sin mostrar la etiqueta «subscription». El cliente autoriza su método de pago una vez; después puedes realizar cargos variables on-demand.

Este es el patrón utilizado por las aplicaciones que cobran según el uso, por ejemplo, una aplicación de astrología que cobra por sesión desde una tarjeta preautorizada, en lugar de hacerlo según un calendario fijo.

• 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

Los cargos on-demand requieren un mínimo de 1 USD (100 centavos). Los importes inferiores a 1 USD se rechazarán con "value out of range". Para una autorización de importe cero, usa mandate_only: true como se muestra arriba y, después, cobra al menos 1 USD en las llamadas posteriores.

Consulta On-Demand Subscriptions para ver el flujo completo de cargos, los eventos de webhook y las políticas de reintento.

​

Flujos de suscripción desde dispositivos móviles

​

Suscripciones recurrentes normales

​

Suscripciones on-demand

• Establece show_on_demand_tag: false para que la página de checkout no muestre lenguaje relacionado con «subscription» u «on-demand». En casos de tokenización de tarjetas, los clientes no esperan terminología de suscripción.
• Después de autorizar el mandato, tu backend recibe subscription.active. Guarda subscription_id; lo utilizarás para todos los cargos futuros.

​

Suscripción con prueba gratuita

​

Mejoras y reducciones de plan

​

Reducir el abandono del checkout

​

Optimizar el formulario

​

Prellenar los datos del cliente

• Clientes nuevos: establece customer.email e customer.name desde tu sesión de autenticación.
• Clientes recurrentes: establece customer.customer_id para prellenar automáticamente todos los datos guardados.
• Moneda: pasa siempre billing_currency y billing_address.country juntos.

​

Herramientas de recuperación

​

Prácticas recomendadas

• Seguridad: Nunca incluyas una clave de API en tu aplicación. Crea sesiones de checkout en tu backend y pasa al cliente únicamente la checkout_url resultante.
• Autoridad: Trata CheckoutResult.status como una indicación de UI. Concede acceso solo después de que tu backend confirme el pago.
• Experiencia de usuario: Muestra un estado de carga mientras tu backend crea la sesión y gestiona cancelled como un resultado normal, no como un error.
• Pruebas: Usa el modo de prueba y tarjetas de prueba, y verifica el recorrido de ida y vuelta de la return-URL en un dispositivo real y en un simulador.
• Conversión: Establece show_order_details: false e minimal_address: true para obtener las mejores tasas de finalización del checkout móvil. Mover los métodos de pago above the fold y reducir los campos del formulario son los dos cambios de mayor impacto que puedes realizar.
• Moneda: Pasa siempre explícitamente billing_currency y billing_address.country; si falta cualquiera de ellos, Adaptive Currency puede cambiar la moneda de facturación según la dirección IP del cliente.
• Facturación on-demand: Establece show_on_demand_tag: false al utilizar suscripciones on-demand para tokenizar tarjetas. Los clientes que usan un flujo de recarga de wallet no esperan ver lenguaje relacionado con «subscription».
• Recuperación: Activa la recuperación de carritos abandonados en tu dashboard de Dodo Payments para volver a captar automáticamente a los clientes que no completan el checkout.

​

Solución de problemas

​

Problemas habituales

• El callback nunca llega: El esquema de returnUrl debe coincidir con el que registraste. En Android es el placeholder de manifest dodoCallbackScheme; en iOS y React Native es el tipo de URL Info.plist.
• El checkout vuelve al navegador en lugar de a tu aplicación (iOS): No has reenviado la URL entrante. Llama a DodoCheckout.handleOpenURL(url) desde .onOpenURL, scene(_:openURLContexts:) o un listener Linking de React Native.
• PLATFORM_ERROR en Android: Normalmente se debe a una discrepancia en el esquema. También puede aparecer si MainActivity establece android:taskAffinity="" (el valor predeterminado estándar flutter create), lo que puede hacer que algunos builds de OEM pierdan el checkout en curso.
• ALREADY_IN_PROGRESS: Hay un checkout abierto. Espera a que finalice o descarta el anterior antes de iniciar otro.
• El build falla por un placeholder no resuelto: Añadiste el SDK de Android, pero nunca estableciste manifestPlaceholders["dodoCallbackScheme"].
• El pago se realizó correctamente, pero no se concedió acceso: Es lo esperado si te basas en el resultado móvil. Concede el acceso desde el webhook payment.succeeded / subscription.active.
• Apple Pay / Google Pay no aparecen en móviles: El checkout se está cargando dentro de un WebView integrado (WKWebView / Android WebView), que suprime las wallets y puede interrumpir 3-D Secure. Ábrelo con el SDK o en el navegador del sistema (Custom Tabs / SFSafariViewController).

​

Recursos adicionales

• Guía de integración de pagos
• Documentación de Webhooks
• Proceso de pruebas
• Preguntas frecuentes técnicas
• Personalización de la sesión de checkout
• On-Demand Subscriptions
• Mejora/reducción de suscripción
• Recuperación de carritos abandonados
• Customer Portal