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.
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.
Instalación
1
Install the Package
- Android
- iOS
- Expo
El paquete se enlaza automáticamente y obtiene La dependencia nativa se resuelve automáticamente, por lo que no se necesita ningún otro paso de instalación.
com.dodopayments.api:checkout-android desde Maven Central.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.En todas las plataformas, establece la misma URL que la
- Android (Gradle)
- iOS (Info.plist)
- Expo (both platforms)
Establece el esquema como un manifest placeholder en Reemplaza
android/app/build.gradle:android/app/build.gradle
"myapp" por el esquema de tu aplicación.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 aDodoCheckout.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 listenerLinking 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.
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.CheckoutStatus
requerido
Uno de cinco valores:
succeeded: la URL de retorno tienestatus=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 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=processingo cualquier valor derequires_*), 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 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.result.status.
Personalización de la apariencia
Para cambiar la toolbar, los botones y el esquema de color del navegador del checkout, pasacustomization 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.
Android — Custom Tab
Android — Custom Tab
string
Color de fondo de la toolbar, como string hexadecimal:
"#RRGGBB" o "#AARRGGBB".Color de la barra de navegación, como string hexadecimal.
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.
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.iOS — SFSafariViewController
iOS — SFSafariViewController
'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.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:checkoutUrlno es una URL de sesión de checkout dehttps(ruta que comienza con/session/) encheckout.dodopayments.comotest.checkout.dodopayments.com.INVALID_RETURN_URL:returnUrlno 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 consucceeded, 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.