Mobile Integration Guide

Unified guide for integrating Dodo Payments into Android, iOS, React Native and Flutter mobile applications.

Quick Start

Get your mobile payment integration running in 4 simple steps

Platform Examples

Ejemplos de código completos para Android, iOS, React Native y Flutter

Dodo Payments ofrece un SDK oficial de checkout para Android, iOS, React Native, y Flutter. Cada uno encapsula el patrón documentado a continuación (abrir la URL de checkout, capturar el retorno, analizar el resultado) detrás de una única llamada tipada start(...), con recuperación de sesiones abandonadas integrada. Utiliza un WebView manual solo si ninguno se adapta a tu stack.

​

Requisitos previos

Antes de integrar Dodo Payments en tu aplicación móvil, asegúrate de tener:

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

​

Flujo de integración

La integración móvil sigue un proceso seguro de 4 pasos en el que tu backend gestiona las llamadas a la API y tu aplicación móvil gestiona la experiencia del usuario.

1. Backend: Create Checkout Session

   Checkout Session API Docs

   Aprende a crear una sesión de checkout en tu backend usando Node.js, Python y más. Consulta ejemplos completos y referencias de parámetros en la documentación específica de Checkout Sessions API.

   Seguridad: Las sesiones de checkout deben crearse en tu servidor backend, nunca en la aplicación móvil. Esto protege tus claves de API y garantiza una validación adecuada.

2. Mobile: Get Checkout URL

   Tu aplicación móvil llama a tu backend para obtener la URL de checkout. Autentica esta solicitud con el token de sesión propio del usuario que ha iniciado sesión.

   iOS (Swift)

   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
   }
   

   Android (Kotlin)

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

   React Native (JavaScript)

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

   Flutter (Dart)

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

   Seguridad: Las aplicaciones móviles solo se comunican con tu backend, nunca directamente con Dodo Payments API.

3. Mobile: Open Checkout in Browser

   Abre la URL de checkout en un navegador seguro integrado en la aplicación para procesar el pago. También puedes omitir por completo la configuración manual con el SDK oficial de checkout para tu plataforma.

   Pick your mobile SDK

   Pasos de instalación e instrucciones de configuración para Android, iOS, React Native y Flutter.

4. Backend: Handle Payment Completion

   Procesa la finalización del pago mediante webhooks y URL de redirección para confirmar el estado del pago.

​

Elige tu SDK

Todos los SDK móviles exponen el mismo contrato: una llamada start(...) abre el checkout alojado de Dodo en la superficie de navegador nativa de la plataforma y devuelve un CheckoutResult tipado cuyo status es succeeded, failed, cancelled, pending o expired. Ninguno almacena una clave de API ni llama a Dodo Payments API, y los cuatro admiten la recuperación de sesiones abandonadas.

Android

com.dodopayments.api:checkout-android abre una pestaña personalizada de Chrome. Requiere minSdk 23.

iOS

dodopayments-mobile-sdk-ios abre SFSafariViewController. Requiere iOS 16 o posterior.

React Native

@dodopayments/react-native-checkout, un Turbo Module sobre ambos núcleos nativos. Requiere React Native 0.76 o posterior.

Flutter

dodopayments_checkout, un canal Pigeon sobre ambos núcleos nativos. Requiere Flutter 3.44 o posterior.

El status que recibes es una indicación de la interfaz, no una prueba de pago. Confirma cada pago desde tu backend mediante el webhook payment.succeeded / subscription.active, o recuperando el pago con tu clave secreta.

​

Registrar un esquema de URL de callback

Los cuatro SDK devuelven el control a tu aplicación mediante un esquema de URL personalizado que eliges, por ejemplo myapp://checkout/return. Regístralo una vez por plataforma:

Android

android/app/build.gradle

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

El propio manifest del SDK ya declara la actividad de redirección, por lo que no hay ningún XML de manifest que añadir.

iOS

Info.plist

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

En iOS también debes reenviar las URL entrantes al SDK, porque SFSafariViewController no puede capturar su propia URL de retorno. Consulta la página de iOS o de React Native para obtener el handler exacto.

Expo

npx expo install expo-build-properties

app.json

{
  "expo": {
    "plugins": [
      [
        "expo-build-properties",
        { "android": { "manifestPlaceholders": { "dodoCallbackScheme": "myapp" } } }
      ]
    ],
    "ios": {
      "infoPlist": {
        "CFBundleURLTypes": [{ "CFBundleURLSchemes": ["myapp"] }]
      }
    }
  }
}

@dodopayments/react-native-checkout también incluye un plugin de configuración de Expo, pero actualmente no escribe ningún esquema de URL ni ningún marcador de posición del manifest. Añadirlo por sí solo no registrará tu esquema de callback; utiliza la configuración anterior. Consulta la página del SDK de React Native.

Funciona únicamente con builds de desarrollo, no con Expo Go. Ejecuta npx expo prebuild --clean después de editar app.json.

¿Prefieres crearlo tú mismo? Abre checkout_url en un WebView e intercepta la navegación hacia tu return_url; después, lee los parámetros de consulta status y payment_id. Los SDK anteriores hacen esto por ti en la superficie de navegador real de la plataforma, por eso Apple Pay y Google Pay siguen funcionando.

​

Prácticas recomendadas

• Seguridad: Nunca incluyas una clave de API en tu aplicación. Crea sesiones de checkout en tu backend y pasa únicamente el checkout_url resultante al cliente.
• Autoridad: Trata CheckoutResult.status como una indicación de la interfaz. Concede acceso solo después de que tu backend confirme el pago.
• Experiencia del 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: Utiliza el modo de prueba y tarjetas de prueba, y verifica el recorrido de ida y vuelta de la URL de retorno en un dispositivo real y también en un simulador.

​

Solución de problemas

​

Problemas comunes

• El callback nunca llega: El esquema de returnUrl debe coincidir con el que registraste. En Android es el marcador de posición del 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 de React Native Linking.
• PLATFORM_ERROR en Android: Lo más habitual es que haya una discrepancia en el esquema. También puede aparecer si tu MainActivity establece android:taskAffinity="" (el valor predeterminado estándar de flutter create), lo que puede hacer que algunos builds de OEM pierdan el checkout en curso.
• ALREADY_IN_PROGRESS: Hay un checkout todavía abierto. Espera a que finalice o descarta el anterior antes de iniciar otro.
• El build falla con un marcador de posición sin resolver: 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 utilizas el resultado móvil como fuente de verdad. Concede acceso desde el webhook payment.succeeded / subscription.active.

​

Recursos adicionales

• Guía de integración de pagos
• Documentación de webhooks
• Proceso de pruebas
• Preguntas frecuentes técnicas

Para preguntas o asistencia, contacta con [e-mail].