Ir al contenido

Archivo CSV

Al terminar esta página sabrás qué columnas trae el archivo de conciliación y cómo cruzarlo contra tus propios registros.

GET /v1/reconciliation/payments.csv
Authorization: Bearer <tu API key>

Límite de tasa: 10 solicitudes por minuto por credencial. Devuelve text/csv; charset=utf-8 con Content-Disposition: attachment; filename="payments.csv". Incluye todos los pagos de tu comercio, sin filtro de fecha ni paginación, así que descargas el archivo completo cada vez.

Una fila por pago, ordenadas por created_at ascendente. Separador ,, fin de línea \r\n, codificación UTF-8.

Tres detalles del formato que conviene tener en cuenta al parsearlo:

  • Los valores van entre comillas dobles, y unas comillas dentro del valor se duplican (""), como manda el RFC 4180.
  • Un null se escribe como celda vacía y sin comillas, para distinguirlo de una cadena vacía.
  • Un valor que empiece con =, +, - o @ lleva un apóstrofo delante ('=A1). Es la defensa estándar contra la inyección de fórmulas al abrir el archivo en una hoja de cálculo. Si procesas el CSV con código, quítalo antes de comparar.
Columna Descripción
payment_id Identificador del pago.
session_id Sesión de checkout a la que pertenece. Vacía en un pago sin obligación, ver Pagos sin obligación. También puede venir vacía en una transferencia que sí salda una obligación, si el pagador había cancelado su sesión: ahí external_reference viene con valor.
external_reference Tu referencia de la obligación. Vacía en un pago sin obligación.
payment_version La misma version que ves en la API y en los webhooks.
currency Siempre MXN.
principal_amount_minor Monto de la obligación, en centavos.
payer_fee_minor, payer_fee_tax_minor Comisión e IVA a cargo del pagador. 0 si los absorbe tu comercio.
provider_fee_minor, provider_fee_tax_minor Comisión e IVA que absorbe tu comercio y se descuentan del depósito. 0 si los paga el pagador.
charged_amount_minor Total cobrado. Vacía si el pago sigue pending; 0 si falló definitivamente.
provider_net_amount_minor Monto neto para tu comercio. Vacía si sigue pending; 0 si falló definitivamente.
refunded_amount_minor Total devuelto y confirmado hasta el momento de la descarga.
payment_status Mismo valor que payment.status en la API, ver Estados y glosario.
created_at Cuándo se creó el intento de cobro.
paid_at Cuándo se confirmó. Vacía si nunca se confirmó.
updated_at Última actualización de este pago, se mueve, por ejemplo, cuando se confirma una devolución.
category Qué pagó el pagador: maintenance_fee, rent o rent_guarantee_insurance, ver Categoría del cobro. Va después de updated_at, antes de fee_bearer, para no correr las columnas anteriores.
fee_bearer Quién pagó la comisión: payer o provider, ver Importes y comisiones. Va al final, después de category.

Una celda vacía en charged_amount_minor o provider_net_amount_minor significa “todavía no hay un resultado definitivo”, no “cero”. No la conviertas en 0 al procesar el archivo.

payment_id,session_id,external_reference,payment_version,currency,principal_amount_minor,payer_fee_minor,payer_fee_tax_minor,provider_fee_minor,provider_fee_tax_minor,charged_amount_minor,provider_net_amount_minor,refunded_amount_minor,payment_status,created_at,paid_at,updated_at,category,fee_bearer
"pay_3ac4efd9f068","cs_164596add1a3","CUOTA-2026-09-000123","2","MXN","125000","3750","600","0","0","129350","125000","0","succeeded","2026-09-14T23:17:17.894Z","2026-09-14T23:17:17.894Z","2026-09-14T23:17:17.894Z","maintenance_fee","payer"
"pay_4ae7fad5b7da","cs_1e1a4def4f6f","CUOTA-2026-10-000124","3","MXN","80000","2400","384","0","0","82784","80000","82784","refunded","2026-09-14T23:17:43.796Z","2026-09-14T23:17:43.796Z","2026-09-14T23:19:48.031Z","maintenance_fee","payer"
"pay_9c1d0b7e2a54","cs_2b7e93c0d1f8","CUOTA-2026-10-000125","2","MXN","125000","0","0","3750","600","125000","120650","0","succeeded","2026-10-22T15:04:11.207Z","2026-10-22T15:04:11.207Z","2026-10-22T15:04:11.207Z","maintenance_fee","provider"

La segunda fila es un pago que fue cobrado y luego cancelado por el pagador: payment_status pasó a refunded, refunded_amount_minor quedó igual al total cobrado, y payment_version avanzó a 3 (de 1 al reservarse, 2 al confirmarse el cobro, 3 al confirmarse la cancelación). La tercera es un cobro con la comisión absorbida por tu comercio: el pagador pagó 125000 y el neto a depositar es 120650.

  1. Indexa tus obligaciones por external_reference; es el único campo del archivo que coincide con lo que tú enviaste al crear la sesión. Una fila con external_reference vacía es dinero recibido que no salda ninguna obligación tuya: no la apliques a ninguna.
  2. Actualiza por payment_id y payment_version, no sumes cada fila como un movimiento nuevo: si descargas el archivo más de una vez, un mismo pago puede aparecer con distinto payment_status en cada descarga.
  3. Usa el webhook (ver Webhooks: eventos y firma) como la señal en tiempo real y este archivo para conciliar el corte del día. Ambos describen el mismo pago; si discrepan, payment_version y updated_at indican cuál es más reciente.

El archivo no tiene corte diario ni metadatos de período; refleja el estado de todos tus pagos en el momento de la descarga. Para conciliar por día, descárgalo a la misma hora cada día y conserva cada copia con su fecha.