Skip to main content
Una promoción es un descuento que defines una sola vez, por ejemplo “10% de descuento con tarjetas de crédito en octubre”. Yuno revisa un pago contra tus promociones cuando pides una cotización y cobra exactamente el precio cotizado cuando el pago lleva esa cotización. En la página de checkout de un enlace de pago, Yuno hace todo por ti y muestra el precio con descuento.
Las promociones se habilitan por organizaciónLas promociones están desactivadas por defecto. Yuno las activa para tu organización, y entonces funcionan en las cuentas de esa organización. Pide a tu Technical Account Manager o Key Account Manager que las habilite, primero en sandbox y luego en producción.Hasta que se habiliten, ninguna promoción se aplica a tus pagos: Create Promotion Quote responde 204 y el checkout muestra el precio regular.

Cómo funciona

Una promoción llega a un pago en tres pasos. La cotización es el vínculo entre ellos: es el precio que el cliente vio, y el pago cobra ese precio.
  1. Crea la promoción. Usa el Dashboard de Yuno. Defines el descuento, las fechas y las condiciones que debe cumplir un pago (BIN o rango de BIN de la tarjeta, tipo de tarjeta, método de pago, país, moneda, monto mínimo o máximo). Para dar un código a tus clientes, crea una promoción con código mediante la API. Consulta Códigos de promoción.
  2. Obtén una cotización. Antes del pago, Yuno le pone precio: qué promoción aplica, el monto original, el descuento y el cobro. La respuesta incluye quote_id, promotions (una entrada por ahora, con id, name, description, discount y discount_amount), original_amount, discount_amount, charge_amount y expires_at. En la página de checkout de un enlace de pago esto ocurre automáticamente. Con el SDK Web, el SDK la pide y entrega la cotización a tu página. Con una integración directa por API, llamas a Create Promotion Quote.
  3. Crea el pago con la cotización. Envía el amount original y additional_data.order.discounts: [{ "type": "YUNO_PROMOTION", "quote_id": "qte_…" }] en Create Payment. Yuno cobra el total cotizado y devuelve el desglose. La página de checkout de un enlace de pago agrega la línea automáticamente; con el SDK Web o la API, la agrega tu servidor.
Una promoción solo se aplica cuando el pago lleva un id de cotización o un código en una línea de descuentoYuno nunca aplica un descuento a un pago por sí mismo. Un pago sin quote_id ni code en additional_data.order.discounts se cobra completo, exactamente como hoy, aunque una promoción hubiera coincidido. Un id de cotización enviado en cualquier otro lugar se ignora, y el pago se cobra completo.

Habilita las promociones para tu organización

  1. Pide a tu Technical Account Manager o Key Account Manager que habilite las promociones para tu organización. Empieza con sandbox.
  2. Una vez activadas, da a los miembros del equipo que trabajan con promociones el permiso Manage promotions (para crearlas y deshabilitarlas) y el permiso View promotions (para verlas), y luego crea tus promociones desde el Dashboard. Cada promoción pertenece a un account_id, la cuenta que tienes seleccionada cuando la creas. Si ejecutas la misma campaña en varias cuentas, créala una vez por cuenta.
  3. Prueba un pago en sandbox con una tarjeta que cumpla las condiciones y luego solicita producción.
Yuno también puede desactivar las promociones para una organización. Cuando están desactivadas, las cotizaciones responden 204 y el checkout muestra el precio regular, así que el cliente nunca ve un descuento que el pago no respeta. Yuno también puede deshabilitar temporalmente las promociones para todas las organizaciones. Mientras estén deshabilitadas, las cotizaciones también responden 204, y un pago que aún lleva una cotización se rechaza con 422 PROMOTION_ENGINE_UNAVAILABLE: crea el pago de nuevo sin la promoción. Un pago que lleva un código se rechaza con 422 PROMOTION_NOT_APPLICABLE y el motivo ENGINE_UNAVAILABLE.

Crea una promoción

Crea promociones en el Dashboard de Yuno, o crea promociones con código mediante la API (Create Promotion). Defines el nombre, una descripción opcional (el checkout muestra ambos), el calendario, el descuento y las condiciones. El objeto Promotion describe cada campo y sus límites. Cosas que debes saber antes de crear una:
  • Las promociones no se pueden editar. El único cambio es deshabilitarla, y es definitivo. Para cambiar un descuento, deshabilita la promoción y crea una nueva. Así cada pago pasado sigue siendo explicable.
  • No se pueden eliminar. Una promoción deshabilitada o vencida permanece en tu lista.
  • El estado sigue las fechas. SCHEDULED antes de starts_at, ACTIVE dentro de la ventana, EXPIRED después de ends_at y DISABLED una vez que la deshabilitas. Las fechas son UTC.
  • Deben cumplirse todas las condiciones. AND entre las claves de condición, OR dentro de la lista values de cada clave. Omite una clave para no tener condición en esa dimensión.
  • Los descuentos fijos tienen una moneda. Un descuento FIXED lista un monto por moneda (cada uno mayor que cero). Cuando también defines una condición de monto, ambas deben listar las mismas monedas, o Yuno rechaza la promoción.

Códigos de promoción

Una promoción puede requerir un código. Créala con la API, con redemption.mode en CODE. Envía un código propio, o un prefijo y Yuno construye el código a partir de él. Luego envía el código en una línea de descuento de Create Payment: additional_data.order.discounts: [{ "code": "SUMMER10" }]. Yuno intercambia el código por una cotización, cuenta un uso del código y cobra el monto con descuento. Una promoción con código puede limitar sus usos con limits.total. Consulta Códigos de promoción para ver el flujo completo, y Create Promotion Quote para mostrar el precio de un código antes del pago. Esa respuesta es una vista previa, sin quote_id: el pago lleva el código. Un pago enviado con X-Dry-Run: true no puede llevar un código.

Cuando coinciden varias promociones

Un pago recibe una promoción. Las promociones no se acumulan. Cuando dos o más promociones coinciden con el mismo pago, Yuno elige la que más ahorra al cliente. Si dos ahorran el mismo monto, gana la más antigua (el created_at más temprano); si también hay empate, gana el id más pequeño. El resultado es el mismo cada vez que lo pides. Un código compite en la misma selección. Cuando un pago lleva un código, la promoción del código y las promociones automáticas que coinciden con el pago compiten, y el código no tiene ventaja. Un código que falla se rechaza con su propio motivo, y ninguna promoción automática ocupa su lugar. Consulta Códigos de promoción. Un descuento fijo está limitado al monto del pago, pero una promoción nunca hace que un cobro sea cero: una cotización cuyo cobro sería cero responde 204 (no se aplica nada), y un pago cuya cotización cobraría cero se rechaza con 422 PROMOTION_QUOTE_INVALID. Un pago o una solicitud de cotización que lleva un código y cobraría cero se rechaza con 422 PROMOTION_NOT_APPLICABLE y el motivo ZERO_CHARGE; consulta Códigos de promoción. Un descuento porcentual se redondea hacia arriba en la mitad a la unidad más pequeña de la moneda, y una promoción cuyo descuento es cero no se aplica.

Lo que el cliente ve en el checkout

En la página de checkout de un enlace de pago no construyes nada. En cuanto el checkout identifica la tarjeta a partir de los primeros dígitos que escribe el cliente, pide la cotización a Yuno. Cuando una promoción aplica, el checkout:
  1. Muestra el nombre de la promoción sobre las filas de precio.
  2. Actualiza el resumen de la orden: el precio original, el descuento y el nuevo total. El botón de pago sigue diciendo “Pagar”: el nuevo total está en el resumen.
Si el cliente cambia la tarjeta, o cambia a un método de pago que no califica, el resumen vuelve al precio regular. Cuando ninguna promoción aplica, el checkout se ve exactamente como hoy. Si Yuno rechaza el pago por causa de la cotización (un error PROMOTION_*, consulta más abajo), el checkout muestra “El precio cambió. Revísalo y paga de nuevo.”, se monta otra vez y el cliente ingresa la tarjeta de nuevo; las promociones quedan desactivadas durante el resto de ese checkout, así que el resumen de la orden muestra el precio regular y el cliente lo paga. Solo los enlaces de pago tienen esto. Con el SDK Web el checkout no cambia el precio: lo hace tu página, como se describe a continuación.

Integración con el SDK Web

Con el SDK Web (checkout Full y Lite), el SDK pide la cotización a Yuno con tu clave pública en cuanto identifica la tarjeta a partir de los primeros dígitos que escribe el cliente, y para cada una de las tarjetas guardadas del cliente. Cuando una promoción aplica, muestra una etiqueta junto a la tarjeta (“10% de descuento”), pero no cambia el precio: tú muestras el precio y envías la cotización en el pago. Las promociones no se aplican en Seamless. Las wallets aún no están incluidas (consulta más abajo), así que los botones externos nunca reciben una cotización por ahora.
  1. Muestra el precio. Pasa onPromotionQuoteUpdated a startCheckout. Recibe la promoción que aplica al método de pago que el cliente seleccionó, y null cuando no hay ninguna: ninguna promoción aplica, el cliente cambió la tarjeta o el método de pago, o la cotización venció. Entonces el SDK pide de nuevo y llega una nueva promoción si alguna aplica, así que null puede llegar justo antes. Muestra su computed.total (lo que paga el cliente), computed.discount y name, y vuelve al precio regular con null. La referencia del SDK Web lista cada campo.
  2. Envía la cotización en el pago. Cuando el cliente paga, tu callback yunoCreatePayment recibe tokenWithInformation. Cuando hay una cotización vigente para esa tarjeta, tokenWithInformation.quote contiene la línea de descuento, { "type": "YUNO_PROMOTION", "quote_id": "…" }. Desde tu servidor, crea el pago con el amount original y additional_data.order.discounts: [tokenWithInformation.quote], como se muestra más abajo. Sin la línea, el pago se cobra completo.
Una cotización nunca bloquea el checkout: un 204, un error o un tiempo de espera agotado deja el precio regular y el SDK no muestra etiqueta. La referencia del SDK Web lista los callbacks.

Integración directa con la API

Sin la página de checkout de un enlace de pago ni el SDK Web, tú pides la cotización y la envías en el pago. Llama a Create Promotion Quote desde tu servidor con tu clave secreta (amount en el cuerpo), o desde el navegador con tu clave pública (checkout_session en lugar de amount; Yuno toma la cuenta de la sesión de checkout, así que account_id es opcional ahí, y un valor que envíes debe coincidir con la cuenta de la sesión; country se sigue validando contra la sesión). En una integración con el SDK Web, el SDK ya hace lo segundo por ti.
  1. Obtén la cotización. Envía el contexto del pago: cuenta, país y payment_method. Para una tarjeta, envía dentro de payment_method su bin (los primeros 6 a 8 dígitos de la tarjeta) con card_type, o un token (token o vaulted_token) a partir del cual Yuno resuelve la tarjeta. Nunca ambos: un bin junto con un token, un bin junto con un token del vault, o un token junto con un vaulted_token se rechaza con 400 INVALID_PARAMETERS, y también un bin con menos de 6 dígitos, más de 8 (nunca envíes el número completo de la tarjeta) o cualquier cosa que no sean dígitos. Una promoción con una condición bins necesita el BIN, y una con una condición card_types necesita el card_type (no el BIN); sin ellos no se aplica. Un BIN de 6 dígitos solo coincide con condiciones que cubren todo su bloque de 6 dígitos, así que envía 8 dígitos cuando una promoción lista prefijos de 8 dígitos o rangos estrechos. Las wallets (Apple Pay, Google Pay) no son un destino compatible en esta versión (consulta más abajo): no construyas todavía sobre una cotización de wallet.
  2. Muestra el precio. Con 200, muestra charge_amount a tu cliente. Con 204, crea el pago como de costumbre, sin quote_id en una línea de descuento. Un 204 también significa que Yuno no pudo poner precio al pago a tiempo, que Yuno deshabilitó temporalmente las promociones, o que una promoción automática haría que el cobro fuera cero. Si la solicitud falla (408, 5xx o sin respuesta), crea el pago también al precio completo: un pago nunca depende de una cotización.
  3. Crea el pago con la cotización. Envía el amount original y additional_data.order.discounts: [{ "type": "YUNO_PROMOTION", "quote_id": "<quote_id>" }], como se muestra a continuación.

Crea el pago con la cotización

Envía el monto original y una línea de descuento con type: YUNO_PROMOTION y el quote_id en Create Payment. Yuno rechaza un pago que envía el monto con descuento en lugar del original. Cada línea tiene un type: MERCHANT (el valor por defecto) para un descuento que calculaste tú, con id, name y unit_amount; YUNO_PROMOTION para una cotización, solo con quote_id. Escribe el type exactamente como se muestra, en mayúsculas: cualquier otra grafía, como yuno_promotion, devuelve 400. Una línea YUNO_PROMOTION rechaza id, name y unit_amount; una línea MERCHANT rechaza quote_id; cualquier mezcla devuelve 400. Una línea con quote_id y sin type se interpreta como YUNO_PROMOTION, y también una línea con code y sin type (consulta Códigos de promoción). Una línea de promoción por pago, un id de cotización o un código, y como máximo 10 líneas de descuento en total. El quote_id es opaco y largo: unos 300 a 730 caracteres, así que guárdalo completo, hasta 1000 caracteres, y nunca lo analices ni lo acortes. Yuno rechaza un quote_id de más de 1000 caracteres, o con espacios o caracteres de control, con 422 PROMOTION_QUOTE_INVALID. La línea YUNO_PROMOTION se acepta solo en Create Payment (POST /v1/payments). Esta es la parte de la solicitud que importa aquí; el resto es el cuerpo de Create Payment que ya envías.
Request
No restes el descuento tú mismoEnvía el amount original y el quote_id en una línea de descuento. Yuno calcula el cobro.

Lo que lleva el pago

amount en la respuesta y en cada webhook payment.* es el monto que enviaste, nunca reescrito. El monto neto cobrado está en la transacción (transactions.amount, un número en la moneda del pago). El descuento total de Yuno es un nuevo discount_amount, la suma de las líneas YUNO_PROMOTION. Yuno completa tu línea de descuento YUNO_PROMOTION (quote_id, id = el id de la promoción, unit_amount = el descuento en la moneda del pago y, cuando Yuno lo tiene, name). Tus propias líneas MERCHANT conservan su id, name y unit_amount. Yuno pide al proveedor que cobre el monto neto; la línea de descuento llega a un proveedor, sin su quote_id, solo cuando su conector asigna los descuentos de la orden.
Response
  • amount − discount_amount = el monto de la transacción.
  • discount_amount y la línea de descuento de Yuno describen la promoción adjunta cuando se creó el pago, sea cual sea el resultado: Retrieve Payment y los webhooks de un pago rechazado, cancelado o reembolsado siguen mostrándolos (las respuestas de cancelación y reembolso llevan solo discount_amount), y los reembolsos nunca los reducen. Usa status, sub_status y la transacción para saber si se cobró el neto.
  • Un pago sin promoción es exactamente la respuesta de hoy, byte por byte.
  • Cada webhook payment.* lleva el mismo discount_amount y la misma línea de descuento completada.

Reembolsos, capturas y cancelaciones

Las operaciones trabajan sobre el monto neto que pagó el cliente, mientras que amount.value sigue siendo el original. En el ejemplo anterior, amount es 250.00 y el neto es 225.00:
  • Reembolso. Deja amount vacío para reembolsar lo que el cliente pagó y aún no se ha reembolsado (225.00). Un reembolso mayor que eso se rechaza con 400 INVALID_PARAMETERS. El pago llega a REFUNDED cuando se reembolsa el neto, así que amount.refunded es entonces igual a 225.00, no a amount.value; antes de eso su sub_status es PARTIALLY_REFUNDED.
  • Captura. Deja amount vacío para capturar lo que se autorizó (el neto). amount.captured pasa a ser 225.00 y el sub_status CAPTURED; un monto menor lo deja en PARTIALLY_CAPTURED.
  • Cancelación. Anula la autorización por el neto; el pago conserva su discount_amount.
  • Todo lo que lee el monto usa el neto: reglas de enrutamiento, fraude, 3D Secure y recibos. Un pago dividido no puede asignar más que el neto (400). Las cuotas no son una combinación compatible en esta versión (consulta más abajo).

El cliente paga el precio cotizado, o el pago se rechaza

Una cotización es válida durante 30 minutos después de emitirse (expires_at), en todas las rutas. Dentro de ese tiempo el pago cobra el precio cotizado, incluso si la fecha de fin de la promoción pasó después de emitirse la cotización. Un pago que ya se creó se completa al precio cotizado, incluso si expires_at pasa mientras tanto. Si Yuno no puede respetar la cotización, rechaza el pago: no se crea ningún pago y nunca cobra el precio completo en silencio. Vuelve a cotizar y muestra el nuevo precio, o confirma el precio completo con el cliente. Una cotización no se consume, así que un reintento después de un rechazo puede reutilizarla mientras sea válida, y una cotización puede respaldar varios pagos. El reintento es una solicitud nueva: envía un nuevo X-Idempotency-Key. Un rechazo que proviene de verificar la cotización consume su clave, y reutilizarla devuelve 400 IDEMPOTENCY_DUPLICATED. Cada rechazo en Create Payment usa el cuerpo de error estándar (code y messages[]), sin campo reason. Decide según code: messages[] es texto informativo cuya redacción puede variar para el mismo código y puede cambiar, así que nunca lo analices. La verificación compara la cuenta, el monto, el vencimiento y la sesión de checkout cuando ambas partes la tienen, además de los datos del pago que participan en las condiciones de la promoción: país, método de pago, tipo de tarjeta y BIN de la tarjeta (un BIN que el pago no lleva no se compara). Un monto modificado u otra cuenta nunca paga con la cotización, y tampoco una tarjeta con otro BIN u otro tipo de tarjeta cuando la promoción tiene una condición de tarjeta. Una promoción sin condición de tarjeta acepta cualquier tarjeta.

Qué no está incluido todavía

  • Suscripciones y pagos recurrentes. Las promociones se aplican a pagos únicos; un pago que lleva una subscription, una external_subscription o una external_invoice se rechaza con PROMOTION_SUBSCRIPTION_UNSUPPORTED, y la página de checkout de un enlace de pago de suscripción no muestra ninguna promoción y cobra el precio regular.
  • Otras rutas de pago. La línea de cotización se acepta solo en Create Payment, no en pagos multimétodo, enlaces de pago ni sesiones de checkout creados mediante la API, ni en captura. Una línea de código sigue la misma regla. Un enlace de pago abierto en su página de checkout recibe el descuento cuando el cliente paga.
  • Conversión de moneda. Una promoción se cotiza en la moneda propia del pago y Yuno no convierte un pago con promoción. Un pago con una promoción de Yuno y una conversión de moneda se rechaza con 422 PROMOTION_CONTEXT_MISMATCH: define tu precio en cada moneda y envía el pago sin la conversión.
  • Seamless. El SDK crea el pago por sí mismo, así que no se pide ni se aplica ninguna promoción.
  • Métodos de pago. Esta versión es solo para tarjetas. PSE, transferencias bancarias, métodos de efectivo y de voucher, y otros métodos de pago alternativos no son un destino compatible: no configures las condiciones de una promoción para uno, y no pidas una cotización para un pago que use uno.
  • Wallets. Apple Pay y Google Pay no son un destino compatible en esta versión. No configures una promoción para un método de pago de wallet, y no construyas sobre los botones externos del SDK Web pidiendo una cotización. Yuno no lo bloquea hoy: una promoción de tarjeta sigue aplicándose a un pago de wallet que llega a Yuno tipificado como tarjeta, así que se cotiza y recibe descuento como cualquier otro pago con tarjeta.
  • Cuotas. Pagar un monto con promoción en cuotas no es compatible en esta versión, y Yuno tampoco lo bloquea hoy: un pago con promoción enviado con cuotas recibe el descuento, pero el plan de cuotas que se muestra al cliente se calcula sobre el monto original, sin descuento.
  • Combinar promociones. Una promoción por pago.
  • Límites de uso en promociones automáticas. Solo una promoción con código puede limitar sus usos (limits.total). Una promoción automática no tiene límite de canjes, y una cotización no se consume. Ninguna promoción limita el monto total que descuenta.
  • Editar una promoción. Deshabilita y crea una nueva.
  • Cupones.