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.
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 El producto de la biblioteca es
Package.swift en su lugar, añade esta dependencia:Package.swift
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 También puedes añadir el tipo de URL en Xcode, en Info → URL Types.Usa este esquema en el
Info.plist:Info.plist
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.
- SwiftUI
- SceneDelegate
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 creaCheckoutResult a partir de los parámetros de consulta 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 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=processingo cualquier valorrequires_*), o faltaba el parámetrostatuso no se reconoció. Concilíalo comocancelled.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.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 unBrowserCustomization 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.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):checkoutUrlno es una URL de sesión de checkouthttps(ruta que comienza con/session/) encheckout.dodopayments.comotest.checkout.dodopayments.com.invalidReturnUrl(INVALID_RETURN_URL):returnUrlno 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.
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.