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

# Headless SDK (Inscripción iOS)

> Guía paso a paso para integrar el Headless SDK de Yuno (Inscripción iOS) en tu aplicación móvil.

> [!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.

> [!WARNING]
>
> **Orientación: elige tu flujo de integración**. Antes de comenzar, revisa el [flujo de integración oficial](https://docs.y.uno/docs/sdks/overview/understanding-flows.md).
>
> * **Flujo estándar ([Full Checkout](https://docs.y.uno/docs/sdks/full-checkout/web-payments))**: Recomendado para la mayoría de los comercios. Yuno se encarga de la interfaz, la seguridad y las actualizaciones automáticas de los métodos de pago.
> * **Flujo personalizado (este SDK)**: Úsalo solo si necesitas control total sobre la experiencia de usuario. **Nota**: Serás responsable de gestionar manualmente los estados de los pagos, las transiciones de 3DS y la recopilación de datos para el enrutamiento de fraude.

El Headless iOS SDK de Yuno te permite inscribir métodos de pago y tokenizar tarjetas para guardarlas y usarlas en el futuro.

Los siguientes pasos describen cómo inscribir un método de pago con el Headless SDK de Yuno.

## Requisitos

Para ejecutar el proceso de inscripción, debes proporcionar el `customer_session` para iniciarlo en el Paso 3. Para obtener el `customer_session`, debes:

1. **Crear un cliente**: se requiere un cliente para inscribir pagos. Usa el endpoint [Create Customer](https://docs.y.uno/reference/customers/create-customer.md) para crear nuevos clientes. En la respuesta recibirás el `id` del cliente, que usarás para crear la sesión de cliente.
2. **Crear la sesión de cliente**: usa el `id` del cliente y el endpoint [Create Customer Session](https://docs.y.uno/reference/customer-sessions-enrollment/create-customer-session.md) para recibir el `customer_session`.

## Paso 1: incluye la biblioteca en tu proyecto

El primer paso es instalar el Yuno SDK en tu proyecto iOS.

> [!NOTE]
>
> **Consulta las versiones del iOS SDK**
>
> Para ver todas las versiones disponibles, visita la [página de versiones](https://github.com/yuno-payments/yuno-sdk-ios/releases) en el repositorio del Yuno iOS SDK.

Puedes instalar el Yuno SDK de dos maneras:

* **Cocoapods**: 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'
  ```
* **[Swift Package Manager](https://www.swift.org/package-manager/)**: configura el paquete de Swift y luego 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 Headless SDK con la clave pública

Para inicializar el Headless SDK, debes importar Yuno y proporcionar una **PUBLIC\_API\_KEY** válida. Si no tienes tus credenciales de API, accede a la página [Developers (Credentials)](https://docs.y.uno/es/docs/using-yuno/settings/developers-credentials.md) para ver cómo obtenerlas desde el Dashboard.

El siguiente bloque de código presenta un ejemplo de cómo importar e inicializar `Yuno`.

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

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

> [!NOTE]
>
> **Requisitos de concurrencia de Swift 6**
>
> Si usas Swift 6, deberás manejar correctamente la concurrencia al usar los métodos asíncronos del SDK. Consulta la guía [Swift 6 Concurrency](https://docs.y.uno/es/docs/sdks/resources/swift-6-concurrency.md) para ver opciones de implementación detalladas y mejores prácticas.

> [!NOTE]
>
> **Inicialización con UISceneDelegate**
>
> Si tu aplicación usa un `UISceneDelegate`, puedes inicializar Yuno dentro de tu `SceneDelegate`. Sin embargo, si prefieres inicializar Yuno en otra parte de tu aplicación, también puedes hacerlo. El método de inicialización ofrece un callback que te notifica cuando el proceso ha terminado.

## Paso 3: crea una sesión de cliente

Para iniciar el proceso de inscripción, debes proporcionar el `customer_session`. Primero, debes crear un cliente. Necesitas un cliente con el que inscribir pagos. Usa el endpoint [Create Customer](https://docs.y.uno/reference/customers/create-customer.md) para crear nuevos clientes. En la respuesta recibirás el `id` del cliente, que usarás para crear la sesión de cliente.

Después de crear el cliente, puedes crear la sesión de cliente. Usa el `id` del cliente y el endpoint [Create Customer Session](https://docs.y.uno/reference/customer-sessions-enrollment/create-customer-session.md). El `customer_session` se entregará en la respuesta. Necesitas un nuevo `customer_session` cada vez que inscribas un nuevo método de pago.

## Paso 4: crea un objeto de método de pago de inscripción

Necesitas un objeto de método de pago de inscripción para configurar la integración del Headless SDK para la inscripción. Puedes crearlo con el endpoint [Enroll Payment Method](https://docs.y.uno/reference/payment-methods-checkout/enroll-payment-method-checkout.md). Al crear el objeto de método de pago, debes definir en qué método de pago puede inscribirse tu cliente. Actualmente, solo CARD está disponible para el Headless SDK.

> [!NOTE]
>
> **Verificación de tarjeta**
>
> Para verificar las tarjetas con una autorización de valor cero antes de la inscripción, incluye el objeto `verify` al crear el objeto de método de pago para la sesión de cliente.

## Paso 5: inicia el proceso de inscripción

A continuación, iniciarás el proceso de checkout con la función `apiClientEnroll`, proporcionando los parámetros de configuración necesarios.

> [!WARNING]
>
> **Manejo de errores**
>
> Este método lanza un error si el Yuno SDK no se ha inicializado antes de llamarlo.

### Parámetros

La siguiente tabla enumera todos los parámetros requeridos y sus descripciones.

| Parámetro | Descripción |
| - | - |
| `countryCode` | Este parámetro determina el país para el cual se configura el proceso de pago. La lista completa de países compatibles y su `countryCode` está disponible en la página [Country coverage](https://docs.y.uno/es/docs/sdks/resources/country-coverage.md). |
| `customerSession` | Se refiere a la sesión de cliente de la inscripción actual, recibida como respuesta del endpoint [Create Customer Session](https://docs.y.uno/reference/customer-sessions-enrollment/create-customer-session.md). Ejemplo: '438413b7-4921-41e4-b8f3-28a5a0141638' |

El siguiente bloque de código presenta un ejemplo de la configuración de los parámetros.

```swift theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
var apiClientEnroll: YunoEnrollHeadless?

apiClientEnroll = try Yuno.apiClientEnroll(
    countryCode: "CO",
    customerSession: "eec6578e-ac2f-40a0-8065-25b5957f6dd3"
)
```

## Paso 6: genera un vaulted token

Después de recopilar toda la información del usuario, puedes iniciar la inscripción. Primero, debes crear un `vaulted_token` con la función `apiClientEnroll.continueEnrollment`. Como es una función asíncrona, puedes usar `do/catch` para asegurarte de manejar correctamente los errores que se produzcan. A continuación, encontrarás un ejemplo de cómo crear un `vaulted_token`:

```swift theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
let enrollmentCollectedData: EnrollmentCollectedData = EnrollmentCollectedData(
    customerSession: "eec6578e-ac2f-40a0-8065-25b5957f6dd3",
    paymentMethod: CollectedData(
        type: "CARD",
        card: CardData(
            detail: CardData.Detail(
                number: "4111111111111111",
                expirationMonth: 12,
                expirationYear: 25,
                securityCode: "123",
                holderName: "Andrea",
                type: .credit
            )
        ),
        customer: Customer()
    )
)

let result = try await apiClientEnroll?.continueEnrollment(data: enrollmentCollectedData)
```

Después de inscribir la nueva tarjeta, recibirás el `vaulted_token`. Puedes usarlo para realizar pagos en el futuro sin pedir los datos de la tarjeta de tu cliente. El siguiente bloque de código presenta un ejemplo de respuesta de la función `apiClientEnroll.continueEnrollment`. La respuesta es un diccionario de tipo `[String: String]` con claves en camelCase: `vaultedToken`, `status` y `customerSession`.

```swift theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
[
    "vaultedToken": "9104911d-5df9-429e-8488-ad41abea1a4b",
    // status: EXPIRED, REJECTED, READY_TO_ENROLL, ENROLL_IN_PROCESS, UNENROLL_IN_PROCESS,
    // IN_PROCESS, ENROLLED, DECLINED, CANCELED, ERROR, or UNENROLLED
    "status": "ENROLLED",
    "customerSession": "eec6578e-ac2f-40a0-8065-25b5957f6dd3"
]
```

> [!NOTE]
>
> **Uso de webhooks para el estado de la inscripción**
>
> Considera usar el estado de la inscripción recibido mediante [webhooks](https://docs.y.uno/docs/webhooks/index.md). Yuno recomienda basar siempre las decisiones de negocio de tu plataforma en este estado.

> [!NOTE]
>
> **Accede a la aplicación de demostración**
>
> Además de los ejemplos de código proporcionados, puedes acceder al [repositorio de Yuno](https://github.com/yuno-payments/yuno-sdk-ios) para ver una implementación completa de los iOS SDK de Yuno.

## Manejo de errores

Maneja en tu aplicación los errores devueltos por el SDK, como pagos fallidos o errores de validación. Para 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.