Saltar al contenido principal
Cuatro pasos: instala el SDK, muestra a tu comprador sus métodos de pago, procesa el pago y confirma que se realizó. Yuno se encarga de los formularios, el enrutamiento y 3DS en el proceso.
1

Instalar

Agrega el SDK a tu plataforma e inicialízalo con tu clave de API pública.
2

Mostrar métodos de pago

Tu backend crea una sesión de checkout; el SDK muestra los métodos.
3

Procesar el pago

Inicia la transacción. Yuno muestra el formulario y ejecuta 3DS.
4

Confirmar que se realizó

El SDK te informa el resultado; tu servidor lo confirma.

Antes de comenzar

Necesitas:
  • Una cuenta de Yuno y tu public API key, disponible en el Yuno Dashboard en Developers > Credentials.
  • Un backend que pueda llamar a la API de Yuno para crear sesiones de checkout y, opcionalmente, pagos.

Instalar

Agrega el SDK para tu plataforma e inicialízalo una sola vez, al iniciar la app o la página. El constructor solo recibe tu clave de API pública. Toda la configuración específica del pago viene después.
Carga el SDK desde la CDN. Expone un SdkPayments global y despacha un evento sdk-payments-ready en window cuando está listo para usarse.
Cada versión tiene su propia ruta con la versión completa. Para pasar a una versión más reciente, cambia la versión en el src.Luego inicializa el SDK. El bundle define window.SdkPayments de forma síncrona y dispara sdk-payments-ready en window una sola vez, justo al cargar. Si tu código se ejecuta después de que el script ya cargó, ese evento ya pasó. Verifica primero el global y recurre al evento solo mientras el script sigue cargando:
Esto funciona sin importar cómo cargues el script: síncrono, async o defer. SdkPayments.initialize devuelve una Promise; usa await antes de usar el SDK.
El SDK usa el entorno según el prefijo de tu clave de API: las claves sandbox_ usan sandbox y las claves prod_ usan producción.

Mostrar métodos de pago

Pregunta a Yuno qué métodos puede usar este comprador y muéstralos en pantalla. Tu backend primero crea una sesión de checkout (la identidad del pago) y se la entrega a tu app.

Crear la sesión de checkout (backend)

Una sesión de checkout es el registro de Yuno de este pago: tu servidor se la pide a Yuno y entrega el ID a tu app.
  • Endpoint: POST /v1/checkout/sessions
  • Autenticación: encabezados public-api-key y private-secret-key (desde el Dashboard en Developers > Credentials)
  • Obligatorios: account_id, merchant_order_id, payment_description, country
  • Opcionales: customer_id (da a la sesión acceso a los métodos inscritos de ese cliente), amount, workflow
  • Devuelve: checkout_session (el valor que pasas como checkoutSession)
  • Referencia: POST /v1/checkout/sessions, con el detalle completo de solicitud, respuesta y autenticación
amount.value está en unidades mayores de la moneda: 25 son USD 25.00, no 25 centavos.
Crea la sesión con workflow: "SDK_SEAMLESS", un campo del cuerpo de creación de la sesión que se muestra arriba, no en TransactionConfig. Es lo que permite que el SDK cree el pago por ti. Sin él, la transacción termina en INTERNAL_ERROR. Consulta el campo workflow.

Mostrar los métodos en pantalla

La elección del comprador llega al SDK como un PaymentMethodSelected: solo paymentMethodType (type en Web, Android y React Native) es obligatorio; vaultedToken y transactionData (data en Web) son opcionales. Hay dos formas de obtenerlo:
  • Usa la lista de métodos prediseñada del SDK. Llama a getPaymentMethodsViews para mostrar una lista de métodos. Cuando el usuario elige uno, tu controlador onPaymentSelected recibe un PaymentMethodSelected que puedes pasar a start(). Consulta Lista de métodos de pago.
  • Crea tu propia lista. Obtén los métodos de pago disponibles desde la API de Yuno y construye PaymentMethodSelected tú mismo según la elección del usuario. Consulta GET /v1/checkout/sessions/{checkout_session}/payment-methods.

Procesar el pago

Cuando el comprador confirma, inicia el pago. Yuno muestra el formulario del método, ejecuta 3DS si el banco lo pide y crea el pago. Una transacción completa tiene tres piezas:
  1. Una sesión de checkout creada por tu backend.
  2. Un TransactionConfig con la sesión, el país, el idioma y los controladores.
  3. Un Transaction que inicias con un PaymentMethodSelected.
Los controladores son la forma en que tu código recibe los eventos del SDK. Como mínimo onStatus, que entrega el resultado final de la transacción. Proporciónalos mediante un objeto TransactionController que pasas en la configuración.
TransactionConfig en web es un objeto simple. Pásalo directamente a sdkPayments.transaction(...).
En Web, start() sin data monta el formulario del método en elementSelector y se resuelve cuando el formulario ya está en la página. El formulario tiene su propio botón Pay. El comprador lo presiona y el resultado llega después en onStatus. Para usar tu propio botón, pasa showPayButton: false en la configuración y llama a transaction.submit() desde él. Para pagar con datos que recopilaste tú mismo, pasa data en paymentMethod y el SDK ejecuta el pago sin formulario.

Campos de TransactionConfig usados aquí

Para la lista completa de campos, consulta TransactionConfig.

Confirmar que se realizó

El SDK presenta el formulario, tokeniza los datos ingresados, crea el pago, gestiona 3DS si es necesario y emite el estado final en onStatus. Úsalo para mostrar el comprobante al comprador. En Web el SDK muestra su propia pantalla de resultado por defecto. Para dibujar tú mismo el comprobante, pasa showStatusScreen: false en la configuración de la transacción.
onStatus controla tu UI. Para el cumplimiento (enviar productos, otorgar acceso), confirma el resultado en el servidor mediante webhooks o la API de pagos; consulta Confirmar en tu servidor.

Crear el pago tú mismo (opcional)

Por defecto, el SDK crea el pago por ti. No necesitas este endpoint. Si sobrescribes createPayment para tomar el control de la creación del pago, tu backend llama a este endpoint con el token de un solo uso que entrega el SDK.
  • Endpoint: POST /v1/payments
  • Obligatorios: token de un solo uso, sesión de checkout, account_id, merchant_order_id, description, country, amount (value + currency), customer_payer.id (el cliente para el que se creó la sesión) y un encabezado X-Idempotency-Key
  • Referencia: POST /v1/payments
Consulta createPayment para el flujo de sobrescritura.

Tarjetas de prueba

Las tarjetas de prueba son específicas de cada proveedor. Las tarjetas siguientes solo funcionan cuando tu sandbox enruta los pagos con tarjeta al Yuno Test Payment Gateway. Si tu enrutamiento apunta a otro proveedor (Adyen, Stripe, etc.), estas tarjetas se rechazan, a menudo sin mensaje de error. En ese caso, usa las tarjetas de prueba de ese proveedor.
Úsalas en sandbox para probar distintos escenarios. Ingresa la combinación completa exactamente como aparece: Para la lista completa de tarjetas y escenarios (Mastercard, Amex, más códigos de rechazo), consulta Detalle de tarjetas. Para flujos 3DS, usa las tarjetas de prueba 3DS.

Próximos pasos