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.- 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.
- 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, conid,name,description,discountydiscount_amount),original_amount,discount_amount,charge_amountyexpires_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. - Crea el pago con la cotización. Envía el
amountoriginal yadditional_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
- Pide a tu Technical Account Manager o Key Account Manager que habilite las promociones para tu organización. Empieza con sandbox.
- 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. - Prueba un pago en sandbox con una tarjeta que cumpla las condiciones y luego solicita producción.
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.
SCHEDULEDantes destarts_at,ACTIVEdentro de la ventana,EXPIREDdespués deends_atyDISABLEDuna 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
valuesde cada clave. Omite una clave para no tener condición en esa dimensión. - Los descuentos fijos tienen una moneda. Un descuento
FIXEDlista 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, conredemption.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 (elcreated_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:- Muestra el nombre de la promoción sobre las filas de precio.
- 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.
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.- Muestra el precio. Pasa
onPromotionQuoteUpdatedastartCheckout. Recibe la promoción que aplica al método de pago que el cliente seleccionó, ynullcuando 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í quenullpuede llegar justo antes. Muestra sucomputed.total(lo que paga el cliente),computed.discountyname, y vuelve al precio regular connull. La referencia del SDK Web lista cada campo. - Envía la cotización en el pago. Cuando el cliente paga, tu callback
yunoCreatePaymentrecibetokenWithInformation. Cuando hay una cotización vigente para esa tarjeta,tokenWithInformation.quotecontiene la línea de descuento,{ "type": "YUNO_PROMOTION", "quote_id": "…" }. Desde tu servidor, crea el pago con elamountoriginal yadditional_data.order.discounts: [tokenWithInformation.quote], como se muestra más abajo. Sin la línea, el pago se cobra completo.
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.
- Obtén la cotización. Envía el contexto del pago: cuenta, país y
payment_method. Para una tarjeta, envía dentro depayment_methodsubin(los primeros 6 a 8 dígitos de la tarjeta) concard_type, o un token (tokenovaulted_token) a partir del cual Yuno resuelve la tarjeta. Nunca ambos: unbinjunto con un token, unbinjunto con un token del vault, o untokenjunto con unvaulted_tokense rechaza con400 INVALID_PARAMETERS, y también unbincon 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ónbinsnecesita el BIN, y una con una condicióncard_typesnecesita elcard_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. - Muestra el precio. Con
200, muestracharge_amounta tu cliente. Con204, crea el pago como de costumbre, sinquote_iden una línea de descuento. Un204tambié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,5xxo sin respuesta), crea el pago también al precio completo: un pago nunca depende de una cotización. - Crea el pago con la cotización. Envía el
amountoriginal yadditional_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 contype: 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
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_amounty 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 solodiscount_amount), y los reembolsos nunca los reducen. Usastatus,sub_statusy 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 mismodiscount_amounty la misma línea de descuento completada.
Reembolsos, capturas y cancelaciones
Las operaciones trabajan sobre el monto neto que pagó el cliente, mientras queamount.value sigue siendo el original. En el ejemplo anterior, amount es 250.00 y el neto es 225.00:
- Reembolso. Deja
amountvacío para reembolsar lo que el cliente pagó y aún no se ha reembolsado (225.00). Un reembolso mayor que eso se rechaza con400 INVALID_PARAMETERS. El pago llega aREFUNDEDcuando se reembolsa el neto, así queamount.refundedes entonces igual a 225.00, no aamount.value; antes de eso susub_statusesPARTIALLY_REFUNDED. - Captura. Deja
amountvacío para capturar lo que se autorizó (el neto).amount.capturedpasa a ser 225.00 y elsub_statusCAPTURED; un monto menor lo deja enPARTIALLY_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, unaexternal_subscriptiono unaexternal_invoicese rechaza conPROMOTION_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.