React Native

Este es el SDK oficial de checkout de Dodo Payments para React Native, @dodopayments/react-native-checkout. Abre el checkout alojado de Dodo en una vista de navegador nativa y devuelve un resultado tipado. Nota: existe un paquete anterior no relacionado llamado dodopayments-react-native-sdk (sin ámbito) con una API completamente diferente. Esta página documenta únicamente el paquete oficial actual con ámbito.

Checkout Sessions API

Crea 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.

El SDK de React Native es un envoltorio delgado de Turbo Module sobre los mismos núcleos nativos de Swift y Kotlin. Abre SFSafariViewController en iOS y una pestaña personalizada de Chrome en Android, no contiene ninguna clave de API y nunca llama directamente a la API de Dodo. Toda la lógica del checkout se ejecuta en el navegador; el SDK simplemente administra el ciclo de vida de la vista y captura la URL de retorno.

Este SDK requiere únicamente New Architecture, React Native 0.76+, iOS 16+ y Android minSdk 24.

Instalación

Install the Package

Android
iOS
Expo

El paquete se enlaza automáticamente y obtiene com.dodopayments.api:checkout-android desde Maven.

npm i @dodopayments/react-native-checkout

No se necesita configuración adicional; la dependencia nativa se resuelve automáticamente.

npm i @dodopayments/react-native-checkout
cd ios && pod install

El núcleo de Swift se incluye en el paquete y se instala mediante CocoaPods.

Solo para compilaciones de desarrollo (no Expo Go).

npm i @dodopayments/react-native-checkout

A continuación, configura tu app.json (consulta Registrar un esquema de URL de callback más abajo).

Tu aplicación debe registrar un esquema de URL para recibir la URL de retorno del checkout.

Android (Gradle)
iOS (Info.plist)
Expo (both platforms)

En android/app/build.gradle:

android/app/build.gradle

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

Sustituye "myapp" por el esquema de tu aplicación.

En ios/YourApp/Info.plist:

Info.plist

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

También puedes añadir esto mediante la interfaz de usuario Info → URL Types de Xcode.

El propio config plugin del paquete registra el esquema para ambas plataformas en prebuild. Pásale una opción scheme en app.json:

app.json

{
  "expo": {
    "scheme": "myapp",
    "plugins": [
      [
        "@dodopayments/react-native-checkout",
        { "scheme": "myappcheckout" }
      ]
    ]
  }
}

scheme debe coincidir con lo que pasas como returnUrl (por ejemplo, myappcheckout://return), y debe ser diferente de expo.scheme. Expo ya registra ese en MainActivity, y reutilizarlo puede dirigir el retorno del checkout a la pantalla equivocada.Vuelve a compilar el proyecto nativo después de editar app.json:

npx expo prebuild --clean

Esto solo funciona con development builds, no con Expo Go.Si android/app/build.gradle se mantiene manualmente y no tiene un bloque defaultConfig { } estándar que el plugin pueda encontrar, añade el marcador tú mismo. Consulta la pestaña de Android anterior.

Uso

import { Linking } from 'react-native';
import { DodoCheckout } from '@dodopayments/react-native-checkout';

// Required for iOS's return-URL handling.
Linking.addEventListener('url', ({ url }) => DodoCheckout.handleOpenURL(url));

const result = await DodoCheckout.start({
  checkoutUrl,                          // from your backend's checkout session
  returnUrl: 'myapp://checkout/return', // scheme must be registered (see Installation)
  onEvent: (e) => console.log(e.type),  // logging only
});

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

Reenvío de la URL de retorno

El listener Linking es necesario para gestionar la URL de retorno en iOS. En Android, handleOpenURL es un no-op que resuelve false porque el core de Android gestiona su redirección de forma nativa. Es seguro registrar el listener incondicionalmente en ambas plataformas.

import { Linking } from 'react-native';
import { DodoCheckout } from '@dodopayments/react-native-checkout';

Linking.addEventListener('url', ({ url }) => {
  DodoCheckout.handleOpenURL(url);
});

Qué significa el resultado

result.status es una indicación de UI, 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 UI; no lo uses para conceder acceso. Consulta Verificar el pago más abajo.

string

Se establece para los checkouts de suscripciones.

string[]

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

string

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

Record<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

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

Concede acceso después de que uno de estos confirme el pago; nunca 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 start(...). Las opciones están agrupadas por plataforma porque Custom Tab de Android y SFSafariViewController de iOS exponen diferentes controles nativos. Todos los campos son opcionales; omitir customization 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.

'default' | 'back'

default muestra el icono de sistema «X»; back dibuja una flecha de retroceso en su lugar.

'start' | 'end'

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

Muestra el icono de compartir de la barra de herramientas.

boolean

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

boolean

Permite que la barra de herramientas se oculte automáticamente mientras se desplaza la página.

boolean

Muestra «Añadir esta página a marcadores» en el menú de opciones.

boolean

Muestra «Descargar página» en el menú de opciones.

'system' | 'light' | 'dark'

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

iOS — SFSafariViewController

'done' | 'close' | 'cancel'

Etiqueta o icono del botón para descartar.

'pageSheet' | 'fullScreen'

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

boolean

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

'system' | 'light' | 'dark'

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

const result = await DodoCheckout.start({
  checkoutUrl,
  returnUrl: 'myapp://checkout/return',
  customization: {
    android: { toolbarColor: '#6366F1', closeButtonStyle: 'back' },
    ios: { presentationStyle: 'fullScreen', colorScheme: 'dark' },
  },
});

Errores

start rechaza con un CheckoutError solo en caso de uso incorrecto o de un fallo de la plataforma. Un pago cancelado o rechazado siempre es un resultado, nunca una excepción.

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

Sesiones abandonadas

Si la app o el paquete JS se cierra durante el checkout, la promise se pierde, pero la capa nativa conserva la sesión. Recupérala en el siguiente mount y reconcilia su estado con tu backend.

import { DodoCheckout } from '@dodopayments/react-native-checkout';

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

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Checkout Sessions API

Mobile Integration Guide

Instalación

Uso

Reenvío de la URL de retorno

Qué significa el resultado

Verificar el pago

Webhooks

Get Payment Detail

Personalización de la apariencia

Errores

Sesiones abandonadas

Relacionado

Mobile Integration Guide

Expo Boilerplate

Checkout Sessions API

Mobile Integration Guide

​Instalación

​Uso

​Reenvío de la URL de retorno

​Qué significa el resultado

​Verificar el pago

Webhooks

Get Payment Detail

​Personalización de la apariencia

​Errores

​Sesiones abandonadas

​Relacionado

Mobile Integration Guide

Expo Boilerplate

Instalación

Uso

Reenvío de la URL de retorno

Qué significa el resultado

Verificar el pago

Personalización de la apariencia

Errores

Sesiones abandonadas

Relacionado