Skip to main content
Esta página cubre el paquete oficial de Dodo Payments para Flutter, dodopayments_checkout en pub.dev. También existe un paquete independiente creado por la comunidad. Consulta Proyectos de la comunidad.

Checkout Sessions API

Crea desde tu backend el checkout_url que abre este SDK.

Mobile Integration Guide

Consulta cómo encaja este SDK en el flujo completo de pagos móviles.
dodopayments_checkout abre el checkout alojado de Dodo Payments en SFSafariViewController en iOS y en una pestaña personalizada en Android, y devuelve un CheckoutResult tipado. Utiliza el mismo código nativo que los SDK independientes de iOS y Android, y toda la lógica del checkout reside en ese código nativo. La capa de Dart transmite cada llamada mediante un canal tipado de Pigeon. El paquete no contiene ninguna clave de API y nunca llama a la API de Dodo Payments. Requisitos: Flutter 3.44 o posterior con Dart 3.12 o posterior, iOS 16 o posterior y Android minSdk 23.

Instalación

1

Add the Dependency

Añade el paquete a pubspec.yaml:
pubspec.yaml
La personalización de la apariencia requiere la versión 1.1.0 o posterior.El plugin de Android compila con Android SDK 35 de forma predeterminada. Si otro plugin necesita un compileSdk superior, establece dodoCompileSdk en el gradle.properties de tu aplicación.
2

Register a Callback URL Scheme

Registra un esquema de URL para que el sistema operativo redirija la URL de retorno del checkout a tu aplicación. Usa este esquema en el returnUrl que pasas al SDK y establece la misma URL como return_url de la sesión de checkout cuando tu backend cree la sesión. La URL no necesita cargar una página real.
Añade un tipo de URL para tu esquema en ios/Runner/Info.plist:
ios/Runner/Info.plist
SFSafariViewController no puede interceptar su propia URL de retorno, por lo que iOS abre la URL en tu aplicación. Reenvía todas las URL entrantes al SDK, por ejemplo desde app_links:
Puedes reenviar todas las URL. handleOpenURL solo actúa sobre una URL que coincida con el returnUrl del checkout en curso y resuelve true para ella. Para cualquier otra URL, resuelve false. En Android, siempre resuelve false.

Uso

Llama a DodoCheckout.instance.start con el checkout_url de tu backend:
onEvent recibe eventos cuyo type es CheckoutEventType.opened, returnReceived o closed. Úsalos solo para el registro, nunca para decidir el resultado.

Qué significa el resultado

El SDK crea CheckoutResult a partir de los parámetros de consulta de la URL de retorno.
result.status es una indicación de la interfaz, no una prueba del pago. Confirma cada pago desde tu backend, mediante el webhook payment.succeeded o subscription.active.
CheckoutStatus
requerido
Uno de cinco valores:
  • succeeded: la URL de retorno contiene status=succeeded (pago único) o status=active (suscripción).
  • failed: el pago fue rechazado (status=failed).
  • cancelled: el cliente cerró la vista del navegador antes de que llegara la URL de retorno. El SDK desconoce el resultado y el pago podría haberse realizado correctamente, así que no muestres una pantalla de error. Reconcilia la sesión abandonada en su lugar.
  • pending: el pago se liquida más tarde (status=processing o cualquier valor requires_*), o faltaba el parámetro status o no se reconoció. Reconcílialo como cancelled.
  • expired: la sesión de checkout expiró (status=expired).
String?
El parámetro de consulta payment_id, cuando la URL de retorno incluye uno. Muéstralo en tu interfaz, pero no lo uses para conceder acceso. Consulta Verificar el pago.
String?
El parámetro de consulta subscription_id. Se establece para los checkouts de suscripción.
List<String>?
El parámetro de consulta license_key. Se establece cuando el checkout incluye productos con claves de licencia.
String?
El parámetro de consulta email. Se establece cuando el checkout captura una dirección de correo electrónico.
Map<String, String>
Cada parámetro de consulta de la URL de retorno, sin modificar.

Verificar el pago

Webhooks

Dodo Payments llama a tu backend cuando un pago se realiza correctamente o se activa una suscripción.

Get Payment Detail

Busca paymentId con tu clave secreta para comprobar su estado.
Concede acceso solo después de que uno de estos confirme el pago. No dependas únicamente de result.status.

Personalización de la apariencia

Para cambiar la barra de herramientas, los botones y el esquema de colores del navegador del checkout, pasa un BrowserCustomization como customization en CheckoutParams. Las pestañas personalizadas de Android y SFSafariViewController de iOS exponen controles nativos diferentes, por lo que las opciones se dividen en AndroidBrowserOptions y IosBrowserOptions. Cada plataforma ignora las opciones de la otra. Todos los campos son opcionales y, de forma predeterminada, tienen el valor null. Para un campo null, el SDK no establece esa opción y la plataforma aplica su propio valor predeterminado.
Color?
Color de fondo de la barra de herramientas.
Color?
Color de la barra de navegación.
Color?
Color del separador situado sobre la barra de navegación.
CloseButtonStyle?
standard muestra el icono de sistema “X”. back muestra una flecha de retroceso dibujada por el SDK.
CloseButtonPosition?
El lado de la barra de herramientas donde aparece el botón de cierre: start o end.
bool?
Muestra el icono de compartir de la barra de herramientas. false lo oculta.
bool?
Muestra el título de la página debajo de la URL en la barra de herramientas.
bool?
Oculta automáticamente la barra de herramientas cuando se desplaza la página.
bool?
Muestra “Añadir esta página a marcadores” en el menú adicional.
bool?
Muestra “Descargar página” en el menú adicional.
BrowserColorScheme?
light o dark fuerza esa apariencia independientemente de la configuración del sistema del dispositivo. system sigue la configuración del sistema.
DismissButtonStyle?
Estilo del botón de descarte: done, close o cancel. iOS decide si lo representa como una etiqueta o como un icono.
PresentationStyle?
pageSheet (se utiliza cuando dejas este null) presenta una tarjeta que el cliente puede deslizar hacia abajo para descartarla. fullScreen cubre toda la pantalla.
bool?
Permite que la barra de herramientas se contraiga al desplazar la página. Solo tiene efecto visible cuando presentationStyle es fullScreen. Con pageSheet, las barras permanecen fijadas independientemente de esta configuración.
BrowserColorScheme?
light o dark fuerza esa apariencia independientemente de la configuración del sistema del dispositivo. system sigue la configuración del sistema.
iOS no tiene ninguna opción de color para la barra de herramientas, porque las propiedades de tintado subyacentes de SFSafariViewController están obsoletas desde iOS 26.

Errores

start lanza CheckoutException únicamente por un uso incorrecto o un fallo de la plataforma. Lee el motivo de code, un CheckoutErrorCode. La cadena de código nativa se encuentra en nativeCode. La cancelación por parte de un cliente o un pago rechazado siempre es un resultado, nunca una excepción.
  • invalidCheckoutUrl (INVALID_CHECKOUT_URL): checkoutUrl no es una URL de sesión de checkout https (ruta que comienza con /session/) en checkout.dodopayments.com o test.checkout.dodopayments.com.
  • invalidReturnUrl (INVALID_RETURN_URL): returnUrl no es una URL absoluta con un esquema y un host.
  • alreadyInProgress (ALREADY_IN_PROGRESS): hay otro checkout en ejecución. Solo puede ejecutarse un checkout a la vez.
  • platformError (PLATFORM_ERROR): se produjo un fallo inesperado de la plataforma. Los errores nativos desconocidos también se asignan a este código.

Sesiones abandonadas

El SDK nativo registra la sesión de checkout cuando comienza el checkout y elimina el registro únicamente cuando el checkout termina con succeeded, failed o expired. El registro se conserva si se cierra la aplicación durante el checkout y después de un resultado cancelled o pending. Comprueba si existe en el siguiente inicio y después de cada resultado cancelled o pending.
abandoned.sessionId es el ID de la sesión de checkout, que comienza con cks_. abandoned.createdAt es la hora en que comenzó el checkout DateTime. Tu backend puede buscar la sesión mediante Obtener sesión de checkout, que devuelve sus valores payment_id y payment_status. Hasta que el pago alcance un estado final, trátalo como pendiente, no como fallido.

Relacionado

Mobile Integration Guide

El mismo contrato para Android, iOS y React Native.

Community Projects

También existe un paquete independiente de Flutter creado por la comunidad.
Última modificación el 26 de septiembre de 2026