Saltar al contenido principal
Un enrutamiento le indica a Yuno, para un payment_method en una cuenta, qué conexiones usar (proveedores de pago, análisis de fraude, pasos de 3DS y autenticación, o un paso de enrutamiento inteligente que elige el proveedor por cada pago), y te permite bifurcar por atributos del comprador (país, moneda, monto, marca de tarjeta, metadatos personalizados, horarios, límites de volumen, …), reaccionar a cada resultado (aprobación, rechazo, grupo de rechazo, Merchant Advice Code, pendiente, error) y terminar la ruta con una acción (cancelar, capturar, retener para revisión, revertir).

Estructura del recurso

Campos de nivel superior
Objeto route
route.steps[] Cada paso es un paso de proveedor (provider_id + connection_id: un proveedor de pago, fraude, 3DS o autenticación, consulta Tipos de paso de proveedor), un paso de enrutamiento inteligente (provider_id: "SMART_ROUTING" + smart_routing, consulta Pasos de enrutamiento inteligente) o un paso de acción (action). Los valores de index son contiguos y empiezan en 1, y cuentan todos los tipos.
Entradas de output[]
Enum de status
TIMEOUT y ERROR_RATE aparecían en versiones anteriores de esta página. No son miembros del enum status: enviar cualquiera de los dos rechaza todo el enrutamiento con 400, y messages lista los valores permitidos. Un tiempo de espera agotado del proveedor se maneja con INTERNAL_ERROR.

Tipos de paso de proveedor

El tipo de un paso de proveedor se deriva de su provider_id y se devuelve como provider_type. Decide qué resultados puede tener el paso y qué puede seguirle, igual que lo hace el dashboard.
PENDING en un paso PAYMENT o de enrutamiento inteligente se rechaza con 400 INVALID_ROUTE_CONFIGURATION (output PENDING is only supported on fraud, 3DS and authentication provider steps), y también se rechaza un PENDING que continúa hacia otro paso en un paso de fraude que se ejecuta después del pago. Configuración de fraude. Un paso FRAUD lleva la misma configuración que edita el dashboard, en el objeto fraud:
Las respuestas devuelven fraud en cada paso FRAUD (los campos sin valor se omiten, report_only siempre se incluye). En Actualizar un enrutamiento, un paso de fraude enviado sin fraud conserva su configuración almacenada; un paso enviado con fraud reemplaza los seis campos. Se rechaza fraud en un paso que no es un proveedor de fraude. Ajustes del paso de proveedor. Otros dos ajustes del paso de proveedor del dashboard están disponibles en la API, cada uno en el tipo de proveedor al que aplica:
Las respuestas devuelven timeout en cada paso de proveedor, network_token_enable y network_token_on en cada paso PAYMENT, y three_d_secure_exemptions en cada paso THREE_D_SECURE (un arreglo vacío cuando no hay ninguna). timeout y network_token_enable son informativos: Yuno los resuelve a partir del catálogo de proveedores y de la incorporación de la organización a los network tokens cuando se guarda el enrutamiento, y los ignora al escribir. Omitir un ajuste no es lo mismo que borrarlo. En Actualizar un enrutamiento, un paso de proveedor enviado sin network_token_on o three_d_secure_exemptions conserva el valor almacenado del paso con el mismo provider_id y connection_id; para borrarlos envía network_token_on: false o three_d_secure_exemptions: []. Un paso nuevo, o uno cuya conexión cambió, empieza con false y []. Reglas de evaluación
  1. La ruta entra en index: 1, a menos que start_split esté definido: entonces Yuno sortea un paso de entrada por cada pago según los porcentajes. Si el paso de entrada es un paso CANCEL, el pago se rechaza y la ruta termina.
  2. Se ejecuta la llamada al proveedor.
  3. Yuno recorre output[] de arriba abajo; gana la primera entrada cuyo status (más el predicado de grupo en DECLINE_GROUP, MAC_CODE_GROUP y SUCCEEDED_GROUP) coincide con el resultado. Una entrada con retry: true primero ejecuta una vez más el mismo proveedor; decide el resultado de ese segundo intento.
  4. Si la entrada coincidente tiene next, salta a ese paso. Si tiene next_split, Yuno sortea uno de sus pasos por cada pago según los porcentajes y salta allí. Si ninguno está definido o ninguna entrada coincide, la ruta termina con el resultado real del proveedor.
  5. Un salto a un paso de acción ejecuta la acción (CANCEL, CAPTURE, HOLD_FOR_REVIEW) y termina la ruta.

Grupos de resultados

Un grupo es un conjunto con nombre de resultados que mantienes en la cuenta, de modo que varias rutas puedan reaccionar a la misma lista sin repetirla. El dashboard los muestra en los ajustes de enrutamiento; la API los lee con Listar grupos de rechazo y Listar grupos de resultados exitosos y los referencia por group_id.
Reglas:
  • group_id debe ser un grupo de la cuenta del enrutamiento. MAC_CODE_GROUP acepta un grupo de Merchant Advice Code; DECLINE_GROUP acepta un grupo de rechazo o un grupo de Merchant Advice Code. Un id desconocido, un id de otra cuenta, o un grupo de rechazo enviado como MAC_CODE_GROUP se rechaza con 400 INVALID_ROUTE_CONFIGURATION; messages nombra el group_id y el tipo que realmente es.
  • Un grupo de Merchant Advice Code se comporta de forma distinta bajo cada estado, y el estado se conserva tal como lo envías. Como MAC_CODE_GROUP, la entrada coincide con un rechazo solo cuando su Merchant Advice Code está en el grupo. Como DECLINE_GROUP, también coincide con un rechazo cuyo subestado es uno de los valores del grupo, incluidos los rechazos que no llevan Merchant Advice Code. El dashboard guarda los grupos de Merchant Advice Code como DECLINE_GROUP, y un enrutamiento recuperado los devuelve así, por lo que envíalos de vuelta sin cambios para conservar cómo se enrutan. Cambiar el estado cambia qué rechazos atrapa la entrada.
  • DECLINE_GROUP con decline_types[] y sin group_id sigue funcionando como antes: Yuno crea un grupo de rechazo llamado auto_… con esos subestados en cada guardado. Prefiere group_id cuando el grupo ya existe, para que la cuenta no acumule grupos automáticos.
  • DECLINE_GROUP con group_id y decline_types[] a la vez se acepta solo cuando la lista es igual a los miembros del grupo como conjunto (el orden no importa). Esto es lo que te permite enviar de vuelta un enrutamiento recuperado sin cambios, ya que las respuestas devuelven ambos. Una lista distinta se rechaza: edita el grupo en el dashboard en su lugar.
  • MAC_CODE_GROUP y SUCCEEDED_GROUP requieren group_id; SUCCEEDED_GROUP no acepta decline_types[]. Crea esos grupos primero en el dashboard.
  • El mismo group_id no puede aparecer dos veces en el output[] de un paso.
  • Las respuestas devuelven group_id y group_name en cada entrada de grupo, y decline_types[] en las entradas DECLINE_GROUP y MAC_CODE_GROUP, con el mismo vocabulario de subestados que usan los endpoints de listado.

Reintento

retry: true en una entrada DECLINED, INTERNAL_ERROR o DECLINE_GROUP le indica a Yuno que intente el mismo proveedor una vez más cuando ocurre ese resultado, antes de seguir el next / next_split de la entrada. El segundo intento usa los demás outputs del paso como de costumbre: si se aprueba, se aplica la ruta APPROVED; si vuelve a fallar, se aplica el destino original de la entrada. Hay como máximo un reintento por entrada y por pago.
  • retry: true en APPROVED, MAC_CODE_GROUP o SUCCEEDED_GROUP se rechaza con 400 INVALID_ROUTE_CONFIGURATION; retry: false se acepta en cualquier lugar, lo que te permite enviar de vuelta un enrutamiento recuperado sin cambios.
  • retry: true en una entrada DECLINE_GROUP que referencia un grupo de Merchant Advice Code se acepta solo cuando el enrutamiento almacenado ya reintenta ese grupo en el mismo paso, de modo que un enrutamiento recuperado hace el viaje de ida y vuelta, pero una actualización no puede empezar a reintentar por Merchant Advice Codes. De lo contrario se rechaza con 400 INVALID_ROUTE_CONFIGURATION. Esto también aplica cuando el reintento se conservaría de la entrada almacenada porque la solicitud omite retry: envía retry: false.
  • Las respuestas siempre devuelven retry en cada entrada (false cuando no está definido), para que puedas ver qué ramas reintentan.
  • En Actualizar un enrutamiento, una entrada enviada sin retry conserva el valor ya almacenado para esa posición; envía retry: false explícitamente para desactivar un reintento.

Pasos de acción

Un paso de acción termina la ruta con una acción en lugar de llamar a un proveedor. Tiene index y action, no tiene provider_id, connection_id ni output, y cuenta en la secuencia contigua de index.
Reglas de action_delay:
  • Solo con action = CAPTURE; en cualquier otro paso se rechaza.
  • Duración ISO-8601 (PT5M, PT3H, P2D, P1W), de al menos 1 minuto (PT1M) y como máximo 7 días (P7D).
  • Omítelo para capturar en cuanto se procesa la aprobación (aproximadamente un minuto).
Un paso que incumple estas reglas de ubicación se rechaza con 400 INVALID_ROUTE_CONFIGURATION; messages nombra el paso y la regla (step index=N with action=CAPTURE must be reached only from an APPROVED or SUCCEEDED_GROUP output of a payment step, ... action=REVERT must be reached only from an output of a fraud step that runs after the payment, ... action=CANCEL must not be reached from an APPROVED or SUCCEEDED_GROUP output of a payment step). También se rechaza un paso CAPTURE, HOLD_FOR_REVIEW o REVERT colocado como entrada de la ruta o dentro de un start_split. En Actualizar un enrutamiento, un paso CAPTURE o HOLD_FOR_REVIEW almacenado se conserva cuando la solicitud lo omite y el output del que colgaba se envía sin next, y un paso CAPTURE enviado sin action_delay conserva el retraso almacenado, la misma regla de “gana lo almacenado” que retry. Para cambiar la captura, envía el paso con su nuevo action_delay; para eliminarla, apunta ese output a otro paso. Omitir el paso en la solicitud no lo elimina.

Pasos de enrutamiento inteligente

Un paso de enrutamiento inteligente permite que Yuno elija el proveedor por cada pago entre un conjunto de conexiones, por costo o por latencia, en lugar de fijar uno. Es la forma en la API de la caja Smart Routing del dashboard. A diferencia de CAPTURE y HOLD_FOR_REVIEW, el paso pertenece a la solicitud: una actualización que no lo incluye lo elimina, así que recupera primero el enrutamiento y envía el paso de vuelta cuando cambies otra cosa. Consulta Actualizar un enrutamiento.
Reglas, las mismas que aplica el dashboard:
  • Solo en enrutamientos con payment_method = "CARD", y como máximo un paso de enrutamiento inteligente por ruta.
  • El paso no tiene connection_id ni action, y su output[] es como máximo una entrada APPROVED. Esa entrada puede continuar hacia un paso de fraude que se ejecuta después del pago (que no debe enrutar más) o hacia un paso CAPTURE / HOLD_FOR_REVIEW; los rechazos y errores se manejan dentro del paso.
  • Debe ser alcanzable desde el paso 1. Solo los pasos de fraude, 3DS o autenticación pueden conducir a él, cada uno a través de sus outputs APPROVED o DECLINED y dirigiendo todos sus next a ese mismo paso.
  • Una infracción de las reglas es 400 INVALID_ROUTE_CONFIGURATION; una configuración de costos faltante o un network token no admitido es 400 con NETWORK_TOKEN_NOT_ONBOARDED / NETWORK_TOKEN_NOT_SUPPORTED.
Las respuestas devuelven el paso con la misma estructura. En una actualización, la solicitud reemplaza el paso; no se conserva si se omite.

Divisiones por porcentaje

Tanto start_split como output[].next_split son listas de entradas { "index", "percentage" }:
Cómo se resuelve una división: la división se evalúa una vez por pago, antes de que se ejecute el paso. Para un next_split de [{ "index": 2, "percentage": 70 }, { "index": 3, "percentage": 30 }], aproximadamente el 70% de los pagos que llegan a ese output continúan en el paso 2 y el 30% en el paso 3; cada pago individual sigue exactamente una rama. Con muchos pagos, el tráfico converge a los porcentajes configurados. Reglas:
  • start_split necesita al menos una entrada. Una sola entrada con percentage: 100 es la forma explícita de enviar todo el tráfico a un paso; omitir start_split significa 100% en index: 1.
  • next_split necesita al menos dos entradas. Para un único destino usa next. next es opcional junto a next_split; si envías ambos, next debe ser la primera entrada de next_split. Las respuestas siempre incluyen next = primera entrada junto con next_split, de modo que los clientes que solo leen next conservan una alternativa.
  • Todo paso debe ser alcanzable desde la entrada, a través de start_split, next o next_split.
  • Se permite un percentage de 0, para que puedas mantener un paso en la configuración mientras no recibe tráfico.
  • Los porcentajes son enteros. Los decimales se rechazan.
  • Una división que incumple una de estas reglas se rechaza con 400 INVALID_ROUTE_CONFIGURATION; messages nombra la división y la regla. Una estructura incorrecta (un porcentaje decimal, un percentage faltante, un next_split de una sola entrada) se rechaza antes con 400 INVALID_PARAMETERS / BAD_REQUEST.
Actualizar un enrutamiento reemplaza la configuración completa, divisiones incluidas. Un conjunto de condiciones enviado sin start_split vuelve a una única entrada en el paso 1, y un output enviado sin next_split conserva solo el next que declara, por lo que omitir una división es la forma de eliminarla. Recuperar un enrutamiento siempre devuelve los start_split y next_split actuales, de modo que un flujo de lectura, modificación y escritura los conserva a menos que los elimines a propósito.

Lo que la API no muestra

Algunas cosas que el dashboard puede configurar no tienen representación aquí: las acciones REFUND, DECLINE y END (que tampoco son acciones de paso en el dashboard), los monitores, y un paso de acción colocado donde las reglas de ubicación no lo permiten.
  • Recuperar un enrutamiento deja fuera de la respuesta esos pasos y ramas.
  • Actualizar un enrutamiento no los elimina: lo que la respuesta no puede mostrar se conserva exactamente como está almacenado, injertado en el paso del que colgaba, de modo que un recorrido de recuperar y actualizar mantiene el enrutamiento como estaba. Una condición de moneda creada en el dashboard sin monto se lee de vuelta como CURRENCY (o como el AMOUNT solo de moneda cuando es EQUAL en una moneda) y se puede actualizar a través de la API; consulta Condiciones de enrutamiento. Una excepción: una condición del dashboard que combina un operador de moneda distinto de EQUAL con un rango de montos no tiene forma en la API; se lee de vuelta como filas CURRENCY_AND_AMOUNT sin procesar y una actualización que las envía de vuelta se rechaza con 400 INVALID_ROUTE_CONFIGURATION. Edita esa condición en el dashboard. Los ajustes del paso de proveedor que la solicitud omite siguen al paso de proveedor con el mismo provider_id y connection_id; si reemplazas esa conexión, se van con ella. Un diseño almacenado que la fusión no puede volver a adjuntar de forma segura (la ruta entra por un paso oculto, un output divide el tráfico entre un paso oculto y uno visible, o un paso oculto continúa hacia un proveedor visible) se rechaza con 400 INVALID_ROUTE_CONFIGURATION y un mensaje que termina con “Edit this routing in the dashboard”.
  • Para cambiar cualquiera de esas partes, usa el dashboard.