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

# Modo Headless

> Migra las integraciones de Web Headless (yuno.apiClientPayment) a la Transaction API unificada.

Headless era un cliente de tokenización pura: el comercio recopilaba los datos de la tarjeta en su propia interfaz, generaba un token y hacía su propia llamada al backend para crear el pago.

En la API unificada el mismo escenario es un `start()` headless. Pasa los datos recopilados previamente dentro de `data` en el `paymentMethod` que entregas a `start()`, sobrescribe [`createPayment`](https://docs.y.uno/es/docs/yuno-sdk/controllers/create-payment) para hacer POST a tu backend (modo manual), y deja que el SDK orqueste automáticamente la tokenización, 3DS y la consulta del estado. Si no quieres que el SDK continúe el flujo después de crear el pago, define `autoContinuePayment` como `false` en el objeto [`TransactionConfig`](https://docs.y.uno/es/docs/yuno-sdk/reference/objects-you-pass#transaction-config).

## Usar la lista de métodos de pago con Headless

Headless no significa que no puedas usar los componentes del SDK. Puedes combinar [`getPaymentMethodsViews`](https://docs.y.uno/es/docs/yuno-sdk/features/payment-methods-list) para la selección del método con un `start()` headless para la ejecución del pago.

* **División de responsabilidades:**
  * **Yuno se encarga de:** mostrar la lista de métodos de pago, mostrar los métodos de pago guardados del cliente, los botones de billeteras exprés (Apple Pay, Google Pay, PayPal), los desafíos 3DS, las redirecciones y los traspasos.
  * **El comercio se encarga de:** mostrar los campos personalizados para recopilar la tarjeta y tu propio botón Pay.

```typescript theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
let selectedMethod: PaymentMethodSelected | null = null

const views = transaction.getPaymentMethodsViews({
    types: ['applePay', 'googlePay', 'paymentMethodList'],
    onPaymentSelected: (selection) => {
        // selection contains { type, name, vaultedToken, selectionSource }
        selectedMethod = selection
    },
})

views.paymentMethodList?.mount({ elementSelector: '#payment-list' })

// When the customer submits with your own Pay button:
if (selectedMethod) {
    if (selectedMethod.vaultedToken) {
        // Customer selected a saved (vaulted) method
        await transaction.start({
            paymentMethod: {
                type: selectedMethod.type,
                vaultedToken: selectedMethod.vaultedToken,
                data: {
                    card: {
                        securityCode: cvv,
                    },
                },
            },
        })
    } else if (selectedMethod.type === 'CARD') {
        // Customer selected new card: submit your custom card form data
        await transaction.start({
            paymentMethod: {
                type: 'CARD',
                data: {
                    card: {
                        holderName: cardHolder,
                        number: cardNumber,
                        securityCode: cvv,
                        expirationMonth: expMonth,
                        expirationYear: expYear,
                    },
                },
            },
        })
    } else {
        // Non-card method (e.g. APM or direct redirect)
        await transaction.start({
            paymentMethod: {
                type: selectedMethod.type,
            },
        })
    }
}
```

> [!WARNING]
>
> **La visualización desplegada no se puede usar con la recopilación de tarjeta headless.** Cuando **Unfolded display** está habilitado en **Checkout Builder → Styling**, al seleccionar un método se incrusta y envía el formulario prediseñado de Yuno directamente dentro de la fila de la lista. Para recopilar los datos de la tarjeta en tus propios campos, asegúrate de que Unfolded display esté deshabilitado para que la lista actúe estrictamente como un selector.

## Antes de empezar

* Carga el bundle del SDK unificado en lugar del heredado e inicialízalo como muestra la comparación lado a lado: `window.Yuno.initialize(...)` pasa a ser `SdkPayments.initialize(...)`. Tu clave de API pública y las sesiones de checkout que crea tu backend no cambian ([Antes de comenzar](https://docs.y.uno/es/docs/yuno-sdk/get-started.md#before-you-begin)).
* Decide quién crea el pago. El `workflow` de la sesión de checkout debe coincidir con esa decisión:

| Quién crea el pago | En Headless tenías | En la API unificada | `workflow` de la sesión |
| - | - | - | - |
| Tu backend | Siempre: `generateToken`, y luego tu propia llamada al backend | Sobrescribe `createPayment` | Predeterminado (`SDK_CHECKOUT`) |
| El SDK | Sin equivalente: Headless nunca creaba el pago | Sin sobrescritura | `SDK_SEAMLESS` |

> [!WARNING]
>
> Una sesión con el workflow predeterminado y sin la sobrescritura de `createPayment` termina en `INTERNAL_ERROR`: el backend rechaza la creación del pago por parte del SDK. Consulta [`createPayment`](https://docs.y.uno/es/docs/yuno-sdk/controllers/create-payment).

## Comparación lado a lado

```typescript Before. Headless (apiClientPayment) theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
const yuno = await window.Yuno.initialize('your-public-api-key')

const apiClientPayment = await yuno.apiClientPayment({
    checkout_session: 'session-from-backend',
    country_code: 'CO',
})

// Merchant collects card data in their own UI, then:
const oneTimeToken = await apiClientPayment.generateToken({
    payment_method: {
        type: 'CARD',
        card: {
            detail: {
                holder_name: 'John Doe',
                number: '4111111111111111',
                security_code: '123',
                expiration_month: 12,
                expiration_year: 28,
            },
        },
        third_party_data: null,
    },
})

// Merchant POSTs to their backend
const paymentId = await myBackend.pay({ oneTimeToken, checkoutSession })

// If 3DS needed, merchant calls SDK again to challenge (bespoke per integration)
```

```typescript After. Unified Transaction (headless) theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
const sdkPayments = await SdkPayments.initialize('your-public-api-key')

const transaction = sdkPayments.transaction({
    checkoutSession: 'session-from-backend',
    countryCode: 'CO',
    createPayment: async (token) => {
        await myBackend.pay({ token: token.token })
    },
    onStatus: (result) => console.log('done:', result.status),
})

await transaction.start({
    paymentMethod: {
        type: 'CARD',
        data: {
            card: {
                holderName: 'John Doe',
                number: '4111111111111111',
                securityCode: '123',
                expirationMonth: 12,
                expirationYear: 28,
            },
        },
    },
})
```

## Qué cambia

Agrupado en el orden en que editas el código. **Renombrado**: mismo rol, nuevo nombre. **Movido**: mismo valor, nuevo dueño. **Eliminado**: nada que llamar. **Nuevo**: sin equivalente heredado. La última columna es lo único que tienes que hacer además del cambio de nombre.

### Inicialización y configuración

| Headless | Unificado | Cambio | Qué hacer |
| - | - | - | - |
| `window.Yuno.initialize(publicApiKey)` | `SdkPayments.initialize(publicApiKey)` | Renombrado | El global es `window.SdkPayments`. Como antes, usa `await`: se resuelve en la instancia de `SdkPayments` desde la que creas las transacciones. |
| Argumentos `checkout_session`, `country_code` de `apiClientPayment` | `checkoutSession`, `countryCode` en la configuración de la transacción | Movido | Defínelos una sola vez en la configuración. |
| `holder_name`, `number`, `security_code`, `expiration_month`, `expiration_year` en `payment_method.card.detail` (argumento de `generateToken`) | `holderName`, `number`, `securityCode`, `expirationMonth`, `expirationYear` en `paymentMethod.data.card` | Movido | Los datos de la tarjeta van en línea en `start()`, anidados en `data.card`, con la forma unificada de `TransactionData`. Esa forma admite más campos para cubrir no solo tarjetas sino también métodos de pago alternativos (APM) como transferencias bancarias, tickets, billeteras y más. Consulta la forma completa en [`TransactionData`](https://docs.y.uno/es/docs/yuno-sdk/reference/objects-you-pass#transaction-data). |
| *(ninguno)* | `paymentMethod.vaultedToken` | Nuevo | Para tarjetas guardadas, pasa `vaultedToken` en `paymentMethod` y solo `securityCode` en `data.card`: `transaction.start({ paymentMethod: { type: 'CARD', vaultedToken: 'tok_saved_abc', data: { card: { securityCode: '123' } } } })`. |

### Callbacks

| Headless | Unificado | Cambio | Qué hacer |
| - | - | - | - |
| Tu propia llamada al backend después de `generateToken` | `createPayment(token)` | Movido | Conéctalo en la configuración de la transacción: `token` es el mismo token que `generateToken` devolvía directamente a tu código, ahora entregado como argumento de tu sobrescritura; no hay una llamada aparte para obtenerlo. Envíalo con POST a tu backend y resuelve la Promise: el SDK continúa desde ahí. Consulta [`createPayment`](https://docs.y.uno/es/docs/yuno-sdk/controllers/create-payment) y [`OneTimeToken`](https://docs.y.uno/es/docs/yuno-sdk/reference/objects-you-receive#one-time-token). |
| *(sin callback de resultado)* | `onStatus(result)` | Nuevo | Ahora el SDK gestiona todo el ciclo de vida (tokenización, 3DS, consulta del estado) e informa el estado final aquí. Consulta [`Status`](https://docs.y.uno/es/docs/yuno-sdk/reference/objects-you-receive#status). |

### Puntos de entrada

| Headless | Unificado | Cambio | Qué hacer |
| - | - | - | - |
| `yuno.apiClientPayment({ checkout_session, country_code })` | `sdkPayments.transaction({ checkoutSession, countryCode, createPayment })` | Renombrado | La fábrica consolida las superficies de API-client y Transaction: ya no hay una superficie `apiClientPayment` aparte, solo un `sdkPayments.transaction(config)`. |
| `apiClientPayment.generateToken(cardData)` | `transaction.start({ paymentMethod: { type: 'CARD', data: { card } } })` | Renombrado | Ya no tokenizas por tu cuenta: arma el `paymentMethod` con los datos de tarjeta que recopilaste previamente (consulta Inicialización y configuración) y luego llama a `start`. El SDK tokeniza y llama a `createPayment` con el token. |
| `apiClientPayment.getThreeDSecureChallenge(...)` (poco frecuente) | *(eliminado)* | Eliminado | Elimina la llamada. Headless requería un manejo de 3DS a medida en cada integración; el SDK orquesta 3DS internamente una vez que `createPayment` se resuelve. |
| `yuno.continuePayment()` después del POST al backend | *(eliminado)* | Eliminado | Elimina la llamada: el contrato de Promise dirige el avance. Resuelve `createPayment` y el SDK continúa. |

## Relacionado

* [`createPayment`](https://docs.y.uno/es/docs/yuno-sdk/controllers/create-payment). El callback que cambia de modo.
* [`TransactionData`](https://docs.y.uno/es/docs/yuno-sdk/reference/objects-you-pass#transaction-data). Forma de los datos headless por método.
* [`OneTimeToken`](https://docs.y.uno/es/docs/yuno-sdk/reference/objects-you-receive#one-time-token). Payload del token enviado a tu backend.


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