Referencia

Catálogo completo de filtros, campos, errores comunes y preguntas frecuentes del API de Consulta.

Consulta de referencia para el API de Consulta de Transacciones.


Consultas

ConsultaArgumentosUso
allTransactionsTodos los filtros de abajoListados. La principal
transactionorderId, transactionIdBúsqueda puntual. La más rápida
allTransactionsV2Los mismos que allTransactionsMisma información, más lenta

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 puntos de cobro: [1234567, 1234568]
companyIdenteroEmpresa
transactionIdtextoUna transacción específica
transactionTokenIdtextoEl token UUID del cobro
externalReferencetextoTu referencia externa
merchantRefCodetextoTu código de referencia de comercio
paymentMethodlista de textoMétodo de pago
promotionlista de textoPromoción (meses sin intereses, etc.)
filterPreauthlista de booleanosFiltra preautorizaciones
productlista de enterosProducto
cognitoUsertextoUsuario del portal
🚧

product y filterPreauth excluyen registros

Úsalos solo cuando quieras acotar deliberadamente. Para reportes y conciliación, déjalos fuera y clasifica en tu sistema.

❗

Los filtros de fecha no aceptan variables de GraphQL

rangeDateFilter y paymentDateFilter responden HTTP 500 si reciben sus valores por variables. Escribe las fechas dentro del texto de la consulta.

Las variables sí funcionan para los filtros de texto (transactionTokenId, transactionId) y para listas (storeId).


Campos de la respuesta

Identificadores

CampoTipoDescripción
transaction_idtextoIdentificador de la transacción. Es el que pide el servicio de devoluciones
transaction_token_idtextoToken UUID del cobro
order_idtextoTu número de orden. 20 dígitos: manéjalo siempre como texto
external_referencetextoTu referencia externa
merchant_ref_codetextoTu código de referencia

Comercio y punto de cobro

CampoTipoDescripción
store_identeroPunto de cobro
store_nametextoNombre del punto de cobro
branch_id, branch_nameentero, textoSucursal
company_id, company_nameentero, textoEmpresa
merchant_id, sub_merchant_idtextoAfiliación
terminal_idtextoTerminal física
cashiertextoCajero
product_id, product_nameentero, textoProducto con el que se procesó

Fechas

CampoFormatoDescripción
transaction_dateDD/MM/YYYY HH:mmFecha de la venta
payment_date_npDD/MM/YYYY HH:mmFecha del depósito. Vacío si aún no se deposita
void_dateDD/MM/YYYY HH:mmFecha de cancelación

Montos

Todos los montos vienen en pesos con decimales, no en centavos.

CampoTipoDescripción
auth_amountdecimalMonto autorizado
capt_amountdecimalMonto capturado. Es el que cuenta para el depósito
tip_amountdecimalPropina
sales_tax_amounttextoImpuesto
currencytextoMoneda (MXN)

Estados

CampoDescripción
statusEstado principal. Ver tabla abajo
report_statusPagada / No Exitosa
conc_statusC cuando está conciliada
response_codeCódigo de respuesta del emisor
response_msgMensaje del emisor. Motivo del rechazo cuando aplica

Valores de status

ValorSignificado¿Hay dinero?
AprobadaCobro autorizadoSí
DevoluciónRegistro de una devolución aplicadaSe resta
RechazadaEl emisor rechazó el cobroNo
ReversadaLa operación se revirtióNo
CanceladaSe canceló antes de liquidarNo

Autorización y rastreo

CampoDescripción
auth_codeCódigo de autorización del emisor. Prueba del cobro
host_ref_numReferencia del adquirente
eciIndicador de comercio electrónico (3D Secure)

Tarjeta

CampoDescripción
brandMarca (Visa, Mastercard, Amex)
card_typeCrédito o débito
span_route_numÚltimos dígitos de la tarjeta
bank_nameBanco emisor
payment_method, payment_method_descriptionMétodo de pago

Promociones

CampoDescripción
promotionPromoción aplicada
promo_termPlazo
promo_term_descriptionDescripción del plazo

Disputas y contracargos

CampoDescripción
dispute_stateEstado de la disputa
dispute_case_numberNúmero de caso
disputed_amountMonto disputado
dispute_creation_dateFecha de apertura

Cliente

CampoDescripción
email_clientCorreo del comprador
phone_numberTeléfono
📘

Hay más campos disponibles

El servicio expone campos adicionales. Si necesitas alguno que no esté aquí, consulta con tu ejecutivo de cuenta.


Buenas prácticas

PrácticaPor qué
Pide solo los campos que necesitasLa respuesta pesa una fracción
Trocea rangos amplios por mesNo hay paginación; respuestas grandes arriesgan timeout
Manda una referencia propia al cobrarTe permite buscar desde tus identificadores
Guarda el transaction_token_id al cobrarLocalizas cualquier transacción sin depender de fechas
order_id y transaction_id como textoComo número pierden dígitos
Montos con tipos decimalesfloat genera diferencias de centavos
Normaliza acentos al comparar statusDevolución lleva acento
Revisa errors aunque el HTTP sea 200Los errores de consulta vienen con código 200

Errores comunes

SíntomaCausaSolución
Error de autenticaciónHeader equivocadoUsa X-Netpay-Apikey, no Authorization
HTTP 500 en consultas con fechasVariables de GraphQL en los filtros de fechaEscribe las fechas dentro del texto de la consulta
HTTP 200 pero con errorsError en la consultaRevisa errors; indica el campo o argumento inválido
HTTP 404URL o ambiente incorrectoVerifica la URL de tu ambiente
La respuesta viene vacíaFiltros product o filterPreauth, o no hay movimiento en ese rangoQuita esos filtros y verifica las fechas
Montos multiplicados o divididos por 100Asumiste centavosLos montos vienen en pesos con decimales
El número de orden pierde los últimos dígitosSe procesó como númeroManéjalo como texto en todo el flujo
Diferencias de centavos al sumarSe usó floatUsa tipos decimales
La comparación de status fallaProblema de acentosNormaliza el texto al comparar
Una venta no aparece en ningún depósitopayment_date_np vacíoTodavía no se liquida; consulta después
La conciliación no cuadra por devolucionesLa ventana no llega hasta hoyAmplía el rango: las devoluciones se fechan cuando se aplican

Checklist de integración

Configuración

  • Header X-Netpay-Apikey configurado.
  • URL correcta por ambiente, probado primero en sandbox.
  • storeId de todos tus puntos de cobro identificados.

Construcción de consultas

  • Fechas escritas dentro del texto de la consulta, con formato validado.
  • Solo los campos necesarios en cada consulta.
  • Rangos amplios troceados por mes.

Manejo de la respuesta

  • Se revisa errors aunque el HTTP sea 200.
  • order_id y transaction_id tratados como texto.
  • Montos con tipos decimales, en pesos.
  • Comparación de status normalizando acentos.
  • Al consultar por order_id, se recorre todo el arreglo.

Preguntas frecuentes

¿Puedo consultar todos mis comercios con una sola llave?
Sí. Si omites storeId, la consulta devuelve todos los comercios asociados a tu llave dentro de la misma empresa.

¿Cada cuánto puedo consultar?
Evita consultas repetidas de rangos amplios. Para procesos automáticos, una corrida diaria es suficiente.

¿Esto reemplaza mis webhooks?
No. Los webhooks te avisan en tiempo real; este servicio es para consultar, verificar y conciliar.

¿Por qué una venta aprobada no aparece en ningún depósito?
Porque todavía no se liquida. Si payment_date_np está vacío, está pendiente.

¿Puedo aplicar devoluciones desde aquí?
No. Este servicio solo consulta. Las devoluciones se aplican con el servicio de Cancelaciones y reembolsos.

¿Los montos incluyen comisiones?
No. Los montos son los de la venta y los depósitos se hacen en bruto. Las comisiones se cobran por separado.

¿Cómo distingo mis ventas en línea de las de terminal?
Con product_name y terminal_id.

¿Por qué dos ventas del mismo día se depositaron en fechas distintas?
Porque el plazo de depósito depende de la marca de la tarjeta. Por eso la conciliación se hace con payment_date_np y no con una regla de días.