Guía paso a paso para consultar tus transacciones por API y conciliar los depósitos que NetPay hace a tu cuenta.
Esta guía es para comercios que necesitan cuadrar los depósitos que reciben de NetPay contra sus ventas, de forma automática y sin depender de reportes manuales.
Al terminar vas a poder:
- Consultar tus transacciones por API, filtradas por fecha, comercio u orden.
- Saber en qué fecha se depositó cada venta.
- Calcular cuánto debió depositarte NetPay cada día, por cada comercio.
- Comparar ese cálculo contra lo que llegó a tu banco.
¿Qué es GraphQL y por qué debería importarme?Es una forma de consultar datos donde tú pides exactamente los campos que necesitas, en lugar de recibir una respuesta gigante con todo. Se usa igual que cualquier API: mandas un
POSTcon un JSON y recibes un JSON.No necesitas saber GraphQL para seguir esta guía. Copia los ejemplos, cambia las fechas y el ID de tu comercio, y listo.
Antes de empezar
Necesitas dos cosas:
| Qué | Dónde lo obtienes |
|---|---|
Tu secretKey | En NetPay Manager → Llaves. Es la misma que usas para cobrar |
Tu storeId | Es el identificador de cada comercio. Una terminal física = un storeId. Tu ecommerce = un storeId |
Un comercio con varias terminales tiene variosstoreIdSi tienes 5 terminales físicas y una tienda en línea, tienes 6
storeId. Los depósitos se hacen porstoreId, así que la conciliación también se hace porstoreId.
El endpoint
| Ambiente | URL |
|---|---|
| Sandbox | https://gateway.netpay-api.com/reports-sandbox/v1/graphql |
| Producción | https://gateway.netpay-api.com/reports/v1/graphql |
Siempre es un POST, siempre a la misma URL. Lo que cambia es el contenido.
Los headers
X-Netpay-Apikey: {tu secretKey}
Content-Type: application/json
El header se llamaX-Netpay-Apikey, noAuthorizationEs el error más común al integrar. El API de cobro usa
Authorization; este servicio usaX-Netpay-Apikey. Si mandas el header equivocado, recibes un error de autenticación aunque la llave sea correcta.
Paso 1 — Tu primera consulta
Empecemos con lo más simple: traer las transacciones 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: [1267778] rangeDateFilter: { min: \"2026/09/09\", max: \"2026/09/09\" } ) { transaction_id order_id transaction_date auth_amount status } }"}'Respuesta:
{
"data": {
"allTransactions": [
{
"transaction_id": "90296F9F-4915-0A46-F335-5E047CBB4CED",
"order_id": "17889789767211267778",
"transaction_date": "09/09/2026 12:36",
"auth_amount": 14,
"status": "Aprobada"
}
]
}
}Cómo se arma el cuerpo
Todo el cuerpo es un JSON con una sola llave, query, cuyo valor es texto:
{ "query": "{ allTransactions( FILTROS ) { CAMPOS_QUE_QUIERES } }" }- FILTROS — qué transacciones quieres (fechas, comercio, orden).
- CAMPOS_QUE_QUIERES — qué datos de cada transacción quieres de vuelta, separados por espacios.
Si quieres un campo más, lo agregas a la lista. Si no lo necesitas, lo quitas y la respuesta pesa menos.
Las fechas van escritas directamente en el texto, no como variablesSi usas variables de GraphQL (
$min,$max) dentro derangeDateFilter, el servidor responde HTTP 500. Escribe las fechas dentro del texto de la consulta.Si las armas concatenando en tu código, valida primero el formato
YYYY/MM/DDpara no abrir una inyección.
Un HTTP 200 no siempre es éxitoSi algo está mal en la consulta, el servidor puede responder 200 con un campo
errorsen el cuerpo. Revisa siempre si existeerrorsantes de leerdata.
Paso 2 — Entender la respuesta
El estado de la transacción
status | Qué significa |
|---|---|
Aprobada | Se cobró correctamente. Esta se te va a depositar |
Devolución | Es el registro de una devolución aplicada. Se resta del depósito |
Rechazada | El emisor rechazó el cobro. No hay dinero |
Reversada | Se revirtió. No hay dinero |
Cancelada | Se canceló antes de liquidar. No hay dinero |
Devoluciónlleva acentoAl comparar en tu código, normaliza el texto (sin acentos y en minúsculas) para no depender de la codificación de tu cliente HTTP.
Los montos
auth_amount y capt_amount vienen en pesos con decimales (1678.14), no en centavos. No los multipliques ni los dividas por 100.
auth_amount— el monto autorizado.capt_amount— el monto realmente capturado. En una venta normal son iguales; en una preautorización pueden diferir. Para conciliar, usacapt_amountcuando exista.
Súmalos con tipos decimales, no confloatEn cualquier lenguaje, sumar muchos
floatproduce errores de centavos. UsaDecimalen Python,BigDecimalen Java,decimalen C#.
El ID de la orden
order_id es un número de 20 dígitos. Excede la precisión de un double, así que trátalo siempre como texto. Si lo exportas a Excel, dale formato de celda como texto o vas a perder los últimos dígitos.
Paso 3 — La fecha del depósito
Este es el campo clave de toda la guía:
payment_date_np = la fecha en que NetPay te depositó esa venta
payment_date_np = la fecha en que NetPay te depositó esa ventacurl --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: [1267778] rangeDateFilter: { min: \"2026/09/01\", max: \"2026/09/18\" } ) { transaction_id order_id transaction_date payment_date_np conc_status report_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",
"conc_status": "C",
"report_status": "Pagada",
"status": "Aprobada",
"capt_amount": 14,
"brand": "Visa"
}Se vendió el 09/09 y se depositó el 10/09.
| Campo | Para qué sirve |
|---|---|
payment_date_np | Fecha y hora del depósito. Es sobre este campo que vas a conciliar |
conc_status | C cuando la transacción ya está conciliada por NetPay |
report_status | Pagada cuando ya se depositó; No Exitosa cuando no hubo cobro |
No todas las marcas se depositan en el mismo plazoEn una misma venta del mismo día, una Visa puede depositarse al día siguiente y una Amex varios días después. Por eso no puedes asumir que "el depósito de hoy son las ventas de ayer".
Usa siempre
payment_date_np, que te dice el dato exacto, en lugar de calcularlo con una regla de días.
payment_date_npvacíoSignifica que esa venta todavía no se deposita. No es un error ni una diferencia: es un pendiente. Vuelve a consultarla más adelante.
Paso 4 — Filtrar por fecha de depósito
Ya que sabes que payment_date_np es la fecha del depósito, puedes pedir directamente "dame todo lo que entró en el depósito del día X" usando paymentDateFilter:
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: [1267778] paymentDateFilter: { min: \"2026/09/10\", max: \"2026/09/10\" } ) { transaction_id order_id transaction_date payment_date_np capt_amount status } }"}'Esto devuelve exactamente las transacciones depositadas el 10/09, sin importar cuándo se vendieron.
Esta es la consulta central de la conciliación. El depósito que recibiste ese día debe ser igual a la suma de estos montos.
| Filtro | Qué hace |
|---|---|
rangeDateFilter | Filtra por fecha de venta |
paymentDateFilter | Filtra por fecha de depósito |
Ambos usan el mismo formato: { min: "YYYY/MM/DD", max: "YYYY/MM/DD" }, inclusivo en ambos extremos.
Paso 5 — Conciliar
La fórmula
Para cada combinación de fecha de depósito y storeId:
Depósito esperado = Σ capt_amount de las Aprobadas
− Σ capt_amount de las Devolución
Ese resultado debe ser igual al monto que llegó a tu cuenta.
Los depósitos son brutosNetPay deposita el monto completo de las ventas. Las comisiones se cobran por separado, así que el cuadre debe ser exacto, peso a peso. No apliques tolerancias por comisiones.
El procedimiento
- Consulta el rango de fechas con
rangeDateFilter(o directamente porpaymentDateFiltersi concilias día por día). - Descarta lo que no se liquida:
Rechazada,Reversada,Cancelada. - Aparta las
Aprobadasinpayment_date_np: son pendientes de depósito, no diferencias. - Agrupa lo demás por la fecha de
payment_date_np(solo la parte de fecha) y porstore_id. - Suma las aprobadas y resta las devoluciones.
- Compara contra el depósito real de ese día para ese
storeId.
Cómo interpretar el resultado
| Situación | Qué significa | Qué hacer |
|---|---|---|
| Esperado = Depositado | ✅ Cuadra | Nada |
| Esperado > Depositado | Falta dinero | Revisa si hay devoluciones o contracargos aplicados a ese depósito |
| Esperado < Depositado | Sobra dinero | Revisa si el depósito incluye ventas de otro periodo |
| Hay transacciones, no hay depósito | Aún no se liquida | Vuelve a consultar al día siguiente |
| Hay depósito, no hay transacciones | Revisar con NetPay | Puede ser un ajuste o un movimiento de otro tipo |
Ejemplo completo
Supón que recibiste un depósito de $1,234.56 el 10/09/2026 para el store 1267778.
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: [1267778] paymentDateFilter: { min: \"2026/09/10\", max: \"2026/09/10\" } ) { transaction_id order_id capt_amount status } }"}'Sumas los capt_amount de las Aprobada, restas los de las Devolución, y ese total debe dar $1,234.56.
Paso 6 — Varios comercios a la vez
storeId acepta una lista, así que puedes traer todos tus comercios en una sola consulta:
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: [1267778, 1271824, 1271686] paymentDateFilter: { min: \"2026/09/10\", max: \"2026/09/10\" } ) { transaction_id store_id store_name capt_amount status payment_date_np } }"}'Trae store_id entre los campos para poder separar los resultados por comercio.
Si administras una cuenta concentradoraUna sola
secretKeypuede consultar todos los comercios de la misma empresa. Si omitesstoreId, la consulta devuelve todos los comercios asociados a la llave. Tenlo presente al diseñar los permisos de tus propios usuarios.
Paso 7 — Buscar una venta específica
Por número de orden (la más rápida)
curl --location 'https://gateway.netpay-api.com/reports/v1/graphql' \
--header 'X-Netpay-Apikey: TU_SECRET_KEY' \
--header 'Content-Type: application/json' \
--data '{"query":"{ transaction(orderId: \"17889789767211267778\") { transaction_id order_id transaction_date payment_date_np capt_amount status } }"}'Devuelve el cobro y todas sus devoluciones, porque comparten order_id. Es la vía natural si tu sistema identifica las operaciones por número de orden.
No tomes el primer registro del arregloCuando una venta tiene devoluciones, la respuesta trae varios registros y el orden no está garantizado. Recórrelos todos: el cobro es el que tiene
status: "Aprobada", y lo ya devuelto es la suma de losDevolución.
Por token de la transacción
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( transactionTokenId: \"5d7291dc-a60b-4e72-937b-6dbaa8866c10\" ) { transaction_id order_id capt_amount status payment_date_np } }"}'Referencia
Filtros de allTransactions
allTransactions| Argumento | Tipo | Descripción |
|---|---|---|
rangeDateFilter | objeto | Rango por fecha de venta: { min: "YYYY/MM/DD", max: "YYYY/MM/DD" } |
paymentDateFilter | objeto | Rango por fecha de depósito, mismo formato |
storeId | lista de enteros | Uno o varios comercios: [1267778, 1271824] |
companyId | entero | Empresa |
transactionId | texto | Una transacción específica |
transactionTokenId | texto | El token UUID del cobro |
orderId | texto | Solo en la consulta transaction |
externalReference | texto | Tu referencia externa |
merchantRefCode | texto | Tu código de referencia |
paymentMethod | lista de texto | Método de pago |
promotion | lista de texto | Promoción, por ejemplo meses sin intereses |
filterPreauth | lista de booleanos | Filtra preautorizaciones |
product | lista de enteros | Producto. [7] es e-commerce |
Cuidado conproductyfilterPreauthEstos filtros excluyen registros. Si usas
product: [7]no vas a ver las ventas de tus terminales físicas. Para conciliar, no los uses: trae todo y filtra en tu sistema.
No hay filtro por estadoNo existe un argumento para pedir solo las
Aprobada. Trae el conjunto completo y filtra porstatusde tu lado.
Campos útiles de la respuesta
| Campo | Descripción |
|---|---|
transaction_id | Identificador de la transacción |
transaction_token_id | Token UUID del cobro |
order_id | Tu número de orden (20 dígitos, trátalo como texto) |
store_id, store_name | Comercio |
company_name | Empresa |
transaction_date | Fecha de la venta, DD/MM/YYYY HH:mm |
payment_date_np | Fecha del depósito |
status | Estado de la transacción |
report_status | Pagada / No Exitosa |
conc_status | C cuando ya está conciliada |
auth_amount | Monto autorizado, en pesos |
capt_amount | Monto capturado, en pesos |
auth_code | Código de autorización del emisor |
host_ref_num | Referencia del adquirente |
terminal_id | Terminal física |
brand, card_type | Marca y tipo de tarjeta |
span_route_num | Últimos dígitos de la tarjeta |
promotion, promo_term | Promoción y plazo |
void_date | Fecha de cancelación |
response_msg | Mensaje del emisor |
Buenas prácticas
Cuándo correr la conciliación
Ejecútala a partir de la tarde del día siguiente. Una devolución aplicada no se refleja de inmediato en las consultas.
Cuánto rango pedir
| Rango | Resultados aproximados | Tiempo |
|---|---|---|
| 1 día | cientos | ~1 s |
| 1 mes | miles | 2 a 6 s |
| 5 meses | decenas de miles | 8 a 15 s |
No hay paginación: la consulta devuelve todo el conjunto. Para rangos amplios, trocea por mes y une los resultados: cada respuesta pesa menos y baja el riesgo de timeout.
La ventana debe llegar hasta hoy
Una devolución se registra con la fecha en que se aplicó, no con la de la venta original, y puede ocurrir meses después. Si consultas solo el mes de la venta, no vas a ver sus devoluciones posteriores.
Contracargos
Un contracargo puede afectar tu depósito. Los campos dispute_state, dispute_case_number y disputed_amount están disponibles en la consulta; si una diferencia no se explica por ventas ni devoluciones, revísalos.
Errores comunes
| Síntoma | Causa | Solución |
|---|---|---|
| Error de autenticación | Header equivocado | Usa X-Netpay-Apikey, no Authorization |
| HTTP 500 en consultas con fechas | Usaste variables de GraphQL en el filtro de fechas | Escribe las fechas dentro del texto de la consulta |
HTTP 200 pero con errors | Error en la consulta | Revisa errors; suele indicar el campo o argumento inválido |
| La respuesta viene vacía | Filtros product o filterPreauth, o no hay movimiento | Quita esos filtros y verifica la fecha |
| Montos multiplicados o divididos por 100 | Asumiste centavos | Los montos vienen en pesos con decimales |
| El número de orden pierde dígitos | Se trató como número | Manéjalo como texto en todo el flujo |
| Una venta no aparece en ningún depósito | payment_date_np vacío | Todavía no se liquida; consulta después |
Checklist de integración
- Header
X-Netpay-Apikeyconfigurado. - URL correcta por ambiente (sandbox / producción).
- Fechas escritas dentro del texto de la consulta, con formato validado.
- Se revisa
errorsaunque el HTTP sea 200. - Sin filtros
productnifilterPreauthen la conciliación. - Montos manejados como decimales, en pesos.
-
order_idytransaction_idtratados como texto. - Comparación de
statusnormalizando acentos. - Agrupación por
payment_date_np+store_id. - Aprobadas sin
payment_date_nptratadas como pendientes, no como diferencias. - Consultas troceadas por mes en rangos amplios.
- La ventana de consulta llega hasta hoy.
