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
Operadores de conditional
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í.
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:
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:
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.
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:
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
AMOUNTrequierecurrency. Las comparaciones no consideran el tipo de cambio; solo se evalúan los pagos cuya moneda coincide con elcurrencyde la regla.AMOUNTcon una listavaluesvací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 aceptaEQUAL; otro operador se rechaza con400 INVALID_ROUTE_CONFIGURATION. Las respuestas lo devuelven con esta misma forma. Para excluir una moneda o evaluar varias, usaCURRENCY.CURRENCYevalú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 envalues:EQUALyNOT_EQUALtoman exactamente 1,ONE_OFyNOT_ONE_OF1 o más. Cada valor es un código ISO 4217 en mayúsculas distinto deXXX, y ningún código puede repetirse; no envíescurrencynikeyen este tipo. Igual queAMOUNT, es válido para todos los métodos de pago. Cualquier otra cosa se rechaza con400 INVALID_ROUTE_CONFIGURATION. Las respuestas devuelvenNOT_EQUAL,ONE_OFyNOT_ONE_OFexactamente como se enviaron, por lo que la condición recuperada se puede reenviar en una actualización sin cambios.CURRENCYconEQUALse almacena como elAMOUNTsolo 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.METADATArequierekey. Comparapayment.metadata[key]. Si la clave está ausente en el pago (o el pago no tienemetadata), la condición no coincide, sin importar el operador. Esto incluye los operadores negativos: un pago sin la clave tampoco coincide conNOT_EQUALni conNOT_ONE_OF. Consulta la nota de abajo para saber cómo enrutar los pagos que no llevan la clave.ADDITIONAL_FIELDrequierekeyde la lista admitida; las claves deMETADATAson libres, las deADDITIONAL_FIELDno.ORDER_ITEMS_AMOUNTrequierecurrencyy unitem_valuesno vacío, yitem_valuesno se acepta en ningún otrocondition_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 cuandopayment_method = "CARD". COUNTRYfrente aCARD_ISSUER_COUNTRY. Ambos provienen de fuentes independientes:COUNTRYcoincide con el país de la transacción que tu backend envía en la solicitud de pago, mientras queCARD_ISSUER_COUNTRYcoincide con el país del emisor que la consulta de BIN propia de Yuno obtiene del número de tarjeta. El mismo pago puede serCOUNTRY = USyCARD_ISSUER_COUNTRY = GBa 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_CURRENCYconBETWEENtoma tres valores["min", "max", "currency"]. ElAMOUNTdel enrutamiento toma dos valores más uncurrencyhermano, y un tercer valor se rechaza. CARD_BINconBETWEENexpresa 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 es400 INVALID_ROUTE_CONFIGURATION, así que["411111", "41111111"](longitudes distintas) y["500000", "400000"](descendente) se rechazan. A diferencia de cualquier otro tipo de condición, unCARD_BIN BETWEENalmacenado 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_PERIODyVOLUME_PAYMENTS_LIMIT. Cualquiera de ellos en otrocondition_typese rechaza con400 INVALID_ROUTE_CONFIGURATION. - Los valores numéricos se envían como strings para coincidir con el esquema
values: string[]. Yuno los interpreta según elcondition_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:- Pon primero un conjunto de condiciones con
METADATAQAEQUAL"true"(menorsort_number). - Pon después el conjunto de condiciones para todos los demás pagos, sin una condición
METADATAsobreQA.
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
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:
- Ejecuta un pago de sandbox con una tarjeta de prueba candidata.
- Lee
card_data.country_codedel pago (detalle del pago en el dashboard, o la respuesta de Retrieve Payment). - Crea la regla con ese valor. Por ejemplo,
4242 4242 4242 4242es una tarjetaGBconfiable de extremo a extremo.
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.