Saltar al contenido principal
Una condición se evalúa contra un atributo del pago entrante.
Las condiciones dentro del mismo condition_sets[].conditions[] se combinan con AND lógico. Para una semántica OR, divide las condiciones en varios conjuntos de condiciones ordenados por sort_number.

Catálogo de condition_type

INSTALLMENTS no es un valor válido de condition_type por sí solo. Enviarlo rechaza todo el enrutamiento con 400 INVALID_ROUTE_CONFIGURATION.

Operadores de conditional

No existe el operador NOT_BETWEEN. No es miembro del enum conditional, por lo que enviarlo rechaza todo el enrutamiento en la deserialización: usa BETWEEN sobre los rangos complementarios en su lugar.
LESS_OR_EQUAL_THAN es el operador de VOLUME_PAYMENTS_LIMIT, donde lleva la semántica de umbral propia del límite (el total de la cuenta durante un período, ver más abajo) en lugar de una comparación genérica de un atributo, y un <= numérico simple para SUBSCRIPTION_RETRY_COUNT. No está pensado para los otros tipos de la tabla. SUBSCRIPTION_RETRY y SUBSCRIPTION_RETRY_COUNT leen subscription_context.retry_count, que Yuno adjunta a los pagos creados por su motor de suscripciones. Cuando está ausente (pagos únicos, o reintentos que activas tú mismo con POST /v1/payments) SUBSCRIPTION_RETRY EQUAL "false" coincide (el pago cuenta como primer intento) mientras que todos los operadores positivos de SUBSCRIPTION_RETRY_COUNT no coinciden. Mantén la rama de reintento (SUBSCRIPTION_RETRY EQUAL "true") por encima de tu ruta por defecto y deja que los primeros intentos caigan en la ruta por defecto; un conjunto EQUAL "false" por encima de la ruta por defecto también captura todos los pagos únicos de la cuenta. Un reintento que fuerzas con POST /v1/subscriptions/{code}/retry lleva el último conteo almacenado, que es 0 hasta que se haya ejecutado un reintento programado. Las reglas que usan estos tipos se evalúan solo al momento del pago: los listados de checkout y de cuotas omiten un conjunto que contenga solo estos tipos, y cualquiera de esos conjuntos desactiva la resolución de cuotas con varios proveedores para esa cuenta y ese método de pago; el simulador de enrutamiento siempre los evalúa como un primer intento. CONTAINS es una prueba de subcadena para METADATA. Para ADDITIONAL_FIELD compara por igualdad con los valores a los que se resuelve el campo: en un campo con varios valores, como order_fee_item_sku_code, coincide cuando cualquier ítem es igual a values[0], que es la forma de probar “la orden contiene este SKU”. La columna Rechazado al guardar se refiere solo a la cantidad de valores. Un sí significa que POST/PUT devuelve 400 cuando la cantidad no coincide, indicando el tipo de condición y el operador. Un no significa que la cantidad no se verifica al guardar, y lo que hace una cantidad incorrecta en la evaluación depende del operador: no cuentes con que sea inofensiva. TIME_PERIOD (uno o dos valores), VOLUME_PAYMENTS_LIMIT (exactamente uno) y CURRENCY (exactamente uno con EQUAL o NOT_EQUAL, uno o más con ONE_OF o NOT_ONE_OF) siempre se verifican, sin importar el operador. Donde se aplica la verificación es exacta, no un mínimo: un valor sobrante se rechaza igual que uno faltante. BETWEEN con ["0", "60", "EUR"] es un 400, no un rango truncado en silencio.
Una cantidad de valores ya almacenada en una versión de enrutamiento se conserva. Si una versión contiene una condición cuya cantidad es anterior a esta verificación, guardar esa versión de nuevo no falla por ella: solo se rechaza una cantidad incorrecta recién introducida. Esto también aplica a una versión duplicada a partir de esa fuente.

Marcas de tarjeta

CARD_BRAND acepta los valores siguientes. Un valor fuera de la lista se rechaza al guardar con 400 INVALID_CARD_BRAND, indicando el valor que causó el error. La lista se valida contra dos fuentes internas al guardar, por lo que un esquema nuevo admitido puede aceptarse antes de aparecer aquí.
Estos valores no existen en la lista anterior, por lo que una regla que lleve uno nunca coincide con un pago:AMEX, UNIONPAY y CB aparecían en versiones anteriores de esta página. Los demás son valores que se enviaron a la API y se aceptaron antes de que existiera la validación al guardar.Las reglas existentes que contengan alguno de ellos no se rechazan en un guardado posterior: se conservan tal como están, pero nunca coincidirán con un pago, así que corrígelas.

Calendarios: TIME_PERIOD

TIME_PERIOD coincide cuando el pago se crea dentro de un calendario. values[0] es cuando empieza el calendario, el values[1] opcional es cuando termina, y los campos de recurrencia lo acotan más:
Este conjunto coincide con los pagos creados en días laborables entre las 09:00 y las 18:00 (UTC−3), a partir del 1 de octubre de 2026.
Sin campos de recurrencia, la condición es un rango de fechas simple: coincide con todos los pagos entre el inicio y el fin. Con una frecuencia, un pago coincide cuando las unidades completas transcurridas desde el inicio son múltiplo de time_period_repeat_amount, su día de la semana está en time_period_repetition_days (cuando se define) y su hora está dentro de la ventana (cuando se define). YEARLY además exige el mismo mes y día que el inicio. Reglas verificadas al guardar, cada una un 400 que indica el campo: un valor que no es una fecha y hora ISO-8601 con offset, tres o más valores, una frecuencia sin cantidad o al revés, una cantidad igual a cero, una hora de inicio posterior a la de fin, una fecha de inicio posterior a la de fin, un extremo de la ventana horaria sin el otro, días de repetición o una ventana horaria sin frecuencia, un timezone que no es un offset, y limit_by o payments_count en un calendario. Un valor fuera de un enum o una cantidad igual a cero se detecta en el borde de la API como INVALID_PARAMETERS; el resto es INVALID_ROUTE_CONFIGURATION.

Límites de volumen y cantidad: VOLUME_PAYMENTS_LIMIT

VOLUME_PAYMENTS_LIMIT coincide mientras la cuenta se mantiene por debajo de un límite durante un período, contando el pago que se está enrutando. Úsalo para enviar los primeros N pagos, o los primeros X de volumen, de un día o un mes por una ruta y el resto por otra:
Este conjunto coincide mientras los pagos de la cuenta del mes calendario actual, en USD y incluido el actual, sumen 50,000 o menos.
Reglas verificadas al guardar: exactamente un valor numérico mayor que cero; sin time_period_repetition_days, time_period_start_time ni time_period_end_time; una moneda válida cuando limit_by es VOLUME (400 INVALID_VOLUME_LIMIT_CURRENCY); un período admitido (400 INVALID_VOLUME_LIMIT_PERIOD); un timezone de horas completas (400 UNSUPPORTED_VOLUME_LIMIT_TIMEZONE).
Coloca el conjunto del límite antes de la ruta que debe recibir el excedente. Una vez alcanzado el límite, el conjunto deja de coincidir, así que los conjuntos siguientes y la default_route reciben los pagos restantes del período.

Campos adicionales: ADDITIONAL_FIELD

ADDITIONAL_FIELD evalúa un campo de la solicitud de pago que no tiene un tipo de condición propio. key nombra el campo y se valida al guardar; una clave desconocida se rechaza con 400 INVALID_ROUTE_CONFIGURATION.
Todos los valores se comparan como strings; email se compara sin distinguir mayúsculas. En un campo con varios valores (ítems de la orden, tramos de aerolínea, pasajeros) cada ítem debe cumplir el operador, excepto CONTAINS, que coincide cuando cualquier ítem es igual a values[0]. Un campo ausente del pago nunca coincide, con una excepción: las claves numéricas (installments, los montos y las cantidades) se resuelven al string "null" cuando están ausentes, por lo que un NOT_EQUAL o NOT_ONE_OF sobre ellas coincide con los pagos que no llevan el campo.

Monto de los ítems de la orden: ORDER_ITEMS_AMOUNT

ORDER_ITEMS_AMOUNT suma quantity × unit_amount de los ítems de additional_data.order.items[] cuyo campo key está en item_values, y compara el total con values en currency. Úsalo para enrutar según qué parte de la canasta pertenece a una lista de productos:
Esta condición coincide con un pago en BRL cuyos ítems con SKU GC-50, GC-100 o GC-200 suman más de 500. Una canasta de GC-50 ×1 (50), GC-100 ×1 (100), GC-200 ×2 (monto unitario 200) y un ítem de 1,950 con otro SKU totaliza 550 y coincide; una canasta de ese ítem de 1,950 y GC-50 totaliza 50 y no coincide.
unit_amount se lee como el precio de una unidad en la moneda del pago; el total se redondea a 2 decimales. Un pago sin ítems de orden, sin ningún ítem de la lista, o cuyos ítems no llevan el campo key totaliza 0, por lo que LESS_THAN y GREATER_OR_EQUAL_THAN 0 coinciden con ese pago. Las respuestas devuelven la condición con la misma forma, con key siempre definido, por lo que se puede reenviar en una actualización sin cambios. Reglas verificadas al guardar, cada una un 400 INVALID_ROUTE_CONFIGURATION: un currency ausente o que no es ISO 4217, un item_values ausente o vacío, un key no admitido, otro operador, una cantidad de valores distinta de la indicada arriba, un valor no numérico, y campos de calendario o de límite. La condición se evalúa solo al momento del pago: los ítems de la orden no se conocen cuando el checkout lista los métodos de pago, por lo que ese listado y el listado de cuotas la ignoran, y el pago la evalúa.

Casos especiales

  • AMOUNT requiere currency. Las comparaciones no consideran el tipo de cambio; solo se evalúan los pagos cuya moneda coincide con el currency de la regla.
  • AMOUNT con una lista values vacía es una condición solo de moneda: { "condition_type": "AMOUNT", "conditional": "EQUAL", "values": [], "currency": "BRL" } coincide con todos los pagos en BRL, sin importar el monto. En esa forma solo se acepta EQUAL; otro operador se rechaza con 400 INVALID_ROUTE_CONFIGURATION. Las respuestas lo devuelven con esta misma forma. Para excluir una moneda o evaluar varias, usa CURRENCY.
  • CURRENCY evalúa solo la moneda del pago: { "condition_type": "CURRENCY", "conditional": "NOT_EQUAL", "values": ["USD"] } coincide con todos los pagos que no están en USD, y { "condition_type": "CURRENCY", "conditional": "ONE_OF", "values": ["EUR", "GBP"] } con todos los pagos en EUR o GBP. Las monedas van en values: EQUAL y NOT_EQUAL toman exactamente 1, ONE_OF y NOT_ONE_OF 1 o más. Cada valor es un código ISO 4217 en mayúsculas distinto de XXX, y ningún código puede repetirse; no envíes currency ni key en este tipo. Igual que AMOUNT, es válido para todos los métodos de pago. Cualquier otra cosa se rechaza con 400 INVALID_ROUTE_CONFIGURATION. Las respuestas devuelven NOT_EQUAL, ONE_OF y NOT_ONE_OF exactamente como se enviaron, por lo que la condición recuperada se puede reenviar en una actualización sin cambios. CURRENCY con EQUAL se almacena como el AMOUNT solo de moneda descrito arriba y regresa con esa forma, { "condition_type": "AMOUNT", "conditional": "EQUAL", "values": [], "currency": "USD" }; ambas formas se aceptan al crear y al actualizar.
  • METADATA requiere key. Compara payment.metadata[key]. Si la clave está ausente en el pago (o el pago no tiene metadata), la condición no coincide, sin importar el operador. Esto incluye los operadores negativos: un pago sin la clave tampoco coincide con NOT_EQUAL ni con NOT_ONE_OF. Consulta la nota de abajo para saber cómo enrutar los pagos que no llevan la clave.
  • ADDITIONAL_FIELD requiere key de la lista admitida; las claves de METADATA son libres, las de ADDITIONAL_FIELD no.
  • ORDER_ITEMS_AMOUNT requiere currency y un item_values no vacío, y item_values no se acepta en ningún otro condition_type. Consulta Monto de los ítems de la orden.
  • Los tipos de condición exclusivos de tarjeta (CARD_ISSUER_COUNTRY, CARD_TYPE, CARD_BRAND, CARD_BIN) solo son válidos cuando payment_method = "CARD".
  • COUNTRY frente a CARD_ISSUER_COUNTRY. Ambos provienen de fuentes independientes: COUNTRY coincide con el país de la transacción que tu backend envía en la solicitud de pago, mientras que CARD_ISSUER_COUNTRY coincide con el país del emisor que la consulta de BIN propia de Yuno obtiene del número de tarjeta. El mismo pago puede ser COUNTRY = US y CARD_ISSUER_COUNTRY = GB a la vez. La consulta de BIN se ejecuta antes de seleccionar un proveedor, es idéntica en sandbox y en producción, y refleja datos reales del registro de BIN, nunca la visión del procesador sobre la tarjeta.
  • No lo confundas con las Campañas de comunicaciones. Ese producto tiene su propio motor de reglas, donde AMOUNT_AND_CURRENCY con BETWEEN toma tres valores ["min", "max", "currency"]. El AMOUNT del enrutamiento toma dos valores más un currency hermano, y un tercer valor se rechaza.
  • CARD_BIN con BETWEEN expresa un rango de emisor y se valida de forma más estricta que la regla genérica de dos valores: exactamente dos valores, ambos de la misma longitud, que sea 6 u 8, todos dígitos, y el primero menor o igual que el segundo. Cualquier otra cosa es 400 INVALID_ROUTE_CONFIGURATION, así que ["411111", "41111111"] (longitudes distintas) y ["500000", "400000"] (descendente) se rechazan. A diferencia de cualquier otro tipo de condición, un CARD_BIN BETWEEN almacenado no se mantiene por compatibilidad: una versión que contenga uno mal formado se rechaza en cada guardado posterior hasta que se corrija.
  • Los campos de calendario y de límite pertenecen solo a TIME_PERIOD y VOLUME_PAYMENTS_LIMIT. Cualquiera de ellos en otro condition_type se rechaza con 400 INVALID_ROUTE_CONFIGURATION.
  • Los valores numéricos se envían como strings para coincidir con el esquema values: string[]. Yuno los interpreta según el condition_type.
Enrutar pagos que no llevan una clave de metadataComo una clave ausente nunca coincide, una regla como METADATA QA NOT_EQUAL "true" omite todos los pagos que no tienen la clave QA. Para dividir el tráfico según la presencia de una clave, haz coincidir los pagos que sí la llevan y deja que todo lo demás caiga hacia abajo:
  1. Pon primero un conjunto de condiciones con METADATA QA EQUAL "true" (menor sort_number).
  2. Pon después el conjunto de condiciones para todos los demás pagos, sin una condición METADATA sobre QA.
Los pagos con QA = "true" coinciden con el primer conjunto; los pagos sin la clave, o con cualquier otro valor, llegan al segundo.

Probar reglas de CARD_ISSUER_COUNTRY en sandbox

Los países de las tarjetas de prueba del proveedor son metadatos del simuladorEl “país” que un proveedor de pago documenta para sus tarjetas de prueba existe solo dentro del propio entorno de pruebas de ese proveedor: es metadato del simulador asociado al PAN, no una propiedad del número en sí. La consulta de BIN de Yuno resuelve en cambio la entrada real del registro, por lo que el país documentado de una tarjeta de prueba y su card_data.country_code resuelto en Yuno normalmente difieren.
Dos ejemplos con las tarjetas de prueba de Stripe: Para verificar de extremo a extremo una regla de CARD_ISSUER_COUNTRY hoy, trabaja con los valores resueltos en lugar de los documentados: la consulta es determinista:
  1. Ejecuta un pago de sandbox con una tarjeta de prueba candidata.
  2. Lee card_data.country_code del pago (detalle del pago en el dashboard, o la respuesta de Retrieve Payment).
  3. Crea la regla con ese valor. Por ejemplo, 4242 4242 4242 4242 es una tarjeta GB confiable de extremo a extremo.
La misma advertencia aplica a toda condición derivada del BIN (CARD_TYPE, CARD_BRAND), aunque el país es donde la documentación de tarjetas de prueba de los proveedores diverge con más frecuencia.