Un solo servicio para consultar todas tus transacciones, sin importar con qué integración las cobraste.
Todas las integraciones de NetPay comparten un mismo servicio de consulta. Sin importar si cobras con Checkout Custom, Checkout Plus, Checkout Hosted o con terminales físicas, todas tus transacciones se consultan desde el mismo lugar.
Qué puedes hacer con este servicio
| Lo que necesitas | Dónde está |
|---|---|
| Buscar una venta, verificar un pago, atender una aclaración | Buscar una transacción |
| Sacar reportes de ventas por periodo o por punto de cobro | Reportes y exportaciones |
| Cuadrar los depósitos que recibes contra tus ventas | Conciliación de depósitos |
| Ver todos los filtros y campos disponibles | Referencia |
Esta página cubre los conceptos y la configuración inicial. Empieza aquí antes de ir a las demás.
No necesitas saber GraphQLGraphQL 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 como cualquier API: mandas un
POSTcon un JSON y recibes un JSON.Copia los ejemplos de esta documentación, cambia las fechas y tus identificadores, y listo.
Conceptos básicos
Cuatro conceptos que explican la mayoría de las dudas al integrar.
1. El storeId identifica cada punto de cobro
storeId identifica cada punto de cobroUn storeId no es tu negocio completo: es cada punto donde cobras.
- Cada terminal física tiene su propio
storeId. - Tu tienda en línea tiene un
storeId.
Si tienes 5 terminales y un ecommerce, manejas 6 storeId.
Esto importa porque los depósitos se hacen por storeId, y los reportes también se organizan así.
companyIdagrupa tus comerciosTodos tus
storeIdpertenecen a una empresa (companyId). Puedes consultar por empresa cuando quieres ver todo junto, o porstoreIdcuando necesitas el detalle de un punto de cobro.
2. Los tres identificadores de una transacción
Una misma venta tiene tres identificadores, y cada uno sirve para algo distinto:
| Identificador | Qué es | Cuándo lo usas |
|---|---|---|
order_id | Tu número de orden, el que tú generas | El más práctico: ya lo tienes en tu sistema |
transaction_token_id | El UUID que te devolvemos al cobrar | Si lo guardaste al procesar el pago |
transaction_id | Nuestro identificador interno | Es el que requiere el servicio de devoluciones |
order_idtiene 20 dígitos: trátalo como textoExcede la precisión de un número decimal (
double), así que si lo manejas como número vas a perder los últimos dígitos. Guárdalo y transpórtalo siempre como texto (string), y si lo exportas a Excel dale formato de celda como texto.La misma regla aplica para
transaction_id.
3. Una venta y sus devoluciones comparten identificadores
Cuando devuelves un cobro, la devolución queda como un registro aparte, con su propio transaction_id, pero comparte el order_id y el transaction_token_id del cobro original.
Por eso, al consultar por order_id recibes toda la cadena: el cobro y todas sus devoluciones.
4. El producto con el que cobraste
El campo product_name te dice con qué integración se procesó cada transacción. Te sirve para separar, por ejemplo, tus ventas en línea de las de tus terminales cuando consultas todo junto.
Configuración
Lo que necesitas
| Qué | Dónde lo obtienes |
|---|---|
Tu secretKey | NetPay Manager → Llaves. Es la misma que usas para cobrar |
Tus storeId | NetPay Manager, o pregúntale a tu ejecutivo de cuenta |
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 a la misma URL. Lo que cambia es el contenido del cuerpo.
Los headers
X-Netpay-Apikey: {tu secretKey}
Content-Type: application/json
El header esX-Netpay-Apikey, noAuthorizationEs el error más común al integrar este servicio. El API de cobro usa
Authorization; el de consulta usaX-Netpay-Apikey. Si mandas el header equivocado recibes un error de autenticación aunque tu llave sea correcta.
Tu primera consulta
Traigamos 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: [1234567] rangeDateFilter: { min: \"2026/09/09\", max: \"2026/09/09\" } ) { transaction_id order_id transaction_date auth_amount status } }"}'{
"data": {
"allTransactions": [
{
"transaction_id": "90296F9F-4915-0A46-F335-5E047CBB4CED",
"order_id": "17889789767211234567",
"transaction_date": "09/09/2026 12:36",
"auth_amount": 14,
"status": "Aprobada"
}
]
}
}Cómo se arma el cuerpo
El cuerpo es un JSON con una sola llave, query, cuyo valor es texto:
{ "query": "{ NOMBRE_DE_LA_CONSULTA( FILTROS ) { CAMPOS_QUE_QUIERES } }" }- NOMBRE_DE_LA_CONSULTA — normalmente
allTransactions. - FILTROS — qué transacciones quieres.
- CAMPOS_QUE_QUIERES — qué datos quieres de vuelta, separados por espacios.
Pedir solo los campos que necesitas hace la respuesta mucho más ligera. Si después necesitas un campo más, lo agregas a la lista.
Tres reglas que te van a ahorrar tiempo
Las fechas van escritas dentro del texto, no como variables de GraphQLSi intentas pasar las fechas con variables (
$min,$max) en los filtros de fecha, el servidor responde HTTP 500. Escríbelas directamente en el 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.{ "errors": [ { "message": "Field 'campo_inexistente' doesn't exist..." } ] }
Los montos vienen en pesos, no en centavos
auth_amount: 1678.14son mil seiscientos setenta y ocho pesos con catorce centavos. No los multipliques ni los dividas por 100.
Entender la respuesta
Los estados de una transacción
status | Qué pasó | ¿Hay dinero? |
|---|---|---|
Aprobada | El cobro fue autorizado | Sí, se te va a depositar |
Devolución | Registro de una devolución aplicada | Se resta de tu depósito |
Rechazada | El banco emisor rechazó el cobro | No |
Reversada | La operación se revirtió | No |
Cancelada | Se canceló antes de liquidar | No |
Devoluciónlleva acentoAl comparar en tu código, normaliza el texto (quita acentos y pasa a minúsculas) para no depender de la codificación de tu cliente HTTP.
Además de status, tienes dos campos de apoyo:
| Campo | Valores | Para qué sirve |
|---|---|---|
report_status | Pagada, No Exitosa | Te dice si ya se depositó |
conc_status | C cuando está conciliada | Confirmación de nuestro lado |
Los montos
| Campo | Qué es |
|---|---|
auth_amount | El monto autorizado |
capt_amount | El monto realmente capturado |
tip_amount | La propina, cuando aplica |
En una venta normal auth_amount y capt_amount son iguales. En preautorizaciones pueden diferir: autorizas un monto y capturas otro. Para efectos de dinero real, capt_amount es el que manda.
Súmalos con tipos decimales, no confloatSumar muchos
floatproduce errores de centavos en cualquier lenguaje. UsaDecimalen Python,BigDecimalen Java,decimalen C#, o trabaja en enteros de centavos internamente.
El mensaje del emisor
Cuando una transacción es rechazada, response_msg trae el motivo tal como lo devolvió el banco emisor. Es el primer lugar a revisar cuando un cliente te dice que su pago no pasó.
Las consultas disponibles
| Consulta | Para qué sirve | Velocidad |
|---|---|---|
allTransactions | La principal. Listados con cualquier combinación de filtros | Depende del rango |
transaction | Buscar por orderId o transactionId | La más rápida |
allTransactionsV2 | Misma información que allTransactions | Más lenta; usa la primera |
En la práctica vas a usar allTransactions para listados y transaction para búsquedas puntuales.
Siguientes pasos
- Buscar una transacción — soporte, verificación de pagos y aclaraciones.
- Reportes y exportaciones — listados por periodo y por punto de cobro.
- Conciliación de depósitos — cuadrar lo que te llega al banco.
- Referencia — catálogo completo de filtros, campos y errores.
