Buscar una transacción

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 elemento

Si 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:

FiltroCampo que consulta
externalReferenceTu referencia externa
merchantRefCodeTu 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ón

Manda 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 vesQué significaQué hacer
status: "Aprobada" con auth_codeEl 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 nadaLa transacción nunca llegó a nosotrosRevisa tu integración de cobro
📘

Esto no sustituye al webhook

Los 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 } }"}'
CampoPara qué te sirve
auth_codeEl código de autorización del banco. Es la prueba del cobro
host_ref_numReferencia del adquirente, para rastreo con el banco
span_route_numÚltimos dígitos de la tarjeta, para confirmar con el cliente
brand, card_typeMarca y si fue crédito o débito
promotion, promo_termSi fue a meses sin intereses y a qué plazo
void_dateSi la transacción ya fue cancelada
dispute_stateSi existe un contracargo en proceso
🚧

Los contracargos afectan tu depósito

Si 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 disponible

Una 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