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

# ¿Por dónde empiezo?

> Decide qué parámetros y controladores usar según lo que quieras construir.

Los SDK de Yuno exponen una sola clase `Transaction`. Lo que cambia entre las
integraciones es **qué parámetros pasas** y **qué controladores
sobrescribes**. Cada decisión es independiente. Combínalas libremente.

Esta página recorre las decisiones que tomarás y te lleva a la
documentación relevante para cada una.

Activa el interruptor en cada paso y el código de la derecha se arma solo para tu plataforma. Cada bloque que usa el código también está escrito debajo de su paso, así que puedes componerlo a mano: parte de la base y luego agrega el bloque de cada paso en el que elegiste la respuesta distinta de la predeterminada. Un bloque de configuración reemplaza el `TransactionConfig`, un bloque de método de pago reemplaza el `PaymentMethodSelected`, una línea de indicador va dentro de `TransactionConfig`, y un bloque de controlador va dentro de tu clase de controlador, o dentro de las opciones de la transacción en Web.

66 s

Elige tu integración
Subtítulos en pantalla, sin voz en off

<dialog aria-label="Elige tu integración">
  ×

  <video src="https://docs.y.uno/videos/explainers/pick-your-integration.mp4" poster="/videos/explainers/pick-your-integration.jpg" controls preload="none" playsInline aria-label="Elige tu integración" />
</dialog>

## Base

El SDK hace todo: muestra el formulario, crea el pago, gestiona 3DS e informa el resultado a `onStatus`. Crea la sesión de checkout con `workflow: "SDK_SEAMLESS"` para esta base.

> [accordion] Código base
>
> > [tab] iOS
> >
> > ```swift theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
> > import SwiftUI
> > import SdkPayments
> >
> > final class Checkout: SdkPayments.TransactionController {
> >
> >     func start() {
> >         let paymentSelected = SdkPayments.PaymentMethodSelected(
> >             paymentMethodType: "CARD"
> >         )
> >
> >         let config = SdkPayments.TransactionConfig(
> >             checkoutSession: "session-from-backend",
> >             countryCode: "US",
> >             language: "en",
> >             controller: self
> >         )
> >
> >         SdkPayments.Transaction(config: config)
> >             .start(paymentSelected: paymentSelected)
> >     }
> >
> >     func onStatus(status: SdkPayments.TransactionStatus) {
> >         print("Final status: \(status.status)")
> >     }
> > }
> > ```
>
> > [tab] Android
> >
> > ```kotlin theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
> > import com.yuno.payments.sdk.api.Transaction
> > import com.yuno.payments.sdk.api.TransactionConfig
> > import com.yuno.payments.sdk.api.TransactionController
> > import com.yuno.payments.sdk.api.models.PaymentMethodSelected
> > import com.yuno.payments.sdk.api.models.TransactionStatus
> >
> > class CheckoutActivity : ComponentActivity(), TransactionController {
> >
> >     private fun startCheckout() {
> >         val paymentSelected = PaymentMethodSelected(
> >             type = "CARD"
> >         )
> >
> >         val config = TransactionConfig(
> >             checkoutSession = "session-from-backend",
> >             countryCode = "US",
> >             language = "en",
> >             controller = this
> >         )
> >
> >         Transaction(config)
> >             .start(activity = this, paymentSelected = paymentSelected)
> >     }
> >
> >     override fun onStatus(status: TransactionStatus) {
> >         println("Final status: ${status.status}")
> >     }
> > }
> > ```
>
> > [tab] Web
> >
> > ```typescript theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
> > const transaction = sdkPayments.transaction({
> >     checkoutSession: 'session-from-backend',
> >     countryCode: 'US',
> >     language: 'en',
> >     elementSelector: '#payment-form',
> >     onStatus: (result) => {
> >         console.log('Final status:', result.status)
> >     },
> > })
> >
> > const paymentMethod = { type: 'CARD' }
> >
> > await transaction.start({ paymentMethod })
> > ```
>
> > [tab] React Native
> >
> > ```tsx theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
> > import { Transaction, type TransactionConfig } from '@yuno-payments/yuno-sdk-react-native';
> >
> > export async function startCheckout() {
> >   const paymentSelected = { type: 'CARD' };
> >
> >   const config: TransactionConfig = {
> >     checkoutSession: 'session-from-backend',
> >     countryCode: 'US',
> >     language: 'en',
> >     controller: {
> >       onStatus: (status) => {
> >         console.log('Final status:', status.status);
> >       },
> >     },
> >   };
> >
> >   await new Transaction(config).start(paymentSelected);
> > }
> > ```

## ¿Estás procesando un pago o guardando un método de pago?

Esta decisión afecta qué tipo de sesión creas en tu backend y
pasas al SDK.

* **Para procesar un pago**, crea una sesión de checkout y pásala a
  `TransactionConfig` como `checkoutSession`. Usa esto cuando quieras
  cobrarle al cliente.
* **Para guardar un método de pago sin cobrar**, crea una sesión de
  cliente y pásala como `customerSession`. Usa esto cuando quieras
  inscribir una tarjeta u otro método para uso futuro.
* **Para pagar e inscribir al mismo tiempo**, pasa solo `checkoutSession`:
  * **Tarjetas.** Activa el indicador "guardar tarjeta al pagar" en tu
    Checkout Builder. El SDK cobra al cliente y guarda la
    tarjeta para uso futuro.
  * **Otros métodos de pago.** Asegúrate de que la variante inscribible del
    método esté agregada en tus conexiones. Cuando lo está, el SDK
    gestiona el pago y la inscripción juntos a partir de la sesión de
    checkout únicamente. En Web, pasa también `savePaymentMethodEnabled: true`
    en `TransactionConfig` y crea la sesión de checkout con un
    `customer_id`. Entonces el SDK agrega una opción de guardado al formulario.

No puedes pasar `checkoutSession` y `customerSession` al mismo
tiempo.

Consulta [Sesiones](https://docs.y.uno/es/docs/basic-concepts/sessions.md) e
[Inscripción](https://docs.y.uno/es/docs/yuno-sdk/features/enrollment.md).

> [accordion] Usa esta configuración para inscribir en lugar de cobrar
>
> > [tab] iOS
> >
> > ```swift theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
> >         let config = SdkPayments.TransactionConfig(
> >             customerSession: "session-from-backend",
> >             countryCode: "US",
> >             language: "en",
> >             controller: self
> >         )
> > ```
>
> > [tab] Android
> >
> > ```kotlin theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
> >         val config = TransactionConfig(
> >             customerSession = "session-from-backend",
> >             countryCode = "US",
> >             language = "en",
> >             controller = this
> >         )
> > ```
>
> > [tab] Web
> >
> > ```typescript theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
> > const transaction = sdkPayments.transaction({
> >     customerSession: 'session-from-backend',
> >     countryCode: 'US',
> >     language: 'en',
> >     elementSelector: '#enrollment-form',
> >     onStatus: (result) => {
> >         console.log('Final status:', result.status)
> >     },
> > })
> > ```
>
> > [tab] React Native
> >
> > ```tsx theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
> >   const config: TransactionConfig = {
> >     customerSession: 'session-from-backend',
> >     countryCode: 'US',
> >     language: 'en',
> >     controller: {
> >       onStatus: (status) => {
> >         console.log('Final status:', status.status);
> >       },
> >     },
> >   };
> > ```

## ¿Quién crea el pago?

Esta decisión afecta si sobrescribes `createPayment`.

* **Predeterminado. El SDK crea el pago.** Después de la tokenización, el
  SDK llama a Yuno para crear el pago, gestiona 3DS si es necesario y
  emite el estado final a `onStatus`. No sobrescribes nada.
  Crea la sesión de checkout con `workflow: "SDK_SEAMLESS"` para que el
  SDK pueda gestionar la creación del pago de principio a fin. Consulta el
  [campo `workflow`](https://docs.y.uno/reference/checkout-sessions/create-checkout-session#body-workflow).
* **Tú creas el pago.** Sobrescribe `createPayment` para recibir el
  token. Envíalo a tu backend, crea el pago llamando a
  [`POST /v1/payments`](https://docs.y.uno/reference/payments/create-payment) y resuelve la
  Promise/Task. Entonces el SDK consulta el estado y continúa el flujo.

> [!WARNING]
>
> `workflow` es un campo del cuerpo de la solicitud
> `POST /v1/checkout/sessions`. **No** forma parte de `TransactionConfig` y no se puede definir
> desde el SDK. Debe coincidir con esta decisión:
>
> * El SDK crea el pago (sin sobrescribir) → crea la sesión con
>   `workflow: "SDK_SEAMLESS"`.
> * Tú creas el pago (sobrescribes `createPayment`) → usa el
>   workflow predeterminado (`SDK_CHECKOUT`).
>
> Con el `SDK_CHECKOUT` predeterminado y **sin** sobrescribir `createPayment`,
> el backend rechaza la creación del pago por parte del SDK y la transacción
> termina en `INTERNAL_ERROR` con `message.source: "backend"`, por lo que el
> flujo no puede completarse.

> [!NOTE]
>
> En un flujo de **inscripción** (cuando pasas `customerSession`),
> `createPayment` no se invoca con datos de pago. No hay
> ningún pago que crear. Sobrescribir este controlador no tiene efecto en
> la inscripción.

Consulta [`createPayment`](https://docs.y.uno/es/docs/yuno-sdk/controllers/create-payment).

> [accordion] Agrega este bloque a tu controlador cuando crees el pago
>
> > [tab] iOS
> >
> > ```swift theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
> >     func createPayment(token: [String: Any]) async throws {
> >         // Create the payment from your backend with POST /v1/payments, then return.
> >         try await myBackend.createPayment(token: token)
> >     }
> > ```
>
> > [tab] Android
> >
> > ```kotlin theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
> >     override suspend fun createPayment(token: Map<String, Any>) {
> >         // Create the payment from your backend with POST /v1/payments, then return.
> >         myBackend.createPayment(token)
> >     }
> > ```
>
> > [tab] Web
> >
> > ```typescript theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
> >     createPayment: async (token) => {
> >         // Create the payment from your backend with POST /v1/payments, then resolve.
> >         await myBackend.createPayment(token.token)
> >     },
> > ```
>
> > [tab] React Native
> >
> > ```tsx theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
> >       createPayment: async (token) => {
> >         // Create the payment from your backend with POST /v1/payments, then resolve.
> >         await myBackend.createPayment(token);
> >       },
> > ```

## ¿Quién recopila los datos de pago?

Esta decisión afecta si pasas `transactionData` en
`PaymentMethodSelected`.

* **Predeterminado. El SDK muestra los formularios.** El SDK presenta el
  formulario adecuado (formulario de tarjeta, formulario de datos de APM, etc.) y recopila los datos que ingresa el
  usuario.
* **Tú proporcionas los datos.** Pasa `transactionData` (`data` en Web) en
  `PaymentMethodSelected` con los valores ya recopilados (por
  ejemplo, datos de tarjeta capturados por tu propia interfaz). El SDK omite los
  formularios y tokeniza directamente.

Consulta [`PaymentMethodSelected`](https://docs.y.uno/es/docs/yuno-sdk/reference/objects-you-pass#payment-method-selected)
y [`TransactionData`](https://docs.y.uno/es/docs/yuno-sdk/reference/objects-you-pass#transaction-data).

> [accordion] Usa este `PaymentMethodSelected` cuando hayas recopilado los datos tú mismo
>
> > [tab] iOS
> >
> > ```swift theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
> >         let paymentSelected = SdkPayments.PaymentMethodSelected(
> >             paymentMethodType: "CARD",
> >             transactionData: SdkPayments.TransactionData(
> >                 card: SdkPayments.CardTransactionData(
> >                     number: cardNumber,
> >                     securityCode: cvv,
> >                     expirationMonth: expMonth,
> >                     expirationYear: expYear,
> >                     holderName: holder
> >                 )
> >             )
> >         )
> > ```
>
> > [tab] Android
> >
> > ```kotlin theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
> >         val paymentSelected = PaymentMethodSelected(
> >             type = "CARD",
> >             transactionData = TransactionData(
> >                 card = CardData(
> >                     number = number,
> >                     securityCode = cvv,
> >                     expirationMonth = expMonth,
> >                     expirationYear = expYear,
> >                     holderName = holder
> >                 )
> >             )
> >         )
> > ```
>
> > [tab] Web
> >
> > ```typescript theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
> > const paymentMethod = {
> >     type: 'CARD',
> >     data: {
> >         card: {
> >             holderName: 'John Doe',
> >             number: '4111111111111111',
> >             securityCode: '123',
> >             expirationMonth: 12,
> >             expirationYear: 28,
> >         },
> >     },
> > }
> > ```
>
> > [tab] React Native
> >
> > ```tsx theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
> >   const paymentSelected = {
> >     type: 'CARD',
> >     transactionData: {
> >       card: {
> >         number: cardNumber,
> >         securityCode: cvv,
> >         expirationMonth: expMonth,
> >         expirationYear: expYear,
> >         holderName: holder,
> >       },
> >     },
> >   };
> > ```

## ¿Quién controla la interfaz del formulario? (iOS, Android, React Native)

Esta decisión afecta si sobrescribes `showView`.

* **Predeterminado. El SDK presenta el formulario a pantalla completa.** El SDK muestra
  el formulario con su propio encabezado y su propio botón de envío.
* **Tú incrustas el formulario.** Sobrescribe `showView` para recibir la vista del formulario
  y un control `TransactionProcess`. Coloca la vista en tu propio
  diseño y llama a `process.onSubmit()` para controlar el envío.

Este controlador solo está disponible en iOS, Android y React Native.

### En Web: tu propio botón de pago en lugar de `showView`

En Web el SDK renderiza el formulario dentro del elemento que pasas como `elementSelector`, por lo que el formulario ya está en tu diseño. Para usar tu propio botón de envío, define `showPayButton: false` en `TransactionConfig` y llama a `transaction.submit()` desde tu botón después de que `start()` se haya resuelto. Si el formulario está incompleto, `submit()` informa `INTERNAL_ERROR` con el código `FORM_INVALID` a través de `onStatus` y mantiene el formulario montado. `submit()` no está disponible para las transacciones de inscripción.

Consulta [`showView`](https://docs.y.uno/es/docs/yuno-sdk/controllers/show-view).

> [accordion] Agrega este bloque a tu controlador cuando incrustes el formulario
>
> > [tab] iOS
> >
> > ```swift theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
> >     func showView(view: AnyView?, process: SdkPayments.TransactionProcess, step: SdkPayments.TransactionViewStep) {
> >         // Place `view` in your own layout. Call process.onSubmit() from your own button.
> >     }
> > ```
>
> > [tab] Android
> >
> > ```kotlin theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
> >     override fun showView(view: Fragment, process: TransactionProcess, step: TransactionViewStep) {
> >         // Place the fragment in your own layout. Call process.onSubmit() from your own button.
> >     }
> > ```
>
> > [tab] React Native
> >
> > ```tsx theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
> >       showView: (view, process, step) => {
> >         // Render <YunoView view={view} /> in your own layout. Call process.onSubmit() from your own button.
> >       },
> > ```

## ¿Quién muestra el indicador de carga?

Esta decisión afecta si sobrescribes `showLoading`.

* **Predeterminado. El SDK muestra su propio indicador de carga** durante la tokenización,
  la creación del pago y la consulta del estado.
* **Tú muestras tu propio indicador de carga.** Sobrescribe `showLoading` para recibir
  `isLoading: true | false` y renderizar tu propia interfaz.

Consulta [`showLoading`](https://docs.y.uno/es/docs/yuno-sdk/controllers/show-loading).

> [accordion] Agrega este bloque a tu controlador cuando muestres tu propio indicador de carga
>
> > [tab] iOS
> >
> > ```swift theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
> >     func showLoading(isLoading: Bool) {
> >         // Show or hide your own loader.
> >     }
> > ```
>
> > [tab] Android
> >
> > ```kotlin theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
> >     override fun showLoading(isLoading: Boolean) {
> >         // Show or hide your own loader.
> >     }
> > ```
>
> > [tab] Web
> >
> > ```typescript theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
> >     showLoading: (isLoading) => mySpinner.toggle(isLoading),
> > ```
>
> > [tab] React Native
> >
> > ```tsx theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
> >       showLoading: (isLoading) => {
> >         // Show or hide your own loader.
> >       },
> > ```

## ¿Debe el SDK mostrar una pantalla de resultado después de la transacción?

Define el indicador [`showStatusScreen`](https://docs.y.uno/es/docs/yuno-sdk/reference/objects-you-pass#showstatusscreen)
en `TransactionConfig`.

> [accordion] Agrega esta línea a `TransactionConfig` para mostrar la pantalla de resultado del SDK
>
> > [tab] iOS
> >
> > ```swift theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
> >             showStatusScreen: true
> > ```
>
> > [tab] Android
> >
> > ```kotlin theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
> >             showStatusScreen = true,
> > ```
>
> > [tab] Web
> >
> > ```typescript theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
> >     showStatusScreen: true,
> > ```
>
> > [tab] React Native
> >
> > ```tsx theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
> >     showStatusScreen: true,
> > ```

## Implementa siempre `onStatus`

Sin importar las decisiones que tomes arriba, siempre debes
implementar `onStatus`. Es la única forma de saber cómo terminó la
transacción. Consulta [`onStatus`](https://docs.y.uno/es/docs/yuno-sdk/controllers/on-status) para saber cuándo
se ejecuta y qué estados informa en cada plataforma, y
[`Status`](https://docs.y.uno/es/docs/yuno-sdk/reference/objects-you-receive#status) para ver el
objeto que recibes.

## Referencia rápida

| Decisión | Predeterminado | Para cambiarlo | Lee |
| - | - | - | - |
| Tipo de sesión | | Pasa `checkoutSession` o `customerSession` | [Inscripción](https://docs.y.uno/es/docs/yuno-sdk/features/enrollment.md) |
| Quién crea el pago | SDK | Sobrescribe `createPayment` | [`createPayment`](https://docs.y.uno/es/docs/yuno-sdk/controllers/create-payment) |
| Quién recopila los datos | El SDK muestra los formularios | Pasa `transactionData` | [`TransactionData`](https://docs.y.uno/es/docs/yuno-sdk/reference/objects-you-pass#transaction-data) |
| Pagar con dos tarjetas | Un método de pago | Pasa un arreglo de dos elementos a `start()`, cada uno con su `amount` (Web, iOS, Android, React Native) | [Pago dividido](https://docs.y.uno/es/docs/yuno-sdk/features/split-payment.md) |
| Quién renderiza la interfaz del formulario (iOS, Android, React Native) | El SDK la presenta a pantalla completa | Sobrescribe `showView` | [`showView`](https://docs.y.uno/es/docs/yuno-sdk/controllers/show-view) |
| Quién muestra el indicador de carga | El SDK muestra el suyo | Sobrescribe `showLoading` | [`showLoading`](https://docs.y.uno/es/docs/yuno-sdk/controllers/show-loading) |
| ¿Mostrar la pantalla de resultado del SDK? | No (Web: Sí) | Define `showStatusScreen: true` en `TransactionConfig` (Web: `showStatusScreen: false` para ocultarla) | [`TransactionConfig`](https://docs.y.uno/es/docs/yuno-sdk/reference/objects-you-pass#transaction-config) |

## Próximos pasos

* [Primeros pasos](https://docs.y.uno/es/docs/yuno-sdk/get-started.md). Instala el SDK y ejecuta tu
  primera transacción.
* [Configuración](https://docs.y.uno/es/docs/yuno-sdk/reference/objects-you-pass.md#transaction-config). Referencia completa de
  `TransactionConfig`, `PaymentMethodSelected` y `TransactionData`.
* [Controladores](https://docs.y.uno/es/docs/yuno-sdk/controllers/overview.md). Referencia completa de cada controlador
  y de lo que cambia cuando lo sobrescribes.


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