Desarrollador de integración de pasarelas de pago: cómo elegirlo

Tu web tiene que cobrar, enviar leads a un CRM o leer el stock de un ERP, y tienes que decidir quién construye ese enlace. La elección pesa más que la plataforma que hay debajo, porque una integración toca dinero y datos de clientes cada día que funciona. Esta guía te ayuda a elegir al desarrollador de integración de pasarelas de pago adecuado y a comprobar su trabajo antes de firmar.

La respuesta corta: cuatro tipos de profesional pueden hacerlo (un ingeniero interno, un freelance, una agencia de integraciones o una app conectora de la plataforma). El adecuado depende de tu modelo de pago, del número de sistemas implicados y de quién mantendrá el código después del lanzamiento.

Está escrita para CTOs, responsables de ingeniería y fundadores técnicos que quieren puntuar a un candidato con evidencias, no con un discurso comercial. Tienes los criterios que separan una integración segura de una frágil, código funcional para pedir que te lo expliquen y rangos honestos de esfuerzo.

Quién puede integrar tu web con APIs de terceros#

Cuatro tipos de profesional pueden conectar tu web con una pasarela de pago, un CRM o un ERP. Cada uno encaja en una situación distinta y cada uno arrastra un riesgo que puedes comprobar antes de comprometerte. Identifica primero tu situación y después lee los criterios que valen para todas las opciones.

Freelance, agencia, equipo interno o app conectora#

Las tarjetas siguientes sitúan cada opción según para qué sirve y qué conviene verificar.

Elijas lo que elijas, la obra es un puente entre tu web y sistemas que no controlas. Las caídas del proveedor cambios de API y los mensajes duplicados son normales en ese puente, así que el trabajo del profesional es hacerlos inofensivos.

En qué destaca cada opción#

Un ingeniero interno conoce mejor tu producto y tus datos. Eso rinde cuando la integración cambia a menudo, por ejemplo si las reglas de precios o las etapas de venta evolucionan cada trimestre. El coste es que una sola persona suele concentrar todo el contexto.

Un freelance es rápido y directo en un trabajo acotado. Puede ser una buena elección para una única integración de Stripe en tu web si tienes un ingeniero que revise el código. Sin revisor, confías el camino de tus ingresos a un solo par de ojos.

Una agencia de integraciones aporta revisión, varios ingenieros y cobertura en vacaciones. Eso ayuda cuando pagos, CRM y ERP deben ponerse de acuerdo. Una app conectora es la vía más rápida si tu flujo es estándar. Deja de bastar cuando necesitas reglas que la app no expone.

Los tres trabajos ocultos en una petición#

Una petición como «conecta Stripe con la web» esconde tres trabajos. Una buena propuesta presupuesta los tres:

• El camino feliz: el comprador paga y el pedido se confirma.
• Los caminos de fallo: rechazos, reembolsos, disputas, mensajes duplicados y caídas del proveedor.
• La operación: monitorización, conciliación, rotación de claves y actualizaciones cuando el proveedor cambia su API.

Un presupuesto que cubre solo el primer trabajo parece barato y acaba costando más. Casi todo el criterio de ingeniería por el que pagas está en los trabajos dos y tres.

Elige modelo de pago y alcance PCI#

Elige el modelo de pago antes que al profesional. Decide cuántos datos de tarjeta tocan tus sistemas, lo que fija tu alcance PCI DSS y el trabajo de cumplimiento que viene después. PCI DSS es el estándar de seguridad de la industria de tarjetas, mantenido por el PCI Security Standards Council, y tu proveedor y tu banco adquirente te indican qué cuestionario de autoevaluación te corresponde.

Modelos de pago y alcance PCI

1. 01Pago con tarjetaAquí se elige el modelo

• ACheckout alojadoAlcance PCI mínimo
  1. Página externaLa tarjeta va al proveedor
  2. Resultado y tokenEs lo único que recibes
• BCampos embebidosAlcance PCI bajo
  1. Campos externosTu página solo los aloja
  2. ProveedorLa tarjeta no llega a tu servidor
• CGestión propiaAlcance PCI máximo
  1. Tu servidorLa tarjeta pasa por tus sistemas
  2. ProveedorRecibe la tarjeta de ti

Diagrama de tres modelos de pago que muestra dónde toca el número de tarjeta tu servidor y cómo crece el alcance PCI del alojado al propio

El diagrama muestra por dónde viaja el número de tarjeta en cada modelo. Cuanto más entra en tus propios sistemas, mayor es tu alcance y más tiene que demostrar tu equipo.

Checkout alojado: el menor alcance#

Tu comprador paga en una página que aloja el proveedor y después vuelve a tu web. Los datos de tarjeta nunca tocan tus servidores, así que el trabajo de cumplimiento es el más ligero. Stripe Checkout, PayPal y Mercado Pago ofrecen este modelo, y un equipo puede lanzarlo en días. Elígelo cuando la rapidez y un alcance pequeño importen más que un paso de pago con tu marca completa.

Campos embebidos: más control, alcance moderado#

Los campos alojados por el proveedor se sitúan dentro de tu página, así que el diseño se siente tuyo mientras los datos de tarjeta van directos al proveedor. El Payment Element de Stripe y componentes similares funcionan así. Tu alcance crece porque tu página carga el script del proveedor, y por eso debes proteger esa página frente a manipulaciones. Elígelo cuando el diseño del checkout afecte claramente a tu conversión.

Gestión propia de tarjetas: pocas veces compensa#

En un desarrollo propio, los números de tarjeta pasan por tus servidores. Entonces cargas con el alcance más amplio, con auditorías, controles de red y reglas de registro. Pocas tiendas online ganan lo suficiente para justificarlo. Si un candidato lo propone por defecto, pregúntale qué requisito lo obliga.

Qué preguntar sobre tu cuestionario PCI#

Pregunta al candidato qué modelo propone y qué cuestionario implica para ti. Una respuesta segura nombra el modelo, explica qué queda de tu lado (por ejemplo, proteger la página de checkout y mantener actualizado el script del proveedor) y remite a la guía de tu proveedor. Desconfía de quien dice «el PCI está resuelto» sin nombrar el modelo.

Las mismas preguntas valen para Adyen, PayPal, Mercado Pago y Redsys, que siguen los mismos patrones. Para métodos locales y pasarelas regionales, el artículo sobre desarrollo web para fintech y pagos digitales en LATAM aporta contexto.

Webhooks, reintentos e idempotencia que protegen ingresos#

Cumple los pedidos desde un evento verificado del proveedor, nunca desde la página a la que llega el comprador. Un webhook es un mensaje que el proveedor envía a tu servidor cuando ocurre algo, como un pago exitoso. Bien hecho, mantiene tus pedidos correctos cuando fallan las redes, los compradores cierran pestañas y los proveedores reintentan.

Este es el ciclo de vida que debes esperar para cada evento de pago: verificar, deduplicar, confirmar, procesar y conciliar.

Ciclo del webhook

1. 01Proveedor envía eventoPago exitoso, firmado por proveedor
2. 02Verificar firmaSe valida con el cuerpo crudo
3. 03Buscar el IDLos repetidos se omiten
4. 04Guardar ID y 200Cesan los reintentos
5. 05Worker cumple el pedidoCorre aparte de la respuesta
6. 06Pedido confirmadoRevisión nocturna cubre huecos

Diagrama del ciclo del webhook: verificar firma, comprobar ID del evento, confirmar, procesar con un worker, omitir duplicados y conciliar de noche

Verifica la firma sobre el cuerpo crudo#

Cualquiera puede enviar JSON a una URL pública. La cabecera de firma permite a tu servidor comprobar que el mensaje viene del proveedor. Se calcula sobre los bytes exactos enviados, así que la ruta debe leer el cuerpo crudo antes de cualquier parseo de JSON. Un fallo habitual es un parser JSON global que altera los bytes y hace fallar todas las comprobaciones, y la mala solución de siempre es desactivar la verificación. La documentación de webhooks de Stripe describe el esquema completo.

El ejemplo siguiente usa TypeScript, Express, el paquete oficial stripe y PostgreSQL. El patrón es el mismo en otros proveedores.

import express from 'express';
import Stripe from 'stripe';
import { Pool } from 'pg';

// Esquema (ejecutar una vez):
// CREATE TABLE processed_events (event_id text PRIMARY KEY, type text NOT NULL, received_at timestamptz NOT NULL DEFAULT now());
// CREATE TABLE jobs (id bigserial PRIMARY KEY, kind text NOT NULL, payload jsonb NOT NULL, created_at timestamptz NOT NULL DEFAULT now());

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
const endpointSecret = process.env.STRIPE_WEBHOOK_SECRET!;
const db = new Pool({ connectionString: process.env.DATABASE_URL });
const app = express();

// Se necesita el cuerpo crudo: la firma cubre los bytes exactos que envió Stripe.
app.post('/webhooks/stripe', express.raw({ type: 'application/json' }), async (req, res) => {
  let event: Stripe.Event;
  try {
    event = stripe.webhooks.constructEvent(
      req.body,
      req.headers['stripe-signature'] as string,
      endpointSecret
    );
  } catch {
    // Firma incorrecta o cuerpo alterado: rechazar y no hacer nada más.
    return res.status(400).send('Invalid signature');
  }

  const client = await db.connect();
  try {
    await client.query('BEGIN');

    // La clave primaria en event_id convierte una entrega duplicada en una operación nula.
    const inserted = await client.query(
      'INSERT INTO processed_events (event_id, type) VALUES ($1, $2) ON CONFLICT (event_id) DO NOTHING',
      [event.id, event.type]
    );

    if (inserted.rowCount === 0) {
      await client.query('ROLLBACK');
      return res.status(200).send('Duplicate ignored');
    }

    // Encolar el trabajo lento para un worker en lugar de hacerlo dentro de la petición.
    if (event.type === 'payment_intent.succeeded') {
      const intent = event.data.object as Stripe.PaymentIntent;
      await client.query('INSERT INTO jobs (kind, payload) VALUES ($1, $2)', [
        'fulfil_order',
        JSON.stringify({ orderId: intent.metadata.order_id }),
      ]);
    }

    await client.query('COMMIT');
    return res.status(200).send('ok'); // Responder rápido.
  } catch (err) {
    await client.query('ROLLBACK');
    return res.status(500).send('Retry later'); // El proveedor reintentará.
  } finally {
    client.release();
  }
});

// Petición saliente: la misma clave devuelve siempre el mismo resultado,
// así que un reintento tras un timeout no puede crear un segundo cobro.
export async function createPayment(orderId: string, amountCents: number) {
  return stripe.paymentIntents.create(
    { amount: amountCents, currency: 'usd', metadata: { order_id: orderId } },
    { idempotencyKey: `order-${orderId}-payment` }
  );
}

app.listen(3000);

Guarda el ID del evento para ignorar duplicados#

Los proveedores entregan al menos una vez, así que el mismo evento puede llegar dos veces. El handler inserta el ID del evento en una tabla con restricción de unicidad. Si la inserción entra en conflicto, el evento es un duplicado y el handler lo confirma sin repetir el trabajo.

En el ejemplo, la inserción y la creación del job comparten una transacción, así que un fallo no puede dejar un evento marcado como procesado sin su job. El handler responde 200 enseguida y un worker hace la parte lenta, como enviar el pedido a tu ERP. Si además procesas eventos con automatización, el artículo sobre webhooks e integraciones de IA como pipelines de datos muestra cómo diseñar el paso siguiente.

Claves de idempotencia en peticiones salientes#

Los duplicados también ocurren en el otro sentido. Un timeout te deja sin saber si un cobro se realizó. Una clave de idempotencia es un valor único que envías con una petición, para que el proveedor devuelva el resultado original en lugar de crear un segundo cobro.

Deriva la clave de algo estable, como el ID del pedido, igual que hace la función createPayment de arriba. Stripe documenta cuánto tiempo conserva las claves y qué pasa cuando llega la misma clave con parámetros distintos.

Concilia cada día con el proveedor#

Aun así, algún webhook puede perderse, por ejemplo durante una caída tuya. Un job nocturno lista los pagos del proveedor del último día y los compara con tus pedidos. Todo lo que figure pagado en el proveedor y falte en tu tienda se marca o se repara automáticamente.

Pregunta a un candidato cómo detectaría un evento perdido. Si la respuesta es «el cliente nos escribiría», el diseño está incompleto.

Autenticación de APIs, límites de uso y monitorización#

El mismo cuidado vale para las APIs de CRM, ERP y envíos, donde el riesgo habitual es una clave filtrada, una sincronización rota o un fallo silencioso más que una brecha de tarjetas. Un revisor debería reconocer las categorías del proyecto OWASP API Security, sobre todo la autorización rota y el consumo de recursos sin restricciones.

Mantén secretos y permisos acotados#

Los secretos van en variables de entorno o en un gestor de secretos, nunca en el repositorio, en un bundle de front-end ni en un mensaje de chat. Usa claves distintas para pruebas y producción, y da a cada clave solo los permisos que necesita. Las claves restringidas de Stripe y los scopes OAuth de un CRM lo permiten. Si una clave se filtra, un permiso estrecho limita el daño y rotarla es una tarea rutinaria.

Comprueba también que tu servidor decide quién puede leer cada registro. La autorización rota a nivel de objeto, donde un cliente lee los datos de otro cambiando un ID, aparece en primer lugar del OWASP API Security Top 10.

Backoff y colas ante los límites de uso#

Toda API limita la velocidad a la que puedes llamarla. Cuando superas el límite, responde con HTTP 429 y a menudo con una cabecera Retry-After. Una buena integración espera, reintenta con backoff exponencial y jitter aleatorio, y pone el trabajo no urgente en una cola para que un pico de pedidos no sature la API.

Los mismos patrones valen para los proveedores de IA, como muestra el artículo sobre cómo gestionar los límites de uso de las APIs de LLM en producción. Pregunta al candidato qué pasa con 5.000 actualizaciones en cola tras una caída de una hora. Una buena respuesta cubre el orden, los reintentos y un límite a la velocidad con que se drena la cola acumulada.

Alertas que llegan a una persona#

El fallo silencioso es el que más cuesta: pedidos que nunca llegan al ERP, leads que nunca llegan al CRM. La monitorización debe vigilar los jobs fallidos, la tasa de errores de webhooks y la antigüedad del elemento más viejo de la cola, y avisar a una persona o canal concreto. Un panel que nadie abre no te protege. Acuerda de antemano quién recibe la alerta, qué se considera urgente y en cuánto tiempo responde alguien.

Coste y plazos de integrar una pasarela de pago#

Los presupuestos varían mucho porque el alcance varía mucho. Los rangos siguientes son ilustrativos, sacados de conversaciones habituales de alcance y no de una encuesta ni de una tarifa. Úsalos para contrastar un presupuesto y pide después al profesional que muestre qué factores explican su cifra.

Pasarela de pago: qué mueve el rango#

Las semanas crecen con el número de métodos de pago, reembolsos parciales, impuestos, monedas y suscripciones. Cada uno añade estados que tu handler debe seguir. Un candidato que pregunta por ellos en la primera llamada está acotando con honestidad. Las fases siguientes muestran cómo podría desarrollarse una integración embebida de tamaño medio.

1. Semana 1 (ilustrativo)

   Alcance y sandbox

   Acordad el modelo de pago, los métodos y los eventos. Conecta una cuenta de pruebas y confirma la ruta de los datos.

2. Semanas 2 a 3

   Desarrollo y gestión de webhooks

   Construye el checkout, el endpoint de webhook firmado, la tabla de eventos y el worker.

3. Semana 4

   Prueba los casos de fallo

   Reproduce duplicados, simula rechazos, reembolsos y una caída del proveedor, y revisa las alertas.

4. Semana 5

   Salida a producción y conciliación

   Cambia a claves de producción, vigila los primeros pedidos y ejecuta la primera conciliación diaria.

Probar los casos de fallo merece su propia semana, porque ahí es donde los presupuestos baratos recortan.

Sincronización con CRM: el trabajo está en el mapeo#

La llamada a la API que crea un contacto es fácil. El trabajo consiste en decidir qué es un lead, qué sistema gana cuando dos valores no coinciden y cómo evitar duplicados. El esfuerzo sigue el número de campos, objetos y sentidos de sincronización. Un flujo unidireccional de formulario a CRM es rápido, mientras que una sincronización bidireccional con etapas de oportunidad lleva más.

ERP: límites heredados y pruebas#

Los proyectos de ERP son los más largos porque el otro lado marca el ritmo: APIs antiguas, exportaciones solo por lotes, entornos de prueba limitados y datos que hay que limpiar. Reserva tiempo para un sandbox que puedas romper y para un plan que mantenga alineados stock, precios y pedidos. El artículo sobre integraciones de APIs y sistemas heredados para webs corporativas profundiza en este caso.

Sea cual sea el sistema, pide primero una fase de descubrimiento de alcance cerrado. La estimación del desarrollo se apoya entonces en lo aprendido y no en una conjetura.

Quién es dueño de la integración tras el lanzamiento#

Debes ser dueño de cada cuenta, clave y línea de código que use la integración, desde el primer día. La propiedad convierte un cambio de profesional en una entrega ordenada y no en un rescate. Es también la prueba más simple de la confianza de un socio en su propio trabajo.

Cuentas y claves a tu nombre#

Crea tú las cuentas de pagos, CRM y ERP e invita al profesional como usuario con permisos limitados. Él genera claves de API restringidas dentro de tus cuentas, y tú puedes revocarlas cuando quieras. Desconfía de los acuerdos en que la cuenta de comercio del profesional procesa tus pagos, porque tu historial y tus liquidaciones no pueden irse contigo.

Código, documentación y runbooks que recibes#

En la entrega debes tener:

• El repositorio en tu propia organización, con todo el historial.
• Un README con los pasos de instalación y cada variable de entorno nombrada.
• Una lista de los eventos de webhook gestionados y qué hace cada uno.
• Un runbook para fallos comunes, como una cola atascada o un evento perdido.
• Pruebas que cubran los caminos de fallo y un diagrama de la ruta de los datos.

Mantenimiento cuando los proveedores cambian su API#

Los proveedores retiran versiones de API, rotan certificados y cambian los payloads de los webhooks. Alguien debe leer esos avisos y probar los cambios. Decide si lo cubre tu equipo, el profesional original o un plan de mantenimiento, y déjalo escrito en el acuerdo. En werun.dev para eso sirven el plan Care y el Retainer mensual, y el código y las cuentas quedan a tu nombre en ambos casos.

Cómo evaluar a un desarrollador de integración de pasarelas de pago#

Puedes juzgar a un candidato en una o dos llamadas si sabes qué escuchar. Usa las señales de alerta para filtrar propuestas y las preguntas para poner a prueba la experiencia.

Señales de alerta en una propuesta#

• Te piden tu clave secreta de API por correo o chat, o quieren usar su propia cuenta de comercio.
• Los pedidos se cumplen en la página de éxito, sin webhook.
• El presupuesto es una sola línea que no menciona reembolsos, disputas ni reintentos.
• Los números de tarjeta o los cuerpos completos de las peticiones acaban en los logs.
• Las claves de prueba y de producción comparten configuración, o no hay plan de pruebas.
• El código vive solo en el repositorio del profesional, sin condiciones de entrega.
• El PCI está «resuelto» sin que se nombre ningún modelo de pago.

Preguntas que revelan experiencia real#

Haz estas preguntas y escucha los detalles: eventos con nombre, tablas con nombre, casos de fallo con nombre. Trata la lista como una hoja de puntuación, con un punto por cada respuesta concreta.

• ¿Quién tiene las claves de API y la cuenta de comercio, y dónde se guardan las claves?
• ¿Qué modelo de pago propones y qué implica para nuestro cuestionario PCI?
• ¿Cómo verificas las firmas de webhook sobre el cuerpo crudo?
• ¿Cómo gestionas un evento duplicado o fuera de orden?
• ¿Qué clave de idempotencia envías en un cobro y en un reembolso?
• ¿Qué pasa cuando alcanzamos un límite de uso o el proveedor cae durante una hora?
• ¿Quién recibe la alerta a las 3 de la madrugada y cómo detectas un evento perdido?
• ¿Qué recibimos en la entrega: repositorio, documentación, runbooks y pruebas?

Un candidato que ya lo ha hecho responde a casi todas sin dudar, y a menudo añade la historia de una vez que salió mal. Esa historia es una evidencia útil.

Por dónde empezar esta semana#

Escribe un brief de integración de una página antes de hablar con nadie. Lista los sistemas implicados, los eventos que viajan entre ellos (pedido pagado, reembolso emitido, contacto creado, stock modificado) y qué sistema es la fuente de verdad de cada uno. Añade los métodos de pago que necesitas, los países donde vendes y quién será dueño de la integración después.

Esa página permite que cualquier candidato te dé un presupuesto comparable, y te muestra enseguida quién hace buenas preguntas. Lleva la lista de comprobación de arriba a dos o tres llamadas y compara las respuestas.

Si quieres una segunda opinión, cuéntanos tu objetivo. En werun.dev construimos integraciones de pagos, CRM y ERP con código, cuentas y claves a tu nombre, y respondemos en menos de 2 horas en días hábiles. Envíanos el brief y te diremos qué modelo de pago y qué plazo propondríamos.

Preguntas frecuentes#