Localiza una venta específica para verificar un pago o atender la aclaración de un cliente.
Esta página cubre las búsquedas puntuales: encontrar una venta concreta cuando un cliente pregunta, cuando tu sistema no registró una confirmación, o cuando necesitas los datos para responder una aclaración.
Si es tu primera vez con este servicio, empieza por API de Consulta de Transacciones para la configuración y los conceptos.
Por tu número de orden (recomendado)
Es la consulta más rápida y la más natural: tú ya tienes el order_id en tu sistema.
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: \"17889789767211234567\") { transaction_id order_id transaction_date status auth_amount capt_amount auth_code response_msg payment_date_np } }"}'
La respuesta es un arreglo: no tomes el primer elementoSi esa venta tiene devoluciones, vienen todas en el mismo arreglo y el orden no está garantizado. Recórrelo completo:
- El cobro original es el que tiene
status: "Aprobada".- Lo ya devuelto es la suma de los registros con
status: "Devolución".- Lo que queda disponible para devolver es: monto del cobro − suma de devoluciones.
Por el token de la transacción
Si guardaste el UUID que te devolvimos al cobrar:
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 transaction_date status auth_amount } }"}'Por tu propia referencia
Si al cobrar mandaste una referencia propia, puedes buscar por ella:
| Filtro | Campo que consulta |
|---|---|
externalReference | Tu referencia externa |
merchantRefCode | Tu código de referencia de comercio |
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( externalReference: \"FACTURA-2026-0912\" ) { transaction_id order_id external_reference transaction_date status auth_amount } }"}'
Recomendación de integraciónManda siempre una referencia propia al cobrar. Te permite encontrar la transacción desde tus propios identificadores sin tener que guardar los nuestros.
Verificar el estado de un pago
Caso típico: un cliente dice que pagó pero tu sistema no registró la confirmació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":"{ transaction(orderId: \"TU_ORDEN\") { transaction_id status response_msg auth_code transaction_date auth_amount capt_amount brand span_route_num } }"}'Cómo interpretar el resultado:
| Lo que ves | Qué significa | Qué hacer |
|---|---|---|
status: "Aprobada" con auth_code | El cobro sí se procesó | Libera el pedido; revisa por qué no llegó tu notificación |
status: "Rechazada" | El emisor lo rechazó | Revisa response_msg y pide otro método de pago |
| La consulta no devuelve nada | La transacción nunca llegó a nosotros | Revisa tu integración de cobro |
Esto no sustituye al webhookLos webhooks son la forma correcta de enterarte de un pago en tiempo real. Esta consulta es para verificar y para los casos donde tu sistema no recibió la notificación.
Atender aclaraciones
Cuando un cliente reclama un cargo, esta consulta te da todo lo que necesitas para responderle:
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: \"TU_ORDEN\") { transaction_id transaction_date auth_amount capt_amount status auth_code host_ref_num brand card_type span_route_num promotion promo_term void_date dispute_state dispute_case_number disputed_amount } }"}'| Campo | Para qué te sirve |
|---|---|
auth_code | El código de autorización del banco. Es la prueba del cobro |
host_ref_num | Referencia del adquirente, para rastreo con el banco |
span_route_num | Últimos dígitos de la tarjeta, para confirmar con el cliente |
brand, card_type | Marca y si fue crédito o débito |
promotion, promo_term | Si fue a meses sin intereses y a qué plazo |
void_date | Si la transacción ya fue cancelada |
dispute_state | Si existe un contracargo en proceso |
Los contracargos afectan tu depósitoSi un depósito no te cuadra y no lo explican las ventas ni las devoluciones, revisa los campos de disputa. Un contracargo aplicado puede descontarse de tu liquidación.
Verificar una devolución
Este servicio es de consulta: no ejecuta devoluciones. Para aplicarlas, consulta la guía de Cancelaciones y reembolsos.
Lo que sí hace este servicio, y te conviene usar, es darte el transaction_id que el servicio de devoluciones necesita, y permitirte verificar después si la devolución quedó aplicada:
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: \"TU_ORDEN\") { transaction_id status auth_amount capt_amount transaction_date } }"}'Si aparece un registro con status: "Devolución" por el monto esperado, la devolución está aplicada.
Antes de devolver, verifica cuánto queda disponibleUna transacción puede recibir varias devoluciones parciales. Consulta la cadena por
order_id, suma las devoluciones ya aplicadas y réstalas del monto del cobro. Si el resultado es cero o menos, ya está devuelta por completo.
Siguientes pasos
- 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 y campos.
