Skip to main content
Esta página cubre el SDK oficial de checkout de Dodo Payments para iOS en Swift. Abre el checkout alojado de Dodo Payments en una vista de navegador nativa y devuelve un resultado tipado.

Checkout Sessions API

Crea el checkout_url que abre este SDK desde tu backend.

Mobile Integration Guide

Consulta cómo encaja este SDK en el flujo de pago móvil completo.
El SDK de iOS abre el checkout alojado de Dodo Payments en SFSafariViewController y devuelve un CheckoutResult tipado cuando el cliente termina o abandona el checkout. No contiene ninguna API key ni código de networking, 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. Requisitos: iOS 16 o posterior y Swift 6.2 o posterior (el paquete declara swift-tools-version: 6.2). El SDK no tiene dependencias de terceros.

Instalación

1

Add the Package

En Xcode, ve a File → Add Package Dependencies e introduce la URL del paquete:
Selecciona la versión 1.1.0 o posterior. La personalización de la apariencia requiere la versión 1.1.0.Para añadir el paquete en Package.swift en su lugar, añade esta dependencia:
Package.swift
El producto de la biblioteca es DodoCheckout.
2

Register a Callback URL Scheme

Registra un esquema de URL para que iOS redirija la URL de retorno del checkout a tu app. Añade un tipo de URL a tu Info.plist:
Info.plist
También puedes añadir el tipo de URL en Xcode, en Info → URL Types.Usa este esquema en el returnUrl que pasas al SDK, por ejemplo myapp://checkout/return, y establece la misma URL como return_url de la sesión de checkout cuando tu backend cree la sesión. El SDK compara la URL de retorno según el esquema, el host y la ruta. La URL no necesita cargar una página real.

Uso

DodoCheckout.start es una función async que se ejecuta en el actor principal. Pasa checkoutUrl como un URL creado a partir del checkout_url que devuelve tu backend:
onEvent recibe eventos .opened, .returnReceived y .closed. Sus valores name son checkout.opened, checkout.return_received y checkout.closed. Usa los eventos únicamente para el logging, nunca para decidir el resultado.

Reenvío de la URL de retorno

SFSafariViewController no puede capturar su propia URL de retorno, por lo que iOS abre la URL en tu app. Reenvía cada URL entrante a DodoCheckout.handleOpenURL(_:). En una app sin scenes, llámalo desde el application(_:open:options:) de tu app delegate.
Puedes reenviar cualquier URL. handleOpenURL actúa únicamente sobre una URL que coincida con el returnUrl del checkout en curso y devuelve true para ella. Para cualquier otra URL, devuelve false, así que debes gestionar esa URL por tu cuenta.

Qué significa el resultado

El SDK crea CheckoutResult a partir de los parámetros de consulta de la URL de retorno.
result.status es una indicación de UI, no una prueba de pago. Confirma cada pago desde tu backend, mediante 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 hoja antes de que llegara la URL de retorno. El SDK desconoce el resultado y el pago podría haberse completado, así que no muestres una pantalla de error. Concilia la sesión abandonada en su lugar.
  • pending: el pago se liquida más tarde (status=processing o cualquier valor requires_*), o faltaba el parámetro status o no se reconoció. Concilíalo como cancelled.
  • 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 UI, 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.
[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.
[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 completa correctamente o una suscripción se activa.

Get Payment Detail

Consulta paymentId con tu clave secreta para comprobar su estado.
Concede acceso únicamente después de que una de estas opciones confirme el pago. No dependas solo de result.status.

Personalización de la apariencia

Para cambiar el botón de cierre de la hoja, el estilo de presentación y la combinación de colores, pasa un BrowserCustomization como customization a start(...). Todos los campos son opcionales. Para un campo nil, el SDK no establece esa opción y iOS aplica su propio valor predeterminado. La excepción es presentationStyle, donde nil significa pageSheet.
DismissButtonStyle?
Estilo del botón de cierre: done, close o cancel. iOS decide si se muestra como una etiqueta o un icono.
PresentationStyle?
pageSheet (el valor predeterminado) muestra una tarjeta que el cliente puede deslizar hacia abajo para cerrarla. fullScreen cubre toda la pantalla y no tiene gesto de cierre.
Bool?
Permite que la barra de herramientas se contraiga mientras se desplaza la página. Solo tiene un efecto visible cuando presentationStyle es fullScreen. Con pageSheet, las barras permanecen fijadas independientemente de esta configuración.
ColorScheme?
light o dark fuerza esa apariencia independientemente de la configuración del sistema del dispositivo. system sigue la configuración del sistema. Esta opción aplica el tema únicamente a los controles nativos alrededor de la página. El modo claro u oscuro de la propia página de checkout proviene de customization.theme en la sesión de checkout, y sus colores provienen de customization.theme_config.
iOS no tiene ninguna opción de color para la barra de herramientas. Las propiedades de tintado de SFSafariViewController subyacentes están obsoletas desde iOS 26.

Errores

start lanza CheckoutError únicamente por un uso incorrecto o un fallo de la plataforma. Lee el motivo de error.code. Un cliente que cancela o un pago rechazado siempre es un resultado, nunca un error lanzado.
  • invalidCheckoutUrl (INVALID_CHECKOUT_URL): checkoutUrl no es una URL de sesión de checkout https (ruta que comienza con /session/) en checkout.dodopayments.com o test.checkout.dodopayments.com.
  • invalidReturnUrl (INVALID_RETURN_URL): returnUrl no 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): un fallo inesperado de la plataforma, como no disponer de un controlador de vista desde el que realizar la presentación.
Después de un error lanzado, comprueba también si existe una sesión abandonada. Si la hoja no confirmó que se mostrara, el SDK conserva la sesión registrada porque el checkout podría seguir abierto. La excepción es alreadyInProgress: cualquier registro que encuentres pertenecerá al checkout que sigue en ejecución.

Sesiones abandonadas

El SDK registra la sesión de checkout cuando presenta el checkout y elimina el registro únicamente cuando el checkout termina con succeeded, failed o expired. El registro permanece si la app se cierra durante el checkout y después de un resultado cancelled o pending. Compruébalo en el siguiente lanzamiento 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 checkout Date iniciado. Tu backend puede consultar la sesión con Obtener la 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, React Native y Flutter.

React Native SDK

Envuelve este mismo núcleo de Swift en iOS.
Última modificación el 26 de septiembre de 2026