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 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
pubspec.yaml:pubspec.yaml
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.- iOS
- Android
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 aDodoCheckout.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 creaCheckoutResult a partir de los parámetros de consulta de la URL de retorno.
CheckoutStatus
requerido
Uno de cinco valores:
succeeded: la URL de retorno contienestatus=succeeded(pago único) ostatus=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=processingo cualquier valorrequires_*), o faltaba el parámetrostatuso no se reconoció. Reconcílialo comocancelled.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.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 unBrowserCustomization 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.
Android — Custom Tab
Android — Custom Tab
Color?
Color de fondo de la barra de herramientas.
Color de la barra de navegación.
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.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.iOS — SFSafariViewController
iOS — SFSafariViewController
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.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):checkoutUrlno es una URL de sesión de checkouthttps(ruta que comienza con/session/) encheckout.dodopayments.comotest.checkout.dodopayments.com.invalidReturnUrl(INVALID_RETURN_URL):returnUrlno 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.