- Métodos de pago: qué métodos se muestran y en qué orden de visualización
- Condiciones: reglas por método (moneda, país, monto, metadata) que determinan cuándo aparece un método
- Campos obligatorios: configuración de los campos del formulario por método (CVV, cuotas, dirección de facturación, etc.) tanto para el flujo con inscripción (tarjeta guardada) como para el flujo sin inscripción (primera vez)
- Configuración general: tipos de documento aceptados por país
- Estilos y configuración del SDK: colores, fuentes, formas de botones, logotipos y marca del enlace de pago
URL base
Todos los ejemplos de esta referencia usan la URL base de producción. El host de sandbox acepta los mismos endpoints y las mismas formas de payload.
Autenticación
Cada solicitud se autentica con tus credenciales de API de comercio y se limita a una sola cuenta.Yuno resuelve la organización a partir de tus credenciales. No envíes un encabezado de organización. Las credenciales ausentes o inválidas, o una cuenta que no está en la lista de permitidos, devuelven
401.Endpoints
Un checkout personalizado se identifica con uncheckout_code (un UUID). Se crea, lista, consulta, escribe y administra en su ciclo de vida a través del mismo recurso, en cinco operaciones:
{checkout_code} debe ser un UUID válido; cualquier otro valor se rechaza con 400 antes de cualquier procesamiento.
Obtienes un
checkout_code al llamar a Create Checkout (el id de nivel superior de la respuesta) o al llamar a List Checkouts (el id de cada elemento es el checkout_code). También puedes obtener uno cuando el checkout personalizado se crea en el Dashboard de Yuno o en el Checkout Builder integrado.Comportamientos clave
PUT es un upsert parcial de la configuración, no un reemplazo completo. Los métodos de pago omitidos del arreglo payment_methods conservan su estado anterior. No se eliminan ni se desactivan. Para desactivar un método, inclúyelo con is_active: false.- Configuración: actualización parcial. Solo se actualizan los métodos de pago que incluyes; los métodos omitidos conservan su estado anterior. La publicación solo actualiza métodos existentes. No se pueden crear nuevos métodos de pago mediante la API (comunícate con tu TAM de Yuno para agregar métodos).
- Estilos: fusión parcial. Los campos que omites (o envías como
null) se conservan; solo cambian los campos que incluyes. Las actualizaciones parciales de estilos son seguras. No necesitas reenviar todo el objetostyles. Para restablecer los estilos a los valores predeterminados, usaflags.force_default_styles. - El orden lo determina
order_to_show, no la posición en el arreglo. Los valores más bajos se muestran primero. - Como máximo un conjunto de condiciones por campo obligatorio. Enviar más de un conjunto de condiciones en un campo se rechaza con
400(conditions_to_override must contain at most one condition set). - Los flujos con inscripción y sin inscripción son independientes. Para CARD, configura el flujo sin inscripción mediante
fieldsy el flujo con inscripción (tarjeta guardada) medianteenrollment_fields. Para dejar un flujo sin cambios, pasa un arreglo vacío para ese lado. - Las transiciones del ciclo de vida siguen una máquina de estados. Publicar solo es válido desde
NOT_PUBLISHED. Un checkoutARCHIVEDse restaura en dos pasos (primeroNOT_PUBLISHED, luegoPUBLISHED). El checkout predeterminado no se puede archivar ni despublicar. Consulta Manage Checkout Lifecycle para ver las reglas completas. - Los cambios surten efecto de inmediato. Valida los payloads contra la URL base de sandbox antes de aplicarlos en producción.
- Cada cuerpo de solicitud se valida de forma independiente; si falla cualquier regla, se rechaza toda la solicitud con un único
400agregado y no se aplica nada. Consulta el endpoint Publish para ver la forma completa de la solicitud y los valores permitidos.
Errores
Los fallos de validación devuelven HTTP400 con un único cuerpo agregado que lista todos los problemas encontrados:
401 (autenticación / cuenta fuera de la lista de permitidos) y 404 (checkout no encontrado para la cuenta, o sin checkout predeterminado para clonar al crear). 409 cubre un nombre de checkout duplicado, o el intento de archivar o despublicar el checkout predeterminado. Consulta la página Publish para ver el esquema completo de solicitud y respuesta y ejemplos de mensajes de validación.
Idempotencia
X-Idempotency-Key es de mejor esfuerzo: el encabezado se acepta y se valida (hasta 64 caracteres), pero no se garantiza que las repeticiones de la misma clave se dupliquen. Diseña tu integración para entrega al menos una vez.