Consulta de transacciones y conciliación de depósitos (GraphQL)

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 POST con 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 secretKeyEn NetPay Manager → Llaves. Es la misma que usas para cobrar
Tu storeIdEs el identificador de cada comercio. Una terminal física = un storeId. Tu ecommerce = un storeId
🚧

Un comercio con varias terminales tiene varios storeId

Si tienes 5 terminales físicas y una tienda en línea, tienes 6 storeId. Los depósitos se hacen por storeId, así que la conciliación también se hace por storeId.

El endpoint

AmbienteURL
Sandboxhttps://gateway.netpay-api.com/reports-sandbox/v1/graphql
Producciónhttps://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 llama X-Netpay-Apikey, no Authorization

Es el error más común al integrar. El API de cobro usa Authorization; este servicio usa X-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 variables

Si usas variables de GraphQL ($min, $max) dentro de rangeDateFilter, 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/DD para no abrir una inyección.

📘

Un HTTP 200 no siempre es éxito

Si algo está mal en la consulta, el servidor puede responder 200 con un campo errors en el cuerpo. Revisa siempre si existe errors antes de leer data.


Paso 2 — Entender la respuesta

El estado de la transacción

statusQué significa
AprobadaSe cobró correctamente. Esta se te va a depositar
DevoluciónEs el registro de una devolución aplicada. Se resta del depósito
RechazadaEl emisor rechazó el cobro. No hay dinero
ReversadaSe revirtió. No hay dinero
CanceladaSe canceló antes de liquidar. No hay dinero
❗

Devolución lleva acento

Al 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, usa capt_amount cuando exista.
🚧

Súmalos con tipos decimales, no con float

En cualquier lenguaje, sumar muchos float produce errores de centavos. Usa Decimal en Python, BigDecimal en Java, decimal en 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

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/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.

CampoPara qué sirve
payment_date_npFecha y hora del depósito. Es sobre este campo que vas a conciliar
conc_statusC cuando la transacción ya está conciliada por NetPay
report_statusPagada cuando ya se depositó; No Exitosa cuando no hubo cobro
🚧

No todas las marcas se depositan en el mismo plazo

En 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_np vacío

Significa 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.

FiltroQué hace
rangeDateFilterFiltra por fecha de venta
paymentDateFilterFiltra 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 brutos

NetPay 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

  1. Consulta el rango de fechas con rangeDateFilter (o directamente por paymentDateFilter si concilias día por día).
  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 lo demás por la fecha de payment_date_np (solo la parte de fecha) 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.

Cómo interpretar el resultado

SituaciónQué significaQué hacer
Esperado = Depositado✅ CuadraNada
Esperado > DepositadoFalta dineroRevisa si hay devoluciones o contracargos aplicados a ese depósito
Esperado < DepositadoSobra dineroRevisa si el depósito incluye ventas de otro periodo
Hay transacciones, no hay depósitoAún no se liquidaVuelve a consultar al día siguiente
Hay depósito, no hay transaccionesRevisar con NetPayPuede 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 concentradora

Una sola secretKey puede consultar todos los comercios de la misma empresa. Si omites storeId, 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 arreglo

Cuando 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 los Devolució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

ArgumentoTipoDescripción
rangeDateFilterobjetoRango por fecha de venta: { min: "YYYY/MM/DD", max: "YYYY/MM/DD" }
paymentDateFilterobjetoRango por fecha de depósito, mismo formato
storeIdlista de enterosUno o varios comercios: [1267778, 1271824]
companyIdenteroEmpresa
transactionIdtextoUna transacción específica
transactionTokenIdtextoEl token UUID del cobro
orderIdtextoSolo en la consulta transaction
externalReferencetextoTu referencia externa
merchantRefCodetextoTu código de referencia
paymentMethodlista de textoMétodo de pago
promotionlista de textoPromoción, por ejemplo meses sin intereses
filterPreauthlista de booleanosFiltra preautorizaciones
productlista de enterosProducto. [7] es e-commerce
🚧

Cuidado con product y filterPreauth

Estos 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 estado

No existe un argumento para pedir solo las Aprobada. Trae el conjunto completo y filtra por status de tu lado.

Campos útiles de la respuesta

CampoDescripción
transaction_idIdentificador de la transacción
transaction_token_idToken UUID del cobro
order_idTu número de orden (20 dígitos, trátalo como texto)
store_id, store_nameComercio
company_nameEmpresa
transaction_dateFecha de la venta, DD/MM/YYYY HH:mm
payment_date_npFecha del depósito
statusEstado de la transacción
report_statusPagada / No Exitosa
conc_statusC cuando ya está conciliada
auth_amountMonto autorizado, en pesos
capt_amountMonto capturado, en pesos
auth_codeCódigo de autorización del emisor
host_ref_numReferencia del adquirente
terminal_idTerminal física
brand, card_typeMarca y tipo de tarjeta
span_route_numÚltimos dígitos de la tarjeta
promotion, promo_termPromoción y plazo
void_dateFecha de cancelación
response_msgMensaje 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

RangoResultados aproximadosTiempo
1 díacientos~1 s
1 mesmiles2 a 6 s
5 mesesdecenas de miles8 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íntomaCausaSolución
Error de autenticaciónHeader equivocadoUsa X-Netpay-Apikey, no Authorization
HTTP 500 en consultas con fechasUsaste variables de GraphQL en el filtro de fechasEscribe las fechas dentro del texto de la consulta
HTTP 200 pero con errorsError en la consultaRevisa errors; suele indicar el campo o argumento inválido
La respuesta viene vacíaFiltros product o filterPreauth, o no hay movimientoQuita esos filtros y verifica la fecha
Montos multiplicados o divididos por 100Asumiste centavosLos montos vienen en pesos con decimales
El número de orden pierde dígitosSe trató como númeroManéjalo como texto en todo el flujo
Una venta no aparece en ningún depósitopayment_date_np vacíoTodavía no se liquida; consulta después

Checklist de integración

  • Header X-Netpay-Apikey configurado.
  • URL correcta por ambiente (sandbox / producción).
  • Fechas escritas dentro del texto de la consulta, con formato validado.
  • Se revisa errors aunque el HTTP sea 200.
  • Sin filtros product ni filterPreauth en la conciliación.
  • Montos manejados como decimales, en pesos.
  • order_id y transaction_id tratados como texto.
  • Comparación de status normalizando acentos.
  • Agrupación por payment_date_np + store_id.
  • Aprobadas sin payment_date_np tratadas como pendientes, no como diferencias.
  • Consultas troceadas por mes en rangos amplios.
  • La ventana de consulta llega hasta hoy.