> ## Documentation Index
> Fetch the complete documentation index at: https://docs.y.uno/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Test in the sandbox first: base URL https://api-sandbox.y.uno (Test Mode in the Dashboard). Production is https://api.y.uno (Live Mode).
> Every API request needs the public-api-key and private-secret-key headers. Get them in the Dashboard at https://dashboard.y.uno/developers (Developers > Credentials); sandbox and production keys are different.
> Send an X-Idempotency-Key (a UUID) when creating payments, refunds and cancels, so retries do not create duplicates.
> Start with the Quickstart (https://docs.y.uno/docs/quickstart.md) and the agent guide (https://docs.y.uno/agents.md). To search these docs from a coding agent, connect the docs MCP server at https://docs.y.uno/mcp.

# Seamless SDK (Pago iOS)

> Integra el Seamless SDK de iOS de Yuno en tu app móvil para ofrecer una experiencia de pago flexible.

> [!NOTE]
>
> **Esta página documenta un SDK heredado.** ¿Vas a iniciar una nueva integración? Usa el [Yuno SDK](https://docs.y.uno/docs/yuno-sdk/get-started.md). ¿Ya usas un SDK heredado? Sigue la [guía de migración](https://docs.y.uno/docs/yuno-sdk/migration/overview.md).
>
> El nuevo **Yuno SDK** (Web v2.x, iOS v3.x, Android v3.x, React Native v2.x) reemplaza los SDK Full, Lite, Seamless, Render, Headless y Secure Fields con una sola API en todas las plataformas. Los SDK heredados siguen siendo compatibles en paralelo durante la transición y está previsto dejarlos de usar en **2027**. Contacta a tu Account Manager para planificar la migración.

En esta página encontrarás todos los pasos para agregar, configurar y usar el Seamless SDK de iOS para realizar pagos en tu proyecto de iOS.

> [!TIP]
>
> **SDK recomendado**
>
> Yuno recomienda usar el **Seamless SDK de iOS** para una integración fluida. Esta opción ofrece una solución de pago flexible con componentes de interfaz prediseñados y opciones de personalización.

![Vista general del Seamless SDK de iOS](https://files.readme.io/bb2c987a467228d113d98035f453a459aedfb41554aad3eb49fc50fed8dbf0a0-Screenshot_2025-06-04_at_10.45.05_AM.png)

## Paso 1: incluye la biblioteca en tu proyecto

Puedes agregar la biblioteca con CocoaPods o Swift Package Manager.

### CocoaPods

Para agregar el Yuno SDK a tu proyecto de iOS, debes instalar el Yuno SDK. Si no tienes un Podfile, sigue la [guía de CocoaPods](https://guides.cocoapods.org/using/using-cocoapods.html) para crear uno. Después de crear el Podfile, integrarás el Yuno SDK con Cocoapods agregando la siguiente línea a tu Podfile.

```ruby theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
pod 'YunoSDK', '~> 2.29.0'
```

Después, debes ejecutar la instalación:

```ruby theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
pod install
```

### Swift Package Manager

Si usas [Swift Package Manager](https://www.swift.org/package-manager/), agrega el Yuno SDK como dependencia, como se muestra en el siguiente bloque de código:

```swift theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
dependencies: [
    .package(url: "https://github.com/yuno-payments/yuno-sdk-ios.git", .upToNextMajor(from: "2.29.0"))
]
```

## Paso 2: inicializa el SDK con la clave pública

Para empezar a ejecutar el checkout Seamless de Yuno para iOS, primero debes obtener tu ID de app de Yuno y tu clave de API pública. Luego, importa e inicializa Yuno como se muestra en el siguiente fragmento de código:

```swift theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
import YunoSDK

Yuno.initialize(
    apiKey: "PUBLIC_API_KEY",
    config: YunoConfig(),
    callback: { print("Yuno SDK initialized") }
)
```

> [!WARNING]
>
> **UISceneDelegate**
>
> Si tu app usa un `UISceneDelegate`, asegúrate de colocar el código de inicialización de Yuno dentro de tu `SceneDelegate`.

El checkout Seamless te permite configurar la apariencia del SDK. Es un paso opcional que configuras mediante la clase `YunoConfig`. Para definir las configuraciones, usa el siguiente bloque de código para configurar los elementos disponibles:

```swift theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
final class YunoConfig {
    let appearance: Yuno.Appearance,
    let saveCardEnabled: Bool
}
```

Configura el SDK con las siguientes opciones:

| Parámetro | Descripción |
| - | - |
| `appearance` | Este campo opcional define la apariencia del checkout. De forma predeterminada, usa los estilos de Yuno. Consulta [Personalizaciones del SDK](https://docs.y.uno/es/docs/sdks/customization/ios.md) para obtener más información. |
| `saveCardEnabled` | Este campo opcional te permite elegir si la casilla **Save Card** se muestra en los flujos de tarjeta. De forma predeterminada es false. |

> [!NOTE]
>
> **Acceso a tu clave de API**
>
> Puedes obtener tu clave de API en la [sección Developers](https://docs.y.uno/es/docs/using-yuno/settings/developers-credentials.md) del Yuno Dashboard.

### Crea una sesión de checkout

Antes de iniciar el proceso de pago, debes crear una `checkout_session` con el endpoint [Crear sesión de checkout](https://docs.y.uno/es/reference/checkout-sessions/create-checkout-session.md). Esta sesión inicializa el flujo de pago y se usará en el siguiente paso.

> [!NOTE]
>
> Controla la autorización frente a la captura enviando `payment_method.detail.card.capture` en la sesión de checkout: `false` = solo autorizar, `true` = capturar de inmediato.

#### Parámetros clave

| Parámetro | Obligatorio | Descripción |
| - | - | - |
| `amount` | Sí | El objeto del monto principal de la transacción, que contiene `currency` (código ISO 4217) y `value` (monto numérico en esa moneda). |
| `workflow` | Sí | Define el valor como `SDK_SEAMLESS` para que el SDK pueda completar correctamente el flujo de pago. |
| `alternative_amount` | No | Una representación del monto de la transacción en otra moneda, con la misma estructura que `amount` (`currency` y `value`). Es útil en escenarios multimoneda. Por ejemplo, puedes mostrar los precios a los clientes en su moneda preferida (por ejemplo, USD) mientras procesas el pago en la moneda local (por ejemplo, COP). |

## Paso 3: inicia el checkout y el proceso de pago

El checkout seamless y el proceso de pago se inician con un único método, `startPaymentSeamlessLite`. En el `ViewController`, donde se mostrará Yuno, llama al método `Yuno.startPaymentSeamlessLite()`. Puedes usar el método con async/await o con callbacks:

```swift Swift (async/await) theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
func startPaymentSeamlessLite(
    with params: SeamlessParams,
    paymentSelected: PaymentMethodSelected,
    showPaymentStatus: Bool = true
) async -> Result
```

```swift Swift (with callbacks) theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
func startPaymentSeamlessLite(
    with params: SeamlessParams,
    paymentSelected: PaymentMethodSelected,
    showPaymentStatus: Bool = true,
    callback: @escaping ((Result) -> Void)
)
```

La versión seamless requiere parámetros adicionales. Estos incluyen:

* `PaymentMethodSelected`: el token almacenado y/o el método de pago que el cliente usará para realizar el pago.

```swift theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
protocol PaymentMethodSelected {
    var vaultedToken: String? { get }
    var paymentMethodType: String { get }
}
```

* `SeamlessParams`

```swift theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
class SeamlessParams {
    var checkoutSession: String
    var countryCode: String
    var language: String?
    var viewController: UIViewController?
}
```

Parámetros

La siguiente tabla describe cada parámetro de `SeamlessParams`:

| Parámetro | Descripción |
| - | - |
| `checkoutSession` | Hace referencia a la sesión de checkout del pago actual. |
| `countryCode` | Este parámetro determina el país para el que se configura el proceso de pago. Consulta la página [Cobertura por país](https://docs.y.uno/es/docs/sdks/resources/country-coverage.md) para ver la lista completa de países compatibles y sus códigos. |
| `language` | Define el idioma que se usará en los formularios de pago. Consulta [Idiomas compatibles](https://docs.y.uno/es/docs/sdks/resources/languages-supported.md) para ver las opciones. |
| `viewController` | Esta propiedad representa el `UIViewController` que se usa para presentar el flujo de pago. La propiedad sigue siendo opcional por compatibilidad con versiones anteriores. Aun así, debes proporcionar un controlador visible para que el SDK pueda presentar su interfaz correctamente. |

> [!NOTE]
>
> **Requisitos de concurrencia de Swift 6**
>
> Si usas Swift 6, deberás implementar el protocolo `YunoPaymentDelegate` con consideraciones específicas de concurrencia. Consulta la guía de [Concurrencia en Swift 6](https://docs.y.uno/es/docs/sdks/resources/swift-6-concurrency.md) para conocer las opciones de implementación y las mejores prácticas.

## Paso 4: gestiona el estado del pago (opcional)

> [!CAUTION]
>
> **Deep links y Mercado Pago Checkout Pro**
>
> Este paso solo es necesario si usas un método de pago que depende de deep links o de Mercado Pago Checkout Pro. Si tus métodos de pago no usan deep links, puedes omitir este paso.

Algunos métodos de pago sacan a los usuarios de tu app para completar la transacción. Una vez finalizado el pago, el usuario regresa a tu app mediante un deep link. El SDK usa este deep link para determinar qué ocurrió (si el pago fue exitoso, falló o se canceló) y puede mostrar una pantalla de estado al usuario.

Para gestionarlo, debes actualizar tu `AppDelegate` para pasar la URL entrante de vuelta al Yuno SDK. Así, el SDK puede leer el resultado y, opcionalmente, mostrar el estado del pago. El siguiente fragmento de código muestra cómo agregarlo a tu app:

```swift theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
func application(_ app: UIApplication,
                 open url: URL,
                 options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {

  guard url.scheme == "yunoexample" else { return false }

  return Yuno.receiveDeeplink(url)
}
```

Este código escucha los deep links que abren tu app. Cuando se recibe una URL, verifica si el esquema coincide con el que usaste en el `callback_url` al configurar la sesión de checkout. Si coincide, la URL se pasa al Yuno SDK mediante `Yuno.receiveDeeplink(_:)`, que lee el resultado del pago.

Asegúrate de que el `url.scheme` de este código coincida con el `callback_url` que indicaste al crear la `checkout_session`.

## Estado de la transacción

Una vez completado el pago, el SDK puede devolver distintos estados de la transacción. La lista de todos los estados posibles y sus descripciones se presenta en la siguiente tabla:

| Estado de la transacción | Descripción |
| - | - |
| `succeeded` | Indica que la transacción o el proceso de pago se completó correctamente. |
| `fail` | Este estado indica que la transacción o el proceso de pago falló. Significa que hubo un error o un problema durante el proceso de pago que impidió completarlo correctamente. |
| `processing` | Indica que la transacción o el proceso de pago se está procesando actualmente. Se usa normalmente cuando hay un retraso en el procesamiento del pago, por ejemplo, al esperar la aprobación de un servicio de terceros o de una institución financiera. |
| `reject` | Este estado indica que la transacción fue rechazada. El rechazo puede ocurrir por varios motivos, como fondos insuficientes, actividad fraudulenta o solicitudes que infringen reglas o políticas específicas. |
| `internalError` | Significa que ocurrió un error inesperado en el sistema o en la infraestructura que gestiona el proceso de pago. Este estado sugiere un problema del lado del servidor o del backend y no un problema con los datos o la solicitud del usuario. |
| `userCancelled` | Este estado indica que el usuario canceló o abortó voluntariamente la transacción o el proceso de pago. Se usa normalmente cuando el usuario tiene la opción de cancelar o abandonar el proceso de pago. |

### Validación del estado del pago

Esta sección explica cómo gestiona el SDK el estado del pago cuando los usuarios cancelan o abandonan los flujos de pago, y cómo se relaciona el estado del SDK con el estado del pago en el backend en estos escenarios.

#### Métodos de pago síncronos (Apple Pay)

En los métodos de pago síncronos como Apple Pay, cuando un usuario cancela o cierra la interfaz de la billetera antes de recibir la respuesta de un proveedor de servicios de pago (PSP):

* **Estado del SDK**: devuelve `userCancelled` (CANCELLED\_BY\_USER)
* **Estado del pago en el backend**: permanece en `PENDING` hasta que se agote el tiempo del PSP o el comercio cancele el pago
* **Importante**: el SDK no devolverá `reject` ni `processing` en este escenario

Esto garantiza que el pago en el backend permanezca en estado pendiente y que el sistema del comercio pueda gestionarlo correctamente.

#### Métodos de pago asíncronos (PIX y métodos basados en QR)

En los métodos de pago asíncronos, cuando un usuario cierra la ventana de pago antes de completar el pago:

* **Estado del SDK**: devuelve `userCancelled`\*.
* **Estado del pago en el backend**: permanece en `PENDING` y el código de pago sigue siendo válido hasta que expire.
* **Reutilización de la sesión de checkout**: al reabrir la misma sesión de checkout se puede mostrar el mismo código de pago válido.
* **Sin cancelación automática**: el pago no se cancela automáticamente en el backend cuando el usuario cierra la ventana.
* **Confirmación del estado**: `userCancelled` significa que el comprador salió de la pantalla, y no implica que el pago haya fallado. Confirma el estado final mediante webhook o `GET /v1/payments/{payment_id}` antes de mostrar una cancelación.

> [!NOTE]
>
> \* Los métodos de pago que muestran un código de pago o un comprobante (código QR de PIX, boleto, OXXO y similares), y Pix Parcelado, devuelven `processing` con el subestado `CLOSED_BY_USER` en lugar de `userCancelled` cuando el usuario cierra la pantalla. El pago permanece en `PENDING` en el backend y aún se puede completar.

#### Pagos asíncronos vencidos

Si un código QR de PIX vence de forma natural:

* **Estado en el backend**: se actualiza a `EXPIRED`
* **Estado del SDK**: los callbacks del SDK y los endpoints de sondeo devuelven `EXPIRED` de forma consistente

Esto garantiza que los comercios reciban información de estado precisa cuando un método de pago ha vencido.

El estado de la transacción se puede gestionar de dos maneras al usar el método `startPaymentSeamlessLite`:

* **Async/Await**: usa el enfoque async/await para un flujo más simplificado. Este método devuelve un Result de forma asíncrona, lo que hace que el código sea más fácil de leer y mantener.
* **Callback**: puedes gestionar el estado de la transacción mediante una función callback, lo que permite una ejecución inmediata en cuanto el resultado está disponible.

Ambas opciones ofrecen flexibilidad según tu enfoque preferido para el código asíncrono.

```swift theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
class Result {
    var status: Status

    enum Status {
        case reject, succeeded, fail, processing, internalError, userCancelled
    }
}
```

Evalúa `result.status` con switch, no `result` directamente.

## Funciones complementarias

El Yuno SDK de iOS ofrece servicios y configuraciones adicionales que puedes usar para mejorar la experiencia de los clientes. Usa las [personalizaciones del SDK](https://docs.y.uno/es/docs/sdks/customization/ios.md) para cambiar la apariencia del SDK y adaptarla a tu marca o para configurar el loader.

* **Loader**: controla el uso del loader mediante las opciones de configuración del SDK.
* **Guardar tarjeta para pagos futuros**: además, puedes mostrar una casilla para guardar o inscribir tarjetas con `saveCardEnabled: true`. A continuación encontrarás ejemplos de la casilla en ambos formatos del formulario de tarjeta.

![Guardar tarjeta para pagos futuros](https://lh7-rt.googleusercontent.com/docsz/AD_4nXe9dPjXE9Y8Uq3EKpmzUrsBpXHCHtspu98NLo41GsszFV1lCCGNsiXvB-9dmQRtPTExcDWQ7S-Qqoq0iFXaeogBZPpONcLy8Ep55cqog0KHHasbstgeCgSTR00BiFmIbcWd4NwHkO7LrLUOsQXnFV1_gT45?key=-31QL7MEbUE8QLWSURQp1jZt)

## Gestión de errores

Gestiona en tu app los errores que devuelve el SDK, como los pagos fallidos y los errores de validación. Para conocer los códigos de estado HTTP y de respuesta, consulta [Códigos de estado y de respuesta](https://docs.y.uno/reference/payments/status-and-response-codes/payment.md) en la referencia de la API.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.