Alcance y confidencialidad
EXCOIN completó una pasarela de pagos y su ampliación para pagos con criptoactivos. No publicamos el nombre del cliente, fechas, volúmenes, procesadores, redes admitidas ni condiciones contractuales. El análisis presenta principios de ingeniería y decisiones representativas; no describe literalmente la infraestructura productiva protegida por contrato. Ningún patrón permite inferir un proveedor concreto o un resultado medido.
El trabajo supera la adición de un botón al checkout. El flujo une pedido, autorización, recepción de valor, confirmación, devolución, evidencia contable y soporte. La rama cripto añade red, activo, dirección, transacción, confirmaciones y, a veces, conversión a moneda de liquidación. Los eventos pueden retrasarse, repetirse o llegar desordenados. Se necesita un estado explícito y un historial auditable, no una simple variable pagado.
Del requisito comercial al contrato de API
Comercio, pagador y operador necesitan vistas diferentes. El comercio crea intenciones de pago, ofrece métodos, consulta estados, devuelve importes y concilia pedidos. El pagador necesita conocer cantidad, moneda, plazo y confirmación final. Operaciones necesita excepciones, conciliación y control de acceso. Así nace un inventario de operaciones basado en procesos del cliente, no una copia de los endpoints de un solo procesador.
La API pública define unidades monetarias, identidad del comercio, clave de idempotencia, correlación, errores útiles y estados consultables. Aceptar una petición y terminar su procesamiento son respuestas diferentes. Ante un timeout del proveedor, la pasarela no debe declarar éxito ni fracaso. El resultado desconocido exige comprobar el origen; el cliente puede repetir la consulta sin crear otro pago.
Máquina de estados del pago
Intención, intento, transacción del procesador, recepción real y pedido comercial son entidades distintas. Un pedido puede tener varios intentos fallidos, pero una regla define qué resultado es efectivo. Las transiciones cubren creación, espera de acción, procesamiento, confirmación, fracaso, caducidad y devoluciones completas o parciales. Cada transición tiene responsable y prueba, por ejemplo un evento autenticado o un registro de liquidación.
Un webhook tardío no puede retroceder un pago confirmado a un estado pendiente. Se reconocen duplicados por identificador y versión. Un conflicto entre notificación y consulta activa se resuelve mediante reglas de fuente de verdad. El cumplimiento del pedido es aparte: recibir dinero no demuestra que almacén, factura o entrega hayan terminado.
Tarjetas y responsabilidad sobre datos
La primera pregunta de arquitectura es quién captura y procesa el número de tarjeta. Una página alojada por el proveedor puede reducir la exposición de la aplicación, pero no elimina todas las obligaciones del comercio. El alcance de PCI DSS depende de la arquitectura y los contratos reales. La pasarela conserva referencias o tokens del procesador, evita datos de autenticación sensibles y controla los scripts de la página de pago.
Autorización, captura, anulación, disputa y devolución son procesos diferentes. La API y la consola no deben ocultarlos bajo una etiqueta genérica de pagado. Soporte requiere historial y motivos de rechazo limitados a su función; no necesita el número íntegro de tarjeta ni secretos internos para responder una reclamación.
Elección del modelo cripto
Una ampliación puede usar un intermediario especializado o recibir activos directamente en carteras bajo control del operador. El primer modelo delega parte de infraestructura y conversión; el segundo añade custodia de claves, direcciones, vigilancia de la red, tesorería y posiblemente otras obligaciones regulatorias. Cada combinación de activo y red se aprueba por separado. Afirmar que se acepta cripto no explica quién custodia fondos ni qué recibe el comercio.
El pagador debe ver activo, red, cantidad, dirección o conexión segura de cartera y vencimiento. Una red, token o memo equivocado puede causar pérdidas o recuperación costosa. Enviar desde la cartera no equivale a completar el pago. La pasarela distingue detección, confirmaciones requeridas, aceptación del proveedor y liquidación final. La política de finalidad depende de la red y del activo concretos.
Cotización, caducidad y diferencias de importe
Si el pedido está en moneda fiduciaria pero se paga con activo digital, la cotización fija tipo de cambio, comisiones, momento de emisión y validez. El movimiento del precio antes de confirmar no debe convertirse en un cobro oculto. También se decide si el comercio recibe el activo, una stablecoin o dinero fiduciario después de la conversión, porque ello cambia tesorería y contabilidad.
Pagos insuficientes, excesivos, tardíos y una segunda transferencia a la misma dirección requieren estados y procedimientos propios. La devolución automática no siempre es segura: la dirección de origen puede no pertenecer al pagador y otra red puede ser incompatible. El sistema separa casos inequívocos de excepciones que precisan aprobación humana.
Webhooks e idempotencia
Los proveedores entregan eventos asíncronos y pueden repetirlos. El receptor verifica firma u otra autenticación, ventana temporal e identificador antes de guardarlos en procesamiento duradero. Un acuse HTTP solo confirma recepción. El worker procesa de forma repetible y cambia el estado atómicamente tras un fallo. Una notificación no autenticada nunca puede liquidar un pedido.
La idempotencia rige ambos límites. Repetir la solicitud del cliente devuelve la misma intención; reintentar contra el procesador no debe capturar fondos dos veces. La clave se vincula al comercio, operación, importe y periodo definido; no se reutiliza para otra compra. También se contempla que la respuesta del proveedor llegue después del timeout del cliente.
Libro contable y conciliación
Una intención de pago no constituye un libro contable. El ledger conserva movimientos inmutables, moneda, hora, referencia, comisiones, devoluciones, conversión y relación con el comercio. Una corrección crea un nuevo asiento con causa y aprobación. Los saldos se comparan con procesador, banco o cadena según el modelo. Así se detectan ingresos sin pedido y pedidos marcados como pagados sin fondos.
La conciliación se realiza periódicamente y después de incidentes. Distingue retrasos de diferencias reales, mantiene una cola de excepciones y asigna responsables. La transacción en cadena puede estar confirmada mientras la liquidación fiduciaria sigue pendiente. El informe del comercio separa importe bruto, cambio, comisión, neto y estado, con protección adecuada de datos personales.
Devoluciones y reclamaciones
Tarjetas y cripto no comparten mecanismo de devolución. Un procesador puede gestionar devoluciones parciales; en cadena se requiere una nueva transferencia, comisión, dirección correcta y control de red. La consola debe guiar por el proceso apropiado. El pagador debe conocer la modalidad prevista antes de aprobar, no después de un fallo.
Cada devolución enlaza al pago original, máximo restante, motivo, aprobador y prueba. Dos clics no pueden generar dos salidas de fondos. Si el envío queda incierto, se consulta primero el estado real en proveedor o cadena. La disputa separa el importe controvertido del resto de la liquidación y conserva las comunicaciones pertinentes.
Identidad, riesgos y límites jurídicos
Pagador, comercio, soporte, finanzas y operaciones tienen permisos separados. Cambiar cuenta de liquidación, dirección, activo o límite necesita controles más fuertes que consultar el estado. La detección de riesgo observa reintentos anómalos, discrepancias pedido-pago y abuso de devoluciones. Las decisiones deben explicarse al personal autorizado sin revelar umbrales defensivos al atacante.
Los servicios cripto pueden caer bajo regímenes diferentes según custodia, conversión y país. MiCA es relevante en la UE, pero mencionarla no clasifica un producto concreto. El equipo jurídico del cliente y proveedores habilitados determinan identificación, vigilancia y responsabilidades antes de activar un método. El estudio no es dictamen legal ni afirma que EXCOIN tenga licencia financiera.
Seguridad y gestión de secretos
Claves API, secretos de webhooks y material de firma permanecen fuera del código. Los accesos se limitan por servicio y entorno, se rotan y auditan. Las acciones administrativas utilizan autenticación multifactor, roles separados y segunda aprobación para cambios sensibles. Protección contra repetición, validación de importes y límites de tasa alcanzan también a las llamadas internas.
La rama cripto requiere un modelo de amenazas para la custodia. Si un tercero guarda claves, contrato e integración determinan responsabilidad y respuesta a incidentes. Si las controla el sistema, se precisan separación de firmas, límites de retirada, controles de dirección, recuperación y plan ante compromiso. Los logs nunca contienen claves privadas ni tokens completos.
Pruebas y lanzamiento controlado
La matriz cubre tarjetas y cripto correctos, rechazo, timeout, webhook duplicado, red errónea, pago inferior o superior, expiración, devolución y diferencia entre confirmación y liquidación. Un sandbox ayuda, pero puede no reproducir finalidad de cadena, liquidación real o incidentes. La producción comienza con importes y segmentos limitados y conciliación revisada manualmente.
Antes de ampliar, operaciones observa tasa de finalización, antigüedad de pendientes, excepciones, demora de liquidación e intervenciones manuales. No publicamos métricas del cliente. La mejor prueba es poder explicar un pago desde pedido hasta extracto y resolver una excepción difícil sin perder dinero ni evidencia.
Checkout como experiencia del usuario
La caja explica producto, moneda, beneficiario y cuándo se confirma el pedido. Cambiar de método no debe perderlo. Un enlace alojado se une a una intención y caducidad; volver al navegador no prueba el pago. El cliente interrumpido continúa solo si la intención sigue vigente.
La caja cripto necesita más que QR. El pagador identifica activo, red, importe, comisión y vencimiento. La interfaz advierte sobre redes equivocadas y muestra estado comprobable en vez de simular éxito. Accesibilidad, idioma y móvil son criterios de aceptación; copiar la dirección evita errores de escritura.
Enrutamiento y disponibilidad de métodos
Los métodos dependen del comercio, moneda, país, producto y acuerdo. Las reglas de ruta se versionan y prueban; ocultar un método tiene explicación. Ante caída puede ofrecerse otro conservando el pedido y consentimiento claro. No se debe enviar silenciosamente el pago por condiciones diferentes.
El fallback entre proveedores evita doble captura. Antes de cambiar se verifica el primer intento y se resuelven resultados desconocidos. Operaciones ve por qué se eligió una ruta y quién posee el estado autoritativo. La disponibilidad mundial depende de permisos reales, no de un lema comercial.
Precisión de importes y unidades
Los importes usan unidades mínimas o decimales exactos. Monedas fiduciarias, tokens con distintos decimales y tasas de red no pasan por float ordinario. El contrato fija redondeo y quién asume diferencias. El extracto reconstruye precio, descuento, impuestos, tipo de cambio, comisiones y neto.
Importe cero o negativo, demasiados decimales, cambio de moneda tras cotización y devolución superior al ingreso son pruebas obligatorias. La puntuación local no cambia el valor contable. Una inconsistencia detiene el pago para investigación y no se corrige en silencio.
Seguimiento de cadena y reorganizaciones
El observador conserva checkpoints por red y bloque, relaciona depósitos con intenciones y verifica el contrato del token. Un envío nativo y un evento de token no son iguales. Recupera interrupciones RPC y cambia proveedor sin perder ni duplicar registros. Una dirección compartida entre pagos exige clave inequívoca.
Una reorganización sustituye bloques observados. Visto no significa confirmado. Se define profundidad de confirmación y respuesta si desaparece una transacción. Una discrepancia tras aceptación final es incidente, no reescritura invisible. Indexador, procesador y libro comparten identificadores.
Direcciones, claves y tesorería
Las direcciones receptoras siguen el modelo de custodia. Su asignación a pedido no cambia sin auditoría. Si el sistema crea carteras, detección de entradas se separa de firma de salidas. Límites, listas de direcciones y doble aprobación protegen fondos. Las claves jamás aparecen en logs, errores o analytics.
Tesorería decide cuándo mover, cambiar o conservar activos. Cada lote relaciona ingresos, comisiones y resultado. Una transferencia propia no es otro pago del cliente. Los saldos se concilian por red y activo; tokens con nombre parecido en cadenas distintas no son una sola partida.
Pagos al comercio
Cobrar al pagador y pagar al comercio son operaciones distintas. La salida sigue condiciones de liquidación, comisiones, devoluciones y reservas. La consola distingue planificado, enviado, confirmado y fallido. Cambiar cuenta bancaria o cartera destino exige autenticación fuerte, historial y demora para detectar fraude.
Tras un fallo se comprueba banco, proveedor o cadena antes de reintentar. Idempotencia y saldo limitan la repetición. El comercio conoce las partidas del lote y el motivo de retención. El ledger representa la deuda con el comercio independientemente del worker emisor.
Fraude frente a error técnico
Una señal de riesgo no es fallo del sistema. Tarjetas repetidas, cambios de dirección, muchas devoluciones o ingresos anómalos requieren revisión. Las decisiones automáticas guardan entradas, versión de regla y vía de recurso autorizada. El pagador recibe mensaje neutral sin conocer umbrales. Un error técnico no se disfraza de sospecha.
Con activos digitales se evalúan origen de fondos y clasificación del servicio según asesoría jurídica del cliente. La tecnología aporta evidencias, pero no inventa deberes legales ni dicta una sentencia sobre personas. Cada caso abierto tiene dueño y plazo para evitar retenciones olvidadas.
Soporte y explicación
Con un ID soporte encuentra pedido, intención, intentos, eventos, hash on-chain, devolución y payout. La vista oculta datos según rol. El cliente necesita respuesta clara: esperando confirmación, rechazado, aceptado o en revisión. Un resultado desconocido no admite plazos inventados.
Toda intervención manual registra motivo y prueba. Un empleado no puede marcar éxito solo porque recibió una captura de cartera. Puede añadirla al expediente, pero se verifica ingreso real en proveedor o cadena. La auditoría debe explicar reclamaciones meses después.
Incidentes y degradación
Los procedimientos separan caídas de checkout, procesador, webhooks, RPC, cambio y ledger. Cada caso establece si pueden abrirse intenciones, mostrarse pendientes o ejecutarse devoluciones. Sin confirmación no se libera el pedido como pagado. Tras recuperar se revisan pendientes y se concilian fuentes.
Un proveedor alternativo no garantiza continuidad automática. Estados, límites y alcance legal pueden diferir. Se ensaya cambio para método y moneda concretos, incluidos pagos en curso. El informe recoge impacto, tiempos, devoluciones y conciliación; un healthcheck verde no cierra un incidente financiero.
Datos personales y conservación
Los datos de pago incluyen identidad, IP, factura y notas de soporte. Cada campo tiene finalidad, rol y plazo conforme a contratos y ley. Logs y analítica no copian webhooks completos. Transferir a proveedores exige claridad sobre funciones y regiones.
Una solicitud de borrado considera registros contables y blockchain que no pueden suprimirse simplemente. Se minimizan datos personales en cadena y se separa identidad del hash público. Procesos de conservación eliminan exportaciones y payloads diagnósticos sin destruir evidencia obligatoria. El equipo jurídico confirma reglas.
Migración de una pasarela existente
Ampliar empieza por mapear estados, identificadores y devoluciones abiertas. La rama cripto no cambia el significado de la historia de tarjetas. Un adaptador puede atender generaciones distintas, pero cada evento indica versión de esquema. Comercios migran por segmentos con retorno para pagos sin liquidar.
La migración no se juzga por número de operaciones nuevas. Importan concordancia del ledger, justificantes antiguos y capacidad de resolver reclamaciones previas. Se archivan muestras y sumas de control. Si falta información histórica, la interfaz lo reconoce.
Versiones, contratos y socios
Otro proveedor cabe detrás de API estable solo si los estados conservan significado. Un método nuevo puede requerir red, memo, caducidad o confirmaciones; no se oculta en JSON sin validar. Tests de contrato protegen a comercios existentes ante estados nuevos o pedidos duplicados.
Cada socio posee errores, webhooks, límites, anulaciones y liquidación propios. El adaptador traduce eventos y guarda pruebas originales con acceso limitado. Al terminar el acuerdo quedan pagos, devoluciones y consultas históricas. Quitar configuración no liquida obligaciones.
Operación y extensiones
La pasarela necesita dueño de incidentes, contactos del proveedor, procedimientos ante caídas, tratamiento de colas, conciliación diaria y recuperación. La observabilidad separa disponibilidad API, éxito por método, webhooks pendientes, pagos sin conciliar y pagos al comercio. Cada alerta conduce a un responsable; el checkout consulta el registro autoritativo y no el último callback recibido.
Un nuevo activo, red o procesador pasa por el mismo contrato y matriz: unidades, precisión, finalidad, comisiones, devoluciones, roles legales, pruebas y dueño operativo. Una transacción de prueba exitosa no basta. También hay que verificar facturación, contabilidad, soporte, monitoring y retirada segura del método sin alterar pagos ya aceptados.
Referencias técnicas generales
Estos enlaces explican principios generales. No documentan la implantación confidencial del cliente.