Conciliación de depósitos

Cuadra cada depósito que recibes de NetPay contra las ventas que lo componen, peso a peso.

NetPay te deposita por storeId, con los montos concentrados: un solo depósito reúne muchas transacciones. Esta página te muestra cómo saber exactamente qué ventas componen cada depósito y cómo cuadrarlo contra lo que llegó a tu banco.

Si es tu primera vez con este servicio, empieza por API de Consulta de Transacciones para la configuración y los conceptos.

📘

Los depósitos son brutos

NetPay deposita el monto completo de tus ventas; las comisiones se cobran por separado. Eso significa que el cuadre debe ser exacto, peso a peso. No apliques tolerancias por comisiones.


Paso 1 — El campo clave: payment_date_np

payment_date_np es la fecha en que se te depositó esa venta. Toda la conciliación gira alrededor de este campo.

curl --location 'https://gateway.netpay-api.com/reports/v1/graphql' \
--header 'X-Netpay-Apikey: TU_SECRET_KEY' \
--header 'Content-Type: application/json' \
--data '{"query":"{ allTransactions( storeId: [1234567] rangeDateFilter: { min: \"2026/09/01\", max: \"2026/09/18\" } ) { transaction_id order_id transaction_date payment_date_np report_status conc_status status capt_amount brand } }"}'
{
  "transaction_id": "90296F9F-4915-0A46-F335-5E047CBB4CED",
  "transaction_date": "09/09/2026 12:36",
  "payment_date_np": "10/09/2026 05:13",
  "report_status": "Pagada",
  "conc_status": "C",
  "status": "Aprobada",
  "capt_amount": 14,
  "brand": "Visa"
}

Se vendió el 09/09 y se depositó el 10/09.

CampoQué te dice
payment_date_npFecha y hora del depósito
report_statusPagada cuando ya se depositó
conc_statusC cuando ya está conciliada de nuestro lado
🚧

El plazo de depósito no es el mismo para todas las marcas de tarjeta

Dos ventas del mismo día pueden liquidarse en fechas distintas según la marca. Por eso no puedes calcular la fecha de depósito con una regla de días.

Si armas tu conciliación asumiendo que "el depósito de hoy son las ventas de ayer", te va a descuadrar. Usa payment_date_np, que trae el dato exacto de cada transacción.

📘

payment_date_np vacío significa que todavía no se deposita

No es un error ni un faltante: es un pendiente. Esa venta aparecerá en un depósito posterior. Vuelve a consultarla más adelante.


Paso 2 — Consultar por fecha de depósito

Con paymentDateFilter preguntas directamente qué entró en el depósito de un día:

curl --location 'https://gateway.netpay-api.com/reports/v1/graphql' \
--header 'X-Netpay-Apikey: TU_SECRET_KEY' \
--header 'Content-Type: application/json' \
--data '{"query":"{ allTransactions( storeId: [1234567] paymentDateFilter: { min: \"2026/09/10\", max: \"2026/09/10\" } ) { transaction_id order_id transaction_date payment_date_np status capt_amount } }"}'

Devuelve exactamente las transacciones depositadas el 10/09, sin importar cuándo se vendieron. Esta es la consulta central de la conciliación.

FiltroFiltra por
rangeDateFilterFecha de venta
paymentDateFilterFecha de depósito

Ambos usan el formato { min: "YYYY/MM/DD", max: "YYYY/MM/DD" } y son inclusivos en los dos extremos.

Varios puntos de cobro

Si manejas varios storeId, inclúyelos todos y agrupa el resultado por store_id. Cada uno tiene su propio depósito:

curl --location 'https://gateway.netpay-api.com/reports/v1/graphql' \
--header 'X-Netpay-Apikey: TU_SECRET_KEY' \
--header 'Content-Type: application/json' \
--data '{"query":"{ allTransactions( storeId: [1234567, 1234568, 1234569] paymentDateFilter: { min: \"2026/09/10\", max: \"2026/09/10\" } ) { transaction_id order_id store_id store_name payment_date_np status capt_amount } }"}'
📘

Cuentas concentradoras

Una sola secretKey puede consultar todos los comercios de la misma empresa. Si omites storeId, la consulta devuelve todos los asociados a la llave, lo que te permite conciliar todos tus puntos de cobro en una sola consulta.


Paso 3 — Calcular el depósito esperado

La fórmula

Para cada combinación de fecha de depósito y storeId:

Depósito esperado = Σ capt_amount de las Aprobada
                  − Σ capt_amount de las Devolución

El procedimiento

  1. Consulta el periodo con rangeDateFilter, o día por día con paymentDateFilter.
  2. Descarta lo que no se liquida: Rechazada, Reversada, Cancelada.
  3. Aparta las Aprobada sin payment_date_np: son pendientes de depósito, no diferencias.
  4. Agrupa el resto por la fecha de payment_date_np (solo la parte de fecha, sin la hora) y por store_id.
  5. Suma las aprobadas y resta las devoluciones.
  6. Compara contra el depósito real de ese día para ese storeId.
🚧

Usa tipos decimales para sumar

Sumar cientos de montos con float produce diferencias de centavos que no existen. Usa Decimal, BigDecimal o trabaja en enteros de centavos.


Paso 4 — Comparar e interpretar

SituaciónQué significaQué hacer
Esperado = Depositado✅ CuadraNada
Esperado > DepositadoFalta dineroRevisa devoluciones y contracargos de ese periodo
Esperado < DepositadoSobra dineroRevisa si el depósito incluye ventas de otro periodo
Hay transacciones, no hay depósitoAún no se liquidaVuelve a consultar más adelante
Hay depósito, no hay transaccionesPuede ser un ajusteConsulta con tu ejecutivo de cuenta
🚧

Los contracargos pueden descontarse del depósito

Si una diferencia no se explica por ventas ni devoluciones, revisa los campos dispute_state, dispute_case_number y disputed_amount de las transacciones de ese periodo.


Cuándo y cómo correr la conciliación

Ejecútala a partir de la tarde del día siguiente

Una devolución recién aplicada puede tardar en reflejarse en las consultas. Conciliar demasiado temprano produce diferencias que se resuelven solas unas horas después.

Tu ventana de consulta debe llegar hasta hoy

🚧

Las devoluciones se fechan cuando se aplican, no cuando se vendió

Una devolución puede aplicarse mucho después de la venta original, y queda registrada con su propia fecha. Si consultas solo el mes de la venta, no vas a ver sus devoluciones posteriores y vas a concluir que algo sigue pendiente cuando ya se devolvió.

No uses los filtros product ni filterPreauth

Excluyen registros. En una conciliación, un registro faltante se ve exactamente igual que un depósito incompleto.


Ejemplo completo

Recibiste un depósito de $1,234.56 el 10/09/2026 para el store 1234567. Para verificarlo:

1. Consulta lo depositado ese día:

curl --location 'https://gateway.netpay-api.com/reports/v1/graphql' \
--header 'X-Netpay-Apikey: TU_SECRET_KEY' \
--header 'Content-Type: application/json' \
--data '{"query":"{ allTransactions( storeId: [1234567] paymentDateFilter: { min: \"2026/09/10\", max: \"2026/09/10\" } ) { transaction_id order_id capt_amount status } }"}'

2. Calcula:

  Suma de capt_amount donde status = Aprobada     →  $1,300.00
− Suma de capt_amount donde status = Devolución   →     $65.44
= Depósito esperado                               →  $1,234.56

3. Compara: $1,234.56 esperado contra $1,234.56 recibido. ✅ Cuadra.


Checklist de conciliación

  • Agrupación por payment_date_np (solo fecha) + store_id.
  • Se usa capt_amount, no auth_amount.
  • Montos sumados con tipos decimales.
  • Rechazada, Reversada y Cancelada excluidas.
  • Aprobadas sin payment_date_np tratadas como pendientes, no como diferencias.
  • Sin filtros product ni filterPreauth.
  • Ventana de consulta hasta la fecha actual.
  • Proceso ejecutado a partir de la tarde del día siguiente.
  • Comparación de status normalizando acentos.

Siguientes pasos