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
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.
output[]
status
Tipos de paso de proveedor
El tipo de un paso de proveedor se deriva de suprovider_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:
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:
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
- La ruta entra en
index: 1, a menos questart_splitesté definido: entonces Yuno sortea un paso de entrada por cada pago según los porcentajes. Si el paso de entrada es un pasoCANCEL, el pago se rechaza y la ruta termina. - Se ejecuta la llamada al proveedor.
- Yuno recorre
output[]de arriba abajo; gana la primera entrada cuyostatus(más el predicado de grupo enDECLINE_GROUP,MAC_CODE_GROUPySUCCEEDED_GROUP) coincide con el resultado. Una entrada conretry: trueprimero ejecuta una vez más el mismo proveedor; decide el resultado de ese segundo intento. - Si la entrada coincidente tiene
next, salta a ese paso. Si tienenext_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. - 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 porgroup_id.
group_iddebe ser un grupo de la cuenta del enrutamiento.MAC_CODE_GROUPacepta un grupo de Merchant Advice Code;DECLINE_GROUPacepta 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 comoMAC_CODE_GROUPse rechaza con400 INVALID_ROUTE_CONFIGURATION;messagesnombra elgroup_idy 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. ComoDECLINE_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 comoDECLINE_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_GROUPcondecline_types[]y singroup_idsigue funcionando como antes: Yuno crea un grupo de rechazo llamadoauto_…con esos subestados en cada guardado. Prefieregroup_idcuando el grupo ya existe, para que la cuenta no acumule grupos automáticos.DECLINE_GROUPcongroup_idydecline_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_GROUPySUCCEEDED_GROUPrequierengroup_id;SUCCEEDED_GROUPno aceptadecline_types[]. Crea esos grupos primero en el dashboard.- El mismo
group_idno puede aparecer dos veces en eloutput[]de un paso. - Las respuestas devuelven
group_idygroup_nameen cada entrada de grupo, ydecline_types[]en las entradasDECLINE_GROUPyMAC_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: trueenAPPROVED,MAC_CODE_GROUPoSUCCEEDED_GROUPse rechaza con400 INVALID_ROUTE_CONFIGURATION;retry: falsese acepta en cualquier lugar, lo que te permite enviar de vuelta un enrutamiento recuperado sin cambios.retry: trueen una entradaDECLINE_GROUPque 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 con400 INVALID_ROUTE_CONFIGURATION. Esto también aplica cuando el reintento se conservaría de la entrada almacenada porque la solicitud omiteretry: envíaretry: false.- Las respuestas siempre devuelven
retryen cada entrada (falsecuando no está definido), para que puedas ver qué ramas reintentan. - En Actualizar un enrutamiento, una entrada enviada sin
retryconserva el valor ya almacenado para esa posición; envíaretry: falseexplí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. Tieneindex y action, no tiene provider_id, connection_id ni output, y cuenta en la secuencia contigua de index.
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).
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 deCAPTURE 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.
- Solo en enrutamientos con
payment_method = "CARD", y como máximo un paso de enrutamiento inteligente por ruta. - El paso no tiene
connection_idniaction, y suoutput[]es como máximo una entradaAPPROVED. 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 pasoCAPTURE/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
APPROVEDoDECLINEDy dirigiendo todos susnexta 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 es400conNETWORK_TOKEN_NOT_ONBOARDED/NETWORK_TOKEN_NOT_SUPPORTED.
Divisiones por porcentaje
Tantostart_split como output[].next_split son listas de entradas { "index", "percentage" }:
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_splitnecesita al menos una entrada. Una sola entrada conpercentage: 100es la forma explícita de enviar todo el tráfico a un paso; omitirstart_splitsignifica 100% enindex: 1.next_splitnecesita al menos dos entradas. Para un único destino usanext.nextes opcional junto anext_split; si envías ambos,nextdebe ser la primera entrada denext_split. Las respuestas siempre incluyennext= primera entrada junto connext_split, de modo que los clientes que solo leennextconservan una alternativa.- Todo paso debe ser alcanzable desde la entrada, a través de
start_split,nextonext_split. - Se permite un
percentagede0, 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;messagesnombra la división y la regla. Una estructura incorrecta (un porcentaje decimal, unpercentagefaltante, unnext_splitde una sola entrada) se rechaza antes con400 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 accionesREFUND, 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 elAMOUNTsolo de moneda cuando esEQUALen 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 deEQUALcon un rango de montos no tiene forma en la API; se lee de vuelta como filasCURRENCY_AND_AMOUNTsin procesar y una actualización que las envía de vuelta se rechaza con400 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 mismoprovider_idyconnection_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 con400 INVALID_ROUTE_CONFIGURATIONy un mensaje que termina con “Edit this routing in the dashboard”. - Para cambiar cualquiera de esas partes, usa el dashboard.