Defina primero por qué necesita orquestación
Una capa entre el producto y los proveedores puede unificar integraciones, visibilidad operativa y algunas reglas de enrutamiento. No mejora por sí sola la tasa de pagos completados. Aclare si el problema es la caída de una pasarela, la entrada en nuevos mercados, diversos métodos, costes o devoluciones difíciles. Cada objetivo exige una medida distinta. Añadir un proveedor sin hipótesis crea más estados y más oportunidades de discrepancia entre sistemas.
Empiece con un inventario: quién recibe la orden, quién conserva la referencia, quién decide cuándo se completa el pedido y quién resuelve una excepción. Anote métodos, divisas, mercados, tipos de cliente y límites entre autorización, captura, anulación y reembolso. Los productos de cada proveedor pueden seguir reglas diferentes. La orquestación no debe fingir un ciclo de pago universal si las rutas reales tienen comportamientos distintos.
Una operación comercial, varios identificadores técnicos
Su sistema necesita un identificador interno estable, mientras cada intento y cada proveedor puede añadir su propia referencia. Mantenga explícita la relación. Pedido, intención de pago, intento, autorización y devolución son objetos distintos. Reducirlos a un solo campo de estado dificulta explicar por qué el cliente vio un error aunque salió dinero, o por qué un segundo intento creó otra autorización. El modelo debe mostrar la secuencia y no ocultarla.
Diseñe estados y transiciones permitidas con el origen de cada cambio. La interfaz muestra una vista derivada; no es la única fuente de verdad. Diferencie pendiente de confirmación, rechazado y resultado desconocido. Un resultado desconocido exige comprobar, no crear automáticamente otro pago. Para cada transición registre hora, evento original, identificador de correlación y versión de la regla aplicada. Esa evidencia ayuda en incidentes y conciliaciones.
Las rutas necesitan reglas y límites
Una regla puede elegir proveedor por método, mercado, disponibilidad o modelo de costes aprobado. Defina orden de reglas, ruta predeterminada y conducta cuando faltan datos. La disponibilidad por sí sola no debe forzar un cambio: ciertos fallos pertenecen a una transacción concreta y repetirla en otro sitio podría crear otro intento. La decisión depende de que los estados reales del proveedor permitan aclarar suficientemente el resultado anterior.
Versione la configuración. Guarde en cada transacción la versión y el motivo de la elección para explicar después diferencias entre pagos parecidos. Pruebe nuevas reglas sobre eventos históricos apropiadamente anonimizados y luego con tráfico limitado. Mida más que la aprobación inmediata: devoluciones posteriores, coste de resolver excepciones y estados sin cerrar. Una aparente mejora inicial puede trasladar trabajo a las operaciones internas.
Idempotencia y tiempos de espera deciden los reintentos
Un timeout significa que el cliente no recibió respuesta; no demuestra que el proveedor no ejecutara la operación. Use una clave de idempotencia estable para la misma operación donde la API concreta lo permita. Adyen documenta solicitudes POST idempotentes y una respuesta distinta ante un reintento simultáneo. Compruebe duración de la clave y reglas sobre parámetros antes de programar reintentos. Crear una clave nueva para un intento idéntico puede anular la protección esperada.
La cola de reintentos necesita máximo de intentos, intervalos, estado visible y vía de revisión manual. Distinga errores de conexión, indisponibilidad temporal y rechazo comercial. Un método de cliente rechazado normalmente no se arregla con repeticiones agresivas. Si el resultado sigue siendo ambiguo, consulte el estado actual mediante una interfaz segura del proveedor o lleve el caso a una cola controlada de excepciones. Muestre al cliente un mensaje sincero de espera, no una confirmación falsa.
Un webhook aporta evidencia, no una orden sin control
Una notificación asíncrona puede llegar repetida, tarde o en otro orden. Adyen recomienda verificar origen e integridad, guardar el mensaje y confirmar recepción antes del procesamiento comercial costoso; también documenta duplicados. Diseñe una entrada que compruebe firmas como indique cada proveedor, conserve el identificador original y responda con seguridad. Después procese el evento almacenado de forma idempotente y compruebe si realmente se aplicó.
El evento no debe sobrescribir el pago sin atender a su estado actual. Relaciónelo con el identificador interno, verifique una transición permitida y abra una excepción ante conflicto. Una autorización tardía no puede devolver una operación reembolsada al estado de pagada. Conserve la posibilidad de reproducir la entrada tras corregir un fallo. Minimice datos personales y de pago en registros; para vigilar el sistema suelen bastar referencia, tipo de evento y regla fallida.
La conciliación une pantalla y movimientos reales
La base interna, los webhooks y los informes del proveedor pueden discrepar temporalmente. La conciliación compara referencias estables, importe, divisa, tipo de operación y periodo. Defina qué diferencias son retrasos normales y cuáles constituyen incidentes. Separe pagos sin pedido interno, pedidos sin pago confirmado, autorizaciones duplicadas y devoluciones inesperadas. Un panel sin responsable de excepciones no resuelve ninguna de ellas.
La frecuencia de comprobación depende del volumen e impacto, no de un intervalo universal. Conserve pruebas y decisiones humanas en cada excepción. Una corrección debe poder repetirse y auditarse: quién la aprobó, qué cambió y si el cliente recibió información correcta. Si el proveedor modifica el informe, la comprobación automática debe fallar visiblemente en lugar de interpretar silenciosamente una columna ausente como cero.
Piloto y aceptación para operaciones
Empiece con un método, dos rutas claramente distintas y tráfico limitado. La matriz de pruebas debe incluir éxito, rechazo, timeout tras el envío, solicitud repetida, webhook duplicado y tardío, caída parcial y reembolso. Mida tiempo hasta el estado definitivo, resultados desconocidos y tiempo de resolución de excepciones. Un piloto real necesita un interruptor que desactive las rutas nuevas y permita volver a la vía conocida. Ensaye fallos con las personas y alertas que atenderán incidentes reales.
La entrega incluye mapa de estados, contratos de datos, claves y rotación, procedimiento de incidentes, panel operativo y responsable de conciliación. Esta página no afirma asociaciones de EXCOIN con pasarelas ni mejoras garantizadas de aprobación. Hay que revisar proveedor y requisitos legales o de seguridad para cada modelo comercial. Un buen encargo inicial describe el flujo actual, excepciones conocidas y por qué otra ruta podría aportar valor medible.