Skip to main content
Esta página cubre el SDK oficial de checkout de Dodo Payments para React Native, @dodopayments/react-native-checkout. Abre el checkout alojado de Dodo Payments en una vista de navegador nativa y devuelve un resultado tipado. Un paquete anterior, dodopayments-react-native-sdk (sin ámbito), tiene una API diferente. Esta página documenta únicamente el paquete con ámbito.

Checkout Sessions API

Crea el checkout_url que este SDK abre desde tu backend.

Mobile Integration Guide

Consulta cómo encaja este SDK en el flujo completo de pagos móviles.
El SDK de React Native es un Turbo Module que envuelve los SDK de checkout nativos de iOS y Android. Abre SFSafariViewController en iOS y una Custom Tab en Android. No contiene ninguna API key ni lógica de checkout propia, por lo que nunca llama a la API de Dodo Payments. El checkout se ejecuta en la vista del navegador. El SDK muestra y cierra esa vista, y lee el resultado de la URL de retorno.
Este SDK solo admite la New Architecture. Requiere React Native 0.77 o posterior, iOS 16 o posterior y Android minSdk 24. Tu aplicación de Android debe compilarse con compileSdk 34 o posterior.

Instalación

1

Install the Package

El paquete se enlaza automáticamente y obtiene com.dodopayments.api:checkout-android desde Maven Central.
La dependencia nativa se resuelve automáticamente, por lo que no se necesita ningún otro paso de instalación.
La personalización de la apariencia requiere la versión 1.2.0 o posterior.
2

Register a Callback URL Scheme

Registra un esquema de URL para que el sistema operativo dirija la URL de retorno del checkout de vuelta a tu aplicación.
Establece el esquema como un manifest placeholder en android/app/build.gradle:
android/app/build.gradle
Reemplaza "myapp" por el esquema de tu aplicación.
En todas las plataformas, establece la misma URL que la return_url de la sesión de checkout al crear la sesión desde tu backend. El SDK compara la URL de retorno por esquema, host y ruta. La URL no necesita cargar una página real.

Uso

Llama a DodoCheckout.start con el checkout_url de tu backend:
onEvent recibe eventos con un type de checkout.opened, checkout.return_received o checkout.closed. Úsalos únicamente para logging, nunca para decidir el resultado.

Reenvío de la URL de retorno

iOS necesita el listener Linking para gestionar la URL de retorno, porque SFSafariViewController no puede capturar su propia URL de retorno. En Android, handleOpenURL no hace nada y resuelve false, porque el SDK de Android captura su redirect de forma nativa. Puedes registrar el listener en ambas plataformas.
En iOS, handleOpenURL resuelve true cuando la URL pertenece al checkout en curso, y false para cualquier otra URL.

Qué significa el resultado

El SDK construye el resultado a partir de los query parameters de la URL de retorno.
result.status es una indicación de la UI, no una prueba de pago. Confirma cada pago desde tu backend, con el webhook payment.succeeded o subscription.active.
CheckoutStatus
requerido
Uno de cinco valores:
  • succeeded: la URL de retorno tiene 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 no conoce el resultado y el pago podría haberse completado, 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 de 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 query payment_id, cuando la URL de retorno incluye uno. Muéstralo en tu UI, pero no lo uses para conceder acceso. Consulta Verificar el pago.
string
El parámetro de query subscription_id. Se establece para checkouts de suscripción.
string[]
El parámetro de query license_key. Se establece cuando el checkout incluye productos con license keys.
string
El parámetro de query email. Se establece cuando el checkout captura una dirección de email.
Record<string, string>
Cada query parameter de la URL de retorno, de forma literal.

Verificar el pago

Webhooks

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

Get Payment Detail

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

Personalización de la apariencia

Para cambiar la toolbar, los botones y el esquema de color del navegador del checkout, pasa customization a start(...). Las Custom Tabs de Android y SFSafariViewController de iOS exponen controles nativos diferentes, por lo que las opciones se agrupan en un objeto android y un objeto ios. Cada plataforma lee únicamente su propio objeto. Todos los campos son opcionales. Cuando omites un campo, la plataforma aplica su propio valor predeterminado.
string
Color de fondo de la toolbar, como string hexadecimal: "#RRGGBB" o "#AARRGGBB".
string
Color de la barra de navegación, como string hexadecimal.
string
Color del divisor situado sobre la barra de navegación, como string hexadecimal.
'default' | 'back'
default muestra el icono de sistema “X”. back muestra una flecha de volver dibujada por el SDK.
'start' | 'end'
El lado de la toolbar donde aparece el botón de cierre.
boolean
Muestra el icono de compartir de la toolbar. false lo oculta.
boolean
Muestra el título de la página debajo de la URL en la toolbar.
boolean
Oculta la toolbar automáticamente al desplazarse por la página.
boolean
Muestra “Bookmark this page” en el menú de opciones.
boolean
Muestra “Download page” en el menú de opciones.
'system' | 'light' | 'dark'
light o dark fuerza esa apariencia independientemente de la configuración del sistema del dispositivo. system sigue la configuración del sistema.
'done' | 'close' | 'cancel'
Estilo del botón de cierre. iOS decide si se muestra como etiqueta o como icono.
'pageSheet' | 'fullScreen'
pageSheet (el valor predeterminado) muestra una tarjeta que el cliente puede deslizar hacia abajo para cerrarla. fullScreen ocupa toda la pantalla.
boolean
Permite que la toolbar se contraiga al desplazarse por la página. Solo tiene efecto visible cuando presentationStyle es fullScreen. Con pageSheet, las barras permanecen fijadas independientemente de esta configuración.
'system' | 'light' | 'dark'
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 toolbar, porque las propiedades de tint de SFSafariViewController subyacentes están obsoletas desde iOS 26.

Errores

start se rechaza con un CheckoutError únicamente por un uso incorrecto o un fallo de la plataforma. Lee el motivo desde error.code. Un cliente que cancela o un pago rechazado siempre es un resultado, nunca un rechazo.
  • INVALID_CHECKOUT_URL: checkoutUrl no es una URL de sesión de checkout de https (ruta que comienza con /session/) en checkout.dodopayments.com o test.checkout.dodopayments.com.
  • INVALID_RETURN_URL: returnUrl no es una URL absoluta con un esquema y un host.
  • ALREADY_IN_PROGRESS: hay otro checkout en ejecución. Solo puede ejecutarse un checkout a la vez.
  • PLATFORM_ERROR: fallo inesperado de la plataforma. El SDK también informa de cualquier error nativo no reconocido con 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 permanece cuando la aplicación o el bundle de JavaScript se cierran durante el checkout, lo que hace que se pierda la promise start, y después de un resultado cancelled o pending. Compruébalo en el siguiente mount 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 el Date en el que comenzó el checkout. Tu backend puede consultar la sesión con Obtener sesión de checkout, que devuelve su 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 Flutter.

Expo Boilerplate

Un ejemplo completo de Expo con integración de checkout.
Última modificación el 26 de septiembre de 2026