Flutter

Este es el paquete oficial de Dodo Payments para Flutter (dodopayments_checkout en pub.dev). También existe un paquete independiente desarrollado por la comunidad; consulta Proyectos de la comunidad.

Checkout Sessions API

Crea el checkout_url que este SDK abre desde tu backend.

Mobile Integration Guide

Consulta cómo encaja esto en el flujo de pago móvil completo.

dodopayments_checkout abre el checkout alojado de Dodo en SFSafariViewController en iOS y en una pestaña personalizada de Chrome en Android: los mismos núcleos nativos que utilizan los SDK independientes de iOS y Android. Toda la lógica del checkout reside en esos núcleos nativos; la capa de Dart pasa la llamada a través de un canal Pigeon tipado. No contiene ninguna API key ni realiza llamadas a la API de Dodo Payments. Requiere Flutter 3.44+ / Dart 3.12+, iOS 16+ y Android minSdk 23.

Instalación

Add the Dependency

pubspec.yaml

dependencies:
  dodopayments_checkout: ^1.0.0

iOS
Android

Añade un tipo URL para tu esquema en ios/Runner/Info.plist:

ios/Runner/Info.plist

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

Después, reenvía las URL entrantes (por ejemplo, mediante app_links) al SDK, porque SFSafariViewController no puede detectar su propia URL de retorno:

import 'package:dodopayments_checkout/dodopayments_checkout.dart';

DodoCheckout.instance.handleOpenURL(url);

Es seguro reenviar aquí todas las URL. handleOpenURL solo actúa sobre las URL que coinciden con tu returnUrl registrado y resuelve false para cualquier otra URL.

Configura tu esquema de callback como un placeholder del manifiesto de Gradle:

android/app/build.gradle

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

Si MainActivity configura android:taskAffinity="" (el valor predeterminado de flutter create), elimínalo o asigna a las activities del SDK la misma affinity. De lo contrario, algunas compilaciones de Android de ciertos OEM pueden perder el checkout en curso y devolver PLATFORM_ERROR.

Uso

import 'package:dodopayments_checkout/dodopayments_checkout.dart';

final result = await DodoCheckout.instance.start(
  CheckoutParams(
    checkoutUrl: Uri.parse(checkoutUrl), // from your backend's checkout session
    returnUrl: Uri.parse('myapp://checkout/return'), // scheme must be registered (see Setup)
    onEvent: (event) => print(event.type), // logging only
  ),
);

switch (result.status) {
  case CheckoutStatus.succeeded: showSuccess(result.paymentId);
  case CheckoutStatus.failed:    showFailure();
  case CheckoutStatus.cancelled: dismiss();
  case CheckoutStatus.pending:   showPending();
  case CheckoutStatus.expired:   showExpired();
}

Qué significa el resultado

result.status 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.

CheckoutStatus

requerido

Uno de succeeded, failed, cancelled, pending, expired.

String?

Se establece cuando la URL de retorno incluía uno. Muéstralo en la interfaz; no lo uses para conceder acceso. Consulta Verificar el pago más abajo.

String?

Se establece para los checkouts de suscripciones.

List<String>?

Se establece cuando el checkout incluye productos con claves de licencia.

String?

Se establece cuando el checkout captura un correo electrónico.

Map<String, String>

Cada parámetro de consulta de la URL de retorno, literalmente.

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

Consulta paymentId con tu secret key para comprobar su estado directamente.

Concede acceso después de que uno de estos confirme el pago; nunca lo hagas basándote únicamente en result.status.

Personalización de la apariencia

Personaliza la barra de herramientas, los botones y la combinación de colores del navegador de checkout mediante customization en CheckoutParams. Las opciones están agrupadas por plataforma porque Custom Tab de Android y SFSafariViewController de iOS exponen distintos controles nativos. Todos los campos son opcionales; si omites customization, se utiliza la apariencia predeterminada de cada plataforma.

Android — Custom Tab

Color de fondo de la barra de herramientas.

Color de la barra de navegación.

Color del separador sobre la barra de navegación.

CloseButtonStyle

standard muestra el icono de sistema “X”; back dibuja una flecha de retroceso en su lugar.

CloseButtonPosition

En qué lado de la barra de herramientas aparece el botón de cierre.

Muestra el icono de compartir de la barra de herramientas.

bool

Muestra el título de la página debajo de la URL en la barra de herramientas.

bool

Permite que la barra de herramientas se oculte automáticamente mientras 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

Fuerza la apariencia clara u oscura independientemente de la configuración del sistema del dispositivo.

iOS — SFSafariViewController

DismissButtonStyle

Etiqueta o icono del botón de descartar.

PresentationStyle

pageSheet se muestra como una tarjeta que se puede descartar deslizando; fullScreen cubre toda la pantalla.

bool

Permite que la barra de herramientas se contraiga al desplazarse. Solo está visible cuando presentationStyle es fullScreen; pageSheet mantiene las barras fijadas independientemente de esta configuración.

BrowserColorScheme

Fuerza la apariencia clara u oscura independientemente de la configuración del sistema del dispositivo.

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

Errores

start lanza CheckoutException únicamente por un uso incorrecto o un fallo de la plataforma. Un pago cancelado o rechazado siempre es un resultado, nunca una excepción.

invalidCheckoutUrl (INVALID_CHECKOUT_URL): no es una URL de sesión de checkout.dodopayments.com.
invalidReturnUrl (INVALID_RETURN_URL): no es una URL absoluta válida.
alreadyInProgress (ALREADY_IN_PROGRESS): ya hay un checkout en ejecución.
platformError (PLATFORM_ERROR): fallo inesperado de la plataforma.

Sesiones abandonadas

Si la aplicación se cierra durante el checkout, recupera la sesión en el siguiente inicio y reconcíliala con tu backend.

import 'package:dodopayments_checkout/dodopayments_checkout.dart';

final abandoned = await DodoCheckout.instance.getAbandonedSession();
if (abandoned != null) {
  // reconcile abandoned.sessionId with your backend, then:
  await DodoCheckout.instance.clearAbandonedSession();
}

Relacionado

Mobile Integration Guide

El mismo contrato para Android, iOS y React Native.

Community Projects

También existe un paquete de Flutter independiente desarrollado por la comunidad.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Checkout Sessions API

Mobile Integration Guide

Instalación

Uso

Qué significa el resultado

Verificar el pago

Webhooks

Get Payment Detail

Personalización de la apariencia

Errores

Sesiones abandonadas

Relacionado

Mobile Integration Guide

Community Projects

Checkout Sessions API

Mobile Integration Guide

​Instalación

​Uso

​Qué significa el resultado

​Verificar el pago

Webhooks

Get Payment Detail

​Personalización de la apariencia

​Errores

​Sesiones abandonadas

​Relacionado

Mobile Integration Guide

Community Projects

Instalación

Uso

Qué significa el resultado

Verificar el pago

Personalización de la apariencia

Errores

Sesiones abandonadas

Relacionado