Cómo aceptar pagos sin el clásico «me cobraron, pero no hay pedido»: Payme, Click y conciliación nocturna con PostgreSQL y TypeScriptA fondo · digest del 22 de noviembre
Bodegón del escritorio de un ingeniero con un cuaderno de arquitectura de pagos, la tabla provider_txn y una consola con estado 200 OK
A fondo7 secciones≈ 31 min

Cómo aceptar pagos sin el clásico «me cobraron, pero no hay pedido»: Payme, Click y conciliación nocturna con PostgreSQL y TypeScript

Imagina una tarde cualquiera antes del lanzamiento de una tienda en línea. Conectaste los pagos con Payme Business Merchant API, probaste un pedido de 15,000 sums, la base de datos marcó el estado como «pagado» y todo parece perfecto. Luego ejecutas las pruebas automáticas en el sandbox de Payme y fallan en la primera corrida.

¿Dónde está el truco? El sandbox incluye una regla que suele pasar desapercibida al leer la documentación: envía las peticiones CreateTransaction, PerformTransaction y CancelTransaction dos veces seguidas y espera que la segunda respuesta sea idéntica a la primera, byte por byte. Una integración armada «paso a paso» se rompe por una línea aparentemente inofensiva: perform_time: Date.now(). En la segunda petición el reloj avanzó un par de cientos de milisegundos, la respuesta cambia y la prueba falla.

El sandbox no hace esto por capricho. Simula un escenario real de producción: nuestro servidor procesó el pago, pero la respuesta se perdió en el camino por un corte de red. Payme Business reintenta la misma petición y espera exactamente la misma respuesta que la primera vez. Si el backend no está preparado, el proveedor manda el pago a revisión manual y a soporte llega el peor ticket posible: «me descontaron el dinero, pero el pedido sigue sin pagarse».

Veamos cómo diseñar una recepción de pagos tolerante a fallos con PostgreSQL y TypeScript para dos proveedores distintos, Payme y Click SHOP API, y blindar el sistema con conciliación nocturna. Los ejemplos usan sums y tiyins uzbekos, pero la arquitectura de base de datos, manejo de concurrencia y detección de diferencias aplica exactamente igual a cualquier pasarela.

Las cinco reglas del contrato de Payme y la trampa del SELECT antes del INSERT

Antes de abrir el editor de código, fijemos cinco condiciones estrictas de la documentación de Payme:

  1. El protocolo es JSON-RPC 2.0 sobre HTTP POST. Siempre debes responder con código 200, incluso si el pedido no existe o el monto no coincide. Los errores de negocio viajan dentro del campo error del JSON (con un código numérico y un objeto message localizado en ru, uz y en). Cualquier otro código HTTP como 400 o 404 será interpretado por el proveedor como un fallo del sistema -32400, no como un rechazo tuyo.
  2. El monto llega como entero en tiyins (15,000 sums equivalen a 1,500,000). Nada de float ni aritmética de punto flotante.
  3. La marca de tiempo es un Unix timestamp de 13 dígitos en milisegundos.
  4. Si la respuesta a CreateTransaction o PerformTransaction se pierde, Payme repite la llamada con los mismos parámetros.
  5. Una transacción en estado «creada» vive exactamente 12 horas (43,200,000 ms); pasado ese plazo, debe cancelarse.

Del cuarto punto nace la regla clave: el identificador externo de Payme (params.id) ya funciona como clave de idempotencia. La idempotencia es la propiedad de una operación por la cual repetirla con los mismos datos produce exactamente el mismo resultado y no corrompe el estado del sistema. No hace falta inventar una clave propia encima de params.id.

La primera idea que viene a la mente es hacer un SELECT en el código para ver si el registro existe y, si no está, ejecutar un INSERT. En tu portátil local funcionará sin problemas. En producción, dos webhooks idénticos llegan con milisegundos de diferencia a dos workers distintos de Node.js. Ambos hacen SELECT, ambos ven que no hay nada y ambos ejecutan el INSERT. La condición de carrera gana la partida. La protección contra duplicados debe vivir dentro de la propia base de datos.

Una base sólida en PostgreSQL: la tabla provider_txn

Conviene guardar las transacciones de las pasarelas en una tabla dedicada desde el primer día, en lugar de amontonar columnas en orders. Un mismo pedido puede tener varios intentos de pago: el cliente empezó por Payme, cambió de opinión, volvió una hora después, pagó con Click y luego pidió un reembolso. Cuando toque investigar un incidente, necesitarás el historial completo de cada intento.

create table provider_txn (
  id serial primary key,
  -- 'payme' | 'click'
  provider text not null,
  -- params.id de Payme o click_trans_id de Click
  external_id text not null,
  order_id bigint not null references orders(id),
  amount_tiyin bigint not null,
  -- 1 creada, 2 completada, -1 cancelada antes, -2 cancelada después
  state smallint not null,
  reason smallint,
  -- params.time de Payme, necesario para GetStatement
  provider_time bigint,
  -- Los tres campos de tiempo siguientes se escriben una sola vez
  create_time bigint not null,
  perform_time bigint not null default 0,
  cancel_time bigint not null default 0,
  raw_last jsonb,
  unique (provider, external_id)
);

-- Un pedido no puede tener una segunda transacción Payme pendiente
create unique index one_pending_per_order
  on provider_txn (order_id)
  where provider = 'payme' and state = 1;

Las dos defensas principales viven directo en PostgreSQL y funcionan con la misma fiabilidad tanto con un contenedor como con veinte réplicas. La restricción única compuesta (provider, external_id) corta de raíz las condiciones de carrera entre duplicados paralelos. Por su parte, el índice único parcial one_pending_per_order (un índice con cláusula where que solo exige unicidad en las filas que cumplen la condición) impide que un mismo pedido abra una segunda transacción Payme activa en espera.

Presta atención especial a las tres columnas de tiempo: create_time, perform_time y cancel_time. El comentario «se escriben una sola vez» no es decorativo. En cuanto la transacción pasa al estado correspondiente, la marca de tiempo queda grabada en la fila y en todos los reintentos futuros se devuelve desde la base de datos sin volver a llamar a Date.now().

Máquina de estados de Payme, Transactional Outbox y autenticación

En el protocolo de Payme, una transacción tiene exactamente cuatro estados y cuatro transiciones válidas:

                        PerformTransaction
  [nada] --Create--> (1) -----------------> (2) completada
                      |                      |
      Cancel/timeout  |                      | Cancel (servicio no entregado)
                      v                      v
                    (-1)                   (-2)

Aquí 1 indica que la transacción fue creada y espera confirmación, 2 corresponde al pago completado, -1 marca la cancelación previa al cobro y -2 registra la cancelación posterior al cobro. Cualquier intento de saltarse este flujo debe devolver el error JSON-RPC -31008 («no es posible realizar la operación»). Si la transacción expiró tras el timeout de 12 horas, la pasamos a -1 con código de motivo reason = 4.

Veamos cómo funciona el manejador CreateTransaction. Dentro de una transacción de base de datos, primero buscamos la fila con SELECT ... FOR UPDATE, que bloquea de forma exclusiva esa fila hasta el commit para que ninguna petición paralela la modifique al mismo tiempo.

const TIMEOUT_MS = 43_200_000;

async function createTransaction(
  p: CreateParams,
): Promise<RpcResult> {
  return db.tx(async (tx) => {
    const existing = await tx.oneOrNone<ProviderTxn>(
      `select * from provider_txn
       where provider = 'payme' and external_id = $1
       for update`,
      [p.id],
    );

    if (existing) {
      if (existing.state !== 1) throw rpcError(-31008);
      if (Date.now() - existing.create_time > TIMEOUT_MS) {
        await cancel(tx, existing, -1, 4);
        throw rpcError(-31008);
      }
      // Reintento: devolvemos exactamente la hora guardada
      return {
        create_time: existing.create_time,
        transaction: String(existing.id),
        state: 1,
      };
    }

    const order = await tx.findOrderForUpdate(p.account.order_id);
    if (!order) throw rpcError(-31050, 'order_id');
    if (order.amount_tiyin !== p.amount) throw rpcError(-31001);
    if (order.status !== 'awaiting_payment') {
      throw rpcError(-31008);
    }

    const row = await tx.insertOrNull('provider_txn', {
      provider: 'payme',
      external_id: p.id,
      order_id: order.id,
      amount_tiyin: p.amount,
      state: 1,
      provider_time: p.time,
      create_time: Date.now(),
    });

    if (!row) {
      // Conflicto de unicidad: comprobamos si es duplicado de params.id
      const twin = await tx.findTxn('payme', p.id);
      if (twin) {
        return {
          create_time: twin.create_time,
          transaction: String(twin.id),
          state: twin.state,
        };
      }
      // Si no, saltó one_pending_per_order: el pedido ya está ocupado
      throw rpcError(-31008);
    }

    return {
      create_time: row.create_time,
      transaction: String(row.id),
      state: 1,
    };
  });
}

Aquí se aprecia por qué creamos el índice parcial one_pending_per_order. El sandbox de Payme prueba un caso engañoso: un pedido ya está esperando pago con una transacción y llega una segunda para el mismo pedido. La documentación lo describe de forma algo ambigua (pide reservar el pedido hasta el pago o el timeout), pero el sandbox espera explícitamente el código -31008. El índice parcial convierte toda esa regla en un conflicto normal de inserción: si no existe fila para ese params.id, entonces saltó el índice de pedido ocupado y devolvemos -31008.

Ahora pasamos al punto más delicado de toda la integración: PerformTransaction. Aquí es donde se pierde dinero en producción.

async function performTransaction(
  p: { id: string },
): Promise<RpcResult> {
  return db.tx(async (tx) => {
    const t = await tx.lockTxn('payme', p.id);
    if (!t) throw rpcError(-31003);

    if (t.state === 2) {
      // Reintento: devolvemos perform_time guardado, nunca Date.now()
      return {
        transaction: String(t.id),
        perform_time: t.perform_time,
        state: 2,
      };
    }

    if (t.state !== 1) throw rpcError(-31008);
    if (Date.now() - t.create_time > TIMEOUT_MS) {
      await cancel(tx, t, -1, 4);
      throw rpcError(-31008);
    }

    const performTime = Date.now();
    await tx.update('provider_txn', t.id, {
      state: 2,
      perform_time: performTime,
    });
    await tx.markOrderPaid(t.order_id, t.id);
    await tx.insert('outbox', {
      type: 'order.paid',
      order_id: t.order_id,
    });

    return {
      transaction: String(t.id),
      perform_time: performTime,
      state: 2,
    };
  });
}

Fíjate en las tres líneas previas al return. El cambio de estado en provider_txn, la actualización del pedido a paid y la inserción del evento en la tabla outbox viajan en una única transacción de PostgreSQL. ¿Qué pasa si separas esos pasos? Supón que el manejador guarda state = 2, luego sale a la red para enviar un SMS con el recibo, sufre un timeout de la pasarela externa y cae sin actualizar el pedido. Payme reintentará PerformTransaction, nuestro código verá state === 2, devolverá éxito felizmente y el pedido quedará sin pagar para siempre.

Para evitarlo se usa el patrón Transactional Outbox. En lugar de hacer llamadas de red dentro del webhook de pago, simplemente escribimos una fila-tarea en la tabla outbox dentro de la misma transacción de base de datos. Más tarde, un worker en segundo plano lee las filas nuevas de outbox y envía con calma los SMS, recibos fiscales y avisos al almacén.

Diagrama arquitectónico del patrón Transactional Outbox: escritura del estado y del evento en una sola transacción de base de datos (Fuente: microservices.io)

Con CancelTransaction la lógica también es clara, aunque esconde un detalle importante.

async function cancelTransaction(
  p: { id: string; reason: number },
) {
  return db.tx(async (tx) => {
    const t = await tx.lockTxn('payme', p.id);
    if (!t) throw rpcError(-31003);

    if (t.state === 1) {
      await cancel(tx, t, -1, p.reason);
    } else if (t.state === 2) {
      // -31007 solo si el envío o servicio ya se entregó realmente
      if (await tx.isOrderFulfilled(t.order_id)) {
        throw rpcError(-31007);
      }
      await cancel(tx, t, -2, p.reason);
    }

    // Para estados ya cancelados (-1 y -2) devolvemos la hora guardada
    const fresh = await tx.getTxn(t.id);
    return {
      transaction: String(fresh.id),
      cancel_time: fresh.cancel_time,
      state: fresh.state,
    };
  });
}

El código -31007 significa «el producto o servicio ya fue entregado, no se puede cancelar». Un error habitual es validar esto revisando si el pedido está «pagado». Pagado y entregado son cosas distintas. Si el cliente ya activó una suscripción o el repartidor entregó la caja, entonces sí devolvemos -31007. Si el pedido solo está en estado paid y aún no sale del almacén, la transacción puede pasar a -2.

Quedan dos métodos auxiliares y la autorización. CheckTransaction simplemente devuelve los campos de la fila en provider_txn (si no existe, -31003). En cambio, GetStatement suele olvidarse al inicio, aunque es el método que usa Payme para conciliar con la tienda. Devuelve la lista ascendente de transacciones cuya fecha de creación del lado de Payme (params.time en CreateTransaction) cae en el rango from <= time <= to, excluyendo las que fallaron al crearse. Precisamente por GetStatement guardamos provider_time separado de nuestro create_time local: no se deben mezclar.

Payme envía la autorización en la cabecera Authorization: Basic ..., donde la contraseña es la clave de caja del panel. Ante una clave incorrecta respondemos -32504, algo que el sandbox también comprueba. No conviene comparar ese secreto con un simple ===: la comparación estándar de cadenas se detiene en el primer carácter distinto, lo que en teoría abre una fuga por tiempo de respuesta (ataque de temporización). Node.js incluye crypto.timingSafeEqual, que siempre compara búferes en tiempo constante.

Por qué la plantilla de Payme se rompe con Click SHOP API

En cuanto funciona la integración con Payme, surge la tentación de copiar los manejadores, cambiar los nombres de los campos y conectar en una tarde la segunda pasarela: Click. Si lo haces a ciegas, la integración con Click fallará. Los protocolos funcionan de forma distinta en casi cada detalle.

Esquema de ingeniería que compara los protocolos de Payme y Click con formatos JSON-RPC y URL-encoded, cálculo de montos y códigos de respuesta

ParámetroPayme Merchant APIClick SHOP API
Formato de peticiónJSON-RPC 2.0 (HTTP POST, siempre 200)POST, application/x-www-form-urlencoded
Autorización / firmaBasic Auth (clave de caja)sign_string (MD5 con SECRET_KEY)
MontoEntero en tiyins (1500000)Cadena decimal en sums ("15000.00")
Clave de idempotenciaparams.idclick_trans_id
Pasos del protocolo6 métodos (Check, Create, Perform, Cancel, CheckTransaction, GetStatement)2 pasos: Prepare (action=0) -> Complete (action=1)
Reintento de pago completadoLa misma respuesta exitosaError -4 («Already paid»)

La fila más dolorosa de la tabla es la última. En Payme, ante un PerformTransaction repetido estás obligado a devolver exactamente el mismo JSON de éxito con el perform_time guardado. En Click, ante un Complete repetido debes devolver el error -4. Pero antes de llegar a los pasos del cobro, es muy fácil tropezar con otras dos cosas: la firma y el dinero.

En los dos pasos de Click, las fórmulas de la firma MD5 difieren en un solo campo (merchant_prepare_id aparece únicamente en el segundo paso):

Prepare:
md5(click_trans_id + service_id + SECRET_KEY + merchant_trans_id
    + amount + action + sign_time)

Complete:
md5(click_trans_id + service_id + SECRET_KEY + merchant_trans_id
    + merchant_prepare_id + amount + action + sign_time)

Aquí se esconde un error clásico. Debes concatenar los campos para el hash exactamente como llegaron en el cuerpo del formulario, antes de convertir nada a números o fechas. Si Click envió amount como "15000.00" y tu framework lo convirtió al número 15000 y luego otra vez a la cadena "15000", la firma no coincidirá y empezarás a rechazar pagos válidos con el código -1.

Para comparar el monto con el pedido de nuestra base de datos, convertimos la cadena a tiyins enteros usando BigInt, sin Number ni parseFloat, para evitar sorpresas como 19.99 * 100 === 1998.9999999999998:

function sumToTiyin(s: string): bigint {
  // Aceptamos sums enteros y hasta dos decimales tras el punto
  const m = /^(\d+)(?:\.(\d{1,2}))?$/.exec(s);
  if (!m) throw new ClickError(-2);
  const sums = BigInt(m[1]) * 100n;
  const tiyins = BigInt((m[2] ?? '').padEnd(2, '0'));
  return sums + tiyins;
}

La función separa la cadena con una expresión regular en parte entera y decimal, rellena los decimales con ceros hasta dos dígitos y lo suma todo en BigInt. La paleta completa de códigos en la documentación de errores de Click SHOP API es compacta: 0 (éxito), -1 (firma inválida), -2 (monto inválido), -3 (acción no encontrada), -4 (ya pagado), -5 (pedido no encontrado), -6 (transacción no encontrada), -7 (error al actualizar), -8 (error en la petición de Click) y -9 (transacción cancelada).

Prepare, Complete y reembolso con reversal en Click

En el primer paso (Prepare, action === '0'), Click pregunta a nuestro backend: ¿el pedido sigue vigente, el monto es correcto y el producto se puede entregar? Aquí conviene reservar el inventario en el almacén.

async function prepare(r: ClickPrepare): Promise<ClickResponse> {
  if (!verifySign(r, { withPrepareId: false })) return err(-1);
  if (r.action !== '0') return err(-3);

  return db.tx(async (tx) => {
    const order = await tx.findOrderForUpdate(r.merchant_trans_id);
    if (!order) return err(-5);
    if (order.status === 'paid') return err(-4);
    if (order.amount_tiyin !== sumToTiyin(r.amount)) {
      return err(-2);
    }

    // insert ... on conflict do nothing, luego select:
    // un Prepare repetido devolverá el mismo merchant_prepare_id
    const t = await tx.insertOrGet(
      'provider_txn',
      { provider: 'click', external_id: r.click_trans_id },
      {
        order_id: order.id,
        amount_tiyin: sumToTiyin(r.amount),
        state: 1,
        create_time: Date.now(),
      },
    );

    if (t.state < 0) return err(-9);
    return ok({
      click_trans_id: r.click_trans_id,
      merchant_trans_id: r.merchant_trans_id,
      merchant_prepare_id: t.id,
    });
  });
}

Usamos exactamente la misma tabla provider_txn que con Payme. El índice único compuesto (provider, external_id) protege contra un Prepare duplicado, y la clave primaria t.id viaja a Click como merchant_prepare_id.

En el segundo paso (Complete, action === '1'), Click nos devuelve ese merchant_prepare_id e informa el resultado del cargo.

async function complete(r: ClickComplete): Promise<ClickResponse> {
  if (!verifySign(r, { withPrepareId: true })) return err(-1);
  if (r.action !== '1') return err(-3);

  return db.tx(async (tx) => {
    const t = await tx.lockTxnById(Number(r.merchant_prepare_id));
    if (!t || t.external_id !== r.click_trans_id) return err(-6);
    // Reintento de Complete sobre pago completado -> -4 ("Already paid")
    if (t.state === 2) return err(-4);
    if (t.state < 0) return err(-9);

    if (Number(r.error) < 0) {
      // El pago falló del lado de Click: cancelamos en nuestra BD
      await cancel(tx, t, -1, null);
      return err(-9);
    }

    await tx.update('provider_txn', t.id, {
      state: 2,
      perform_time: Date.now(),
    });
    await tx.markOrderPaid(t.order_id, t.id);
    await tx.insert('outbox', {
      type: 'order.paid',
      order_id: t.order_id,
    });

    return ok({
      click_trans_id: r.click_trans_id,
      merchant_trans_id: r.merchant_trans_id,
      merchant_confirm_id: t.id,
    });
  });
}

Fíjate en la rama Number(r.error) < 0. Si el cliente no tenía saldo suficiente o el banco rechazó el cargo, Click igual envía Complete, pero con un campo error negativo. En ese momento estamos obligados a marcar la transacción local como cancelada (state = -1) y responder -9.

Ahora veamos una regla sacada de una nota al pie de Click SHOP API, que casi siempre se descubre tras el primer incidente serio. Supón que Prepare pasó, el dinero se descontó de la tarjeta del cliente, llegó Complete con error = 0, pero la última unidad del producto se vendió a otro comprador justo en ese minuto. No puedes responder con error al Complete: el dinero del cliente quedaría atrapado y el pago pasaría a revisión manual. Según el contrato de Click, tras el cobro solo puedes devolver error en Complete por dos razones: pago ya confirmado (-4) o cancelado (-9).

La salida correcta es responder a Click con éxito (0) e inmediatamente iniciar una devolución (reversal, la anulación forzada de un pago ya procesado) mediante Click Merchant API: DELETE /v2/merchant/payment/reversal/:service_id/:payment_id. No puedes postergarlo. La anulación tiene límites estrictos: el pago debe estar completado y hecho con tarjeta en línea, solo se puede revertir dentro del mes contable actual (del mes anterior, únicamente el primer día del mes nuevo) y el sistema UZCARD tiene derecho a rechazar la anulación. Si detectas la diferencia al cerrar el mes y no el mismo día, el reversal automático ya no funcionará.

Prueba el simulador interactivo de abajo: elige un proveedor y un fallo operativo para comparar cómo reaccionan Payme y Click ante el mismo escenario.

Simulador de webhook de pagos: Payme frente a Click

Cuando ves ambos contratos lado a lado, desaparece cualquier gana de meter Payme y Click en un mismo controlador «universal». Solo se comparte el esquema provider_txn + outbox; los adaptadores de protocolo de cada pasarela deben vivir por separado y respetar al pie de la letra sus códigos de respuesta.

Tercera capa de defensa: conciliación nocturna (reconciliation)

La idempotencia y los índices de PostgreSQL frenan las condiciones de carrera y los reintentos, pero no pueden contra otros fallos cotidianos. Un proceso pudo caer justo entre el commit y el envío de la respuesta HTTP. Un gestor pudo cambiar manualmente el estado del pedido en el panel. El proveedor pudo cancelar la operación de su lado sin enviar webhook. Estas discrepancias solo se detectan con una conciliación regular (reconciliation), y hay que correrla cada noche, no una vez al mes antes del cierre contable.

Primero, el job ejecuta cuatro consultas SQL sobre los invariantes internos de nuestra base. En un sistema sano, las cuatro deben devolver cero filas. Cada fila encontrada es un incidente real:

Esquema arquitectónico isométrico de la conciliación nocturna de transacciones comparando PostgreSQL con los registros externos de proveedores

-- 1. Dinero cobrado, pero pedido sin pagar (paid_not_fulfilled)
select t.*
from provider_txn t
join orders o on o.id = t.order_id
where t.state = 2
  and o.status <> 'paid';

-- 2. Pedido pagado sin transacción completada (order_without_txn)
select o.*
from orders o
where o.status = 'paid'
  and not exists (
    select 1 from provider_txn t
    where t.order_id = o.id and t.state = 2
  );

-- 3. Doble pago de un mismo pedido (double_payment)
select order_id, count(*)
from provider_txn
where state = 2
group by order_id
having count(*) > 1;

-- 4. Transacciones atascadas en state = 1 más de 12 horas (stuck_pending)
select *
from provider_txn
where state = 1
  and create_time <
      (extract(epoch from now()) * 1000)::bigint - 43200000;

Surge una duda lógica: ¿de dónde saldría el tercer caso (double_payment) si ya tenemos el índice parcial one_pending_per_order? Recuerda su condición: where provider = 'payme' and state = 1. Solo protege contra duplicados dentro de Payme. Si un comprador abandona el pago en Payme y cinco minutos después paga el mismo pedido con Click, el sistema no debería bloquearlo. Rechazar al cliente por una coincidencia rara es mucho peor que detectar un doble pago cada seis meses en la conciliación nocturna y emitir el reembolso.

Tras revisar los invariantes internos, contrastamos con los proveedores externos. Click ofrece en su Merchant API un endpoint puntual para consultar el estado según nuestro número de pedido:

GET /v2/merchant/payment/status_by_mti/:service_id/:merchant_trans_id/YYYY-MM-DD

Para usarlo se envía la cabecera Auth: merchant_user_id:digest:timestamp, donde digest = sha1(timestamp + secret_key). Aquí hay otra trampa con las unidades: a diferencia de los 13 dígitos en milisegundos de Payme, la cabecera Auth de Click exige tiempo Unix en segundos. Esta consulta resulta muy práctica para verificar uno por uno los pedidos sospechosos de las consultas 1, 2 y 4.

Con Payme el flujo va en sentido contrario: es Payme quien llama a GetStatement para conciliarse con nosotros, así que nuestra respuesta debe coincidir con provider_txn, mientras que de nuestro lado comparamos la base de datos contra el registro diario de operaciones y los abonos bancarios. Así luce el esqueleto de la tarea nocturna:

async function nightlyReconciliation(day: Date) {
  const findings: Finding[] = [
    ...(await db.many(Q_PAID_TXN_UNPAID_ORDER))
      .map((r) => f('paid_not_fulfilled', r)),
    ...(await db.many(Q_PAID_ORDER_NO_TXN))
      .map((r) => f('order_without_txn', r)),
    ...(await db.many(Q_DOUBLE_PAYMENT))
      .map((r) => f('double_payment', r)),
    ...(await db.many(Q_STUCK_PENDING))
      .map((r) => f('stuck_pending', r)),
  ];

  // Para Click consultamos el estado vivo del pedido en Merchant API
  for (const x of findings.filter((i) => i.provider === 'click')) {
    x.external = await click.statusByMti(x.merchant_trans_id, day);
  }

  const registry = await loadProviderRegistry(day);
  // Archivamos el registro crudo antes de procesarlo
  await archiveRaw(day, registry);
  // Comparamos por ID del proveedor, nunca por monto y hora
  findings.push(...diffById(await db.txnsForDay(day), registry));

  // Abrimos un ticket con responsable por cada diferencia
  for (const x of findings) {
    await tickets.open(x);
  }
}

Los dos últimos detalles de este código ahorran horas de investigación en la práctica. Primero, concilia las operaciones contra el registro usando estrictamente el ID externo del proveedor (params.id o click_trans_id), nunca el par «monto + hora»: dos compras de 15,000 sums en el mismo minuto ocurren todos los días en cualquier tienda. Segundo, archiva el archivo original del registro tal cual llega antes de aplicar parsers o filtros: cuando contabilidad o soporte pregunten una semana después de dónde salió una diferencia, tendrás el original del proveedor y no una copia alterada.

Lista de verificación antes de salir a producción

Antes de habilitar pagos con dinero real, repasa cada punto de esta lista en tu entorno de pruebas.

Checklist antes de lanzar Payme y Click a producción

  • PostgreSQL tiene la tabla provider_txn con unique (provider, external_id) y el índice parcial one_pending_per_order; la defensa contra concurrencia vive en la BD, no en un SELECT previo al INSERT.
  • Los campos create_time, perform_time y cancel_time se escriben una sola vez y se devuelven intactos en los reintentos; provider_time se guarda aparte para GetStatement de Payme.
  • El manejador de Payme siempre responde HTTP 200 (errores en JSON), valida el timeout de 12 horas (43,200,000 ms) en CreateTransaction y PerformTransaction, y compara la clave de Basic Auth con crypto.timingSafeEqual.
  • El cambio provider_txn.state = 2, el paso del pedido a paid y la escritura de la tarea en outbox ocurren en la misma transacción de BD; un worker separado envía SMS, recibos y webhooks.
  • El error -31007 en Payme (CancelTransaction) depende de la entrega real del producto o servicio, no del estado «pagado».
  • En Click, la firma MD5 se verifica con las cadenas crudas del formulario antes de parsear tipos, y el monto se convierte a tiyins enteros usando BigInt sin float.
  • Ante un Complete repetido en Click se responde -4, ante un error < 0 entrante se cancela la transacción con -9, y si falta stock tras el cobro se responde 0 y se llama enseguida a DELETE /v2/merchant/payment/reversal/....
  • El sandbox test.paycom.uz pasó al completo y el job nightlyReconciliation con los cuatro invariantes SQL, archivo del registro crudo y apertura de tickets corre a diario según lo programado.

Si toda esta arquitectura pasa en verde en el sandbox de Payme, soporta los reintentos de Complete en Click y entrega un reporte limpio en la conciliación nocturna, tu backend de pagos está listo para recibir tráfico real, incluso si al comprador se le cae el internet móvil medio segundo justo al momento del cobro.

Quiero un análisis detalladoLos votos ayudan a elegir qué analizar a fondo. Este material tiene 0 votos.
Fuentes · 7