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.- Web
- iOS
- Android
- React Native
Carga el SDK desde la CDN. Expone un 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 Esto funciona sin importar cómo cargues el script: síncrono,
SdkPayments global y despacha un evento sdk-payments-ready en window cuando está listo para usarse.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: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-keyyprivate-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 comocheckoutSession) - 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.
Mostrar los métodos en pantalla
La elección del comprador llega al SDK como unPaymentMethodSelected: 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
getPaymentMethodsViewspara mostrar una lista de métodos. Cuando el usuario elige uno, tu controladoronPaymentSelectedrecibe unPaymentMethodSelectedque puedes pasar astart(). 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
PaymentMethodSelectedtú mismo según la elección del usuario. ConsultaGET /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:- Una sesión de checkout creada por tu backend.
- Un
TransactionConfigcon la sesión, el país, el idioma y los controladores. - Un
Transactionque inicias con unPaymentMethodSelected.
onStatus, que entrega el resultado final de la transacción. Proporciónalos mediante un objeto TransactionController que pasas en la configuración.
- Web
- iOS
- Android
- React Native
TransactionConfig en web es un objeto simple. Pásalo directamente a sdkPayments.transaction(...).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 enonStatus. Ú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 sobrescribescreatePayment 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 encabezadoX-Idempotency-Key - Referencia:
POST /v1/payments
createPayment para el flujo de sobrescritura.
Tarjetas de prueba
Ú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
- Configuración. Referencia completa de
TransactionConfig. Consulta tambiénPaymentMethodSelectedyTransactionData. - Controladores. Sobrescribe
showLoadingocreatePaymentpara personalizar la visualización, la carga o la creación del pago. - Guías. Lista de métodos de pago, inscripción, estilos y más.