Conciliación de pagos para comerciantes cripto
Cómo conciliar los pagos cripto con tus pedidos y tu saldo: qué registrar, las comprobaciones diarias, cómo encontrar webhooks perdidos y pagos cortos, y cómo contabilizar comisiones y retiros.
La conciliación responde a una pregunta: ¿cada pedido que consideras pagado corresponde a un pago que realmente llegó, y cada pago que llegó corresponde a un pedido? Con cripto no es difícil, porque cada pago lleva tu propio número de pedido, pero solo funciona si registras lo correcto y compruebas con un calendario. Esta guía muestra qué anotar, qué comprobaciones ejecutar y cómo explicar las diferencias que encuentres.
Qué estás conciliando
Tres conjuntos de registros deben coincidir:
- Tus pedidos: lo que vendiste, en dólares estadounidenses, y cuáles consideras pagados.
- Tu registro de webhooks: las notificaciones que Qvard te envió y lo que hiciste con cada una.
- El panel de Qvard: los pagos y el saldo tal como los ve la pasarela.
La API pública no tiene ninguna ruta para listar o leer pagos, así que no puedes traer el lado de la pasarela a un script. Concilias tus pedidos y tu propio registro de webhooks entre sí, y luego comparas los totales con lo que muestra el panel.
Qué registrar para que la conciliación sea posible
La conciliación es fácil si los datos existen y dolorosa si no.
- Usa tu propio número de pedido como id del pago. Va a Qvard cuando creas el pago y vuelve en el webhook, así que es la clave que une todo.
- Registra cada webhook, con el
id, elstatus, la hora y tu decisión: aplicado, repetición, pedido desconocido o clave rechazada. Nunca registres tu clave secreta. - Guarda el valor del pedido en dólares en el momento del pedido, y la hora en que lo marcaste como pagado.
- Conserva el id del pago de Qvard de la respuesta si lo quieres para soporte.
Marca un pedido como pagado solo desde el webhook, que Qvard envía cuando un pago está completado, y haz el manejador idempotente. Detalles en cómo proteger los webhooks de pagos cripto.
Las comprobaciones diarias
Tres consultas pequeñas detectan casi todo; el ejemplo las muestra.
- Pedidos sin pagar pasada la ventana del tipo de cambio. El tipo de la página de pago queda fijado durante una hora. Un pedido que sigue esperando después, o fue abandonado o perdió su notificación. Mira esos pagos en el panel.
- Pedidos pagados sin un evento «completed». Si marcaste un pedido como pagado pero tu registro no tiene una notificación de finalización, algo se saltó el webhook, lo cual nunca debería ocurrir. Investiga antes de enviar más.
- El total diario. Compara el número y la suma en dólares de los pedidos que marcaste como pagados con los pagos que el panel muestra para el mismo día.
Cuando el panel muestra un pago como completado y tu pedido sigue sin pagar, la notificación se perdió: reenvíala desde el panel y deja que el manejador idempotente la aplique.
-- Your side: every webhook you receive is logged with your decision.
CREATE TABLE qvard_events (
id BIGSERIAL PRIMARY KEY,
order_id TEXT NOT NULL, -- the id you sent to Qvard
status TEXT NOT NULL, -- completed, ...
decision TEXT NOT NULL, -- applied | repeat | unknown_order | rejected_key
received_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
-- 1. Orders still unpaid after the rate window: candidates for a missed notification.
SELECT id, amount_usd, created_at
FROM orders
WHERE state = 'awaiting_payment'
AND created_at < now() - interval '1 hour'
ORDER BY created_at;
-- 2. Orders you consider paid, with no logged "completed" event: investigate before fulfilling more.
SELECT o.id, o.amount_usd, o.paid_at
FROM orders o
LEFT JOIN qvard_events e ON e.order_id = o.id AND e.status = 'completed'
WHERE o.state = 'paid' AND e.id IS NULL;
-- 3. The daily total to compare with the Qvard cabinet.
SELECT date_trunc('day', paid_at) AS day, count(*) AS orders, sum(amount_usd) AS usd
FROM orders
WHERE state = 'paid'
GROUP BY 1
ORDER BY 1 DESC;Explicar las diferencias que encuentres
La mayoría de los desajustes tienen una lista corta de causas.
- Un pago corto. Llegó menos del importe completo, así que el pago tiene el estado
partialy no se envió webhook de finalización. El pedido no está pagado; pide la diferencia o reembolsa. Consulta cómo gestionar los pagos incompletos en USDT. - Una notificación perdida. Tu servidor estuvo caído más que la ventana de reintentos (cinco intentos en unos seis minutos), o respondió con algo distinto de exactamente HTTP 200. Consulta estrategia de reintentos de webhooks en sistemas de pago.
- Un duplicado. El mismo evento llegó dos veces. Un manejador correcto lo registra como repetición y no cambia nada.
- Un pedido desconocido. Una notificación con un id que no tienes. Comprueba erratas en el id que envías y pagos creados desde otro sistema con la misma clave.
- Un reembolso. Un reembolso es una transferencia que envías tú; regístralo contra el pedido original para que los totales sigan explicándose solos.
Comisiones, saldos y retiros
El valor en dólares de los pedidos no es lo mismo que el dinero en tu billetera.
- Comisión. No hay cuota de suscripción; la comisión es individual para tu proyecto y, según la página de precios, parte del 1% y puede bajar hasta el 0,1%. Regístrala como una línea propia.
- Comisiones de red. El cliente paga la comisión de red de la transferencia. Tú pagas solo la comisión de red cuando retiras a tu propia billetera.
- Retiros. Registra cada uno con su fecha, red y comisión. El retiro a una cuenta bancaria en moneda fiat no está disponible; si conviertes a efectivo, ese paso ocurre fuera de Qvard y tiene sus propios registros.
- Moneda y red. Los pagos en distintas redes se acumulan por separado. Comprueba los saldos por activo y red, como en comisiones de red en las operaciones de pagos cripto.
Mantén también informado a tu contable: el tratamiento fiscal y contable de los cobros en cripto depende de tu país.
FAQ
¿Puedo obtener mis pagos por la API para conciliar?
La API pública no tiene ninguna ruta para listar o leer pagos. Concilia tus pedidos y tu propio registro de webhooks, y compara los totales con los pagos y el saldo del panel de Qvard.
¿Cómo asocio un pago a un pedido?
Por el id. Envías tu propio número de pedido al crear el pago, y el mismo id vuelve en el webhook.
¿Y si el panel muestra un pago completado y mi pedido está sin pagar?
La notificación se perdió. Reenvíala desde el panel; un manejador idempotente la aplica con seguridad.
¿Con qué frecuencia debo conciliar?
A diario es un buen valor por defecto, más una alerta cuando una racha de solicitudes de webhook recibe un error.