Devoluciones y consulta de transacciones

Guía de integración contra los servicios de NetPay para ejecutar devoluciones y consultar transacciones. Todo lo documentado aquí se ejercitó contra producción y sandbox.

📘

Sobre esta guía

El comportamiento descrito está verificado empíricamente contra los ambientes reales
(incluyendo un lote de 1,263 devoluciones en producción). Donde el comportamiento
observado difiere de lo que un integrador esperaría, se marca explícitamente.


Los tres servicios

NetPay expone estas capacidades en hosts distintos, con esquemas de autenticación
distintos
. Es el punto que más confusión genera al integrar.

ServicioPara qué sirveHeader de auth
Gateway e-commerceResolver el transactionId a partir de un tokenAuthorization
Reports — RESTEjecutar la devoluciónX-Netpay-Apikey
Reports — GraphQLConsultar transacciones y su estadoX-Netpay-Apikey

Las tres usan la misma secretKey del comercio; lo que cambia es el nombre del header.

URLs por ambiente

ServicioSandboxProducción
Gateway e-commercehttps://gateway-154.netpaydev.com/gateway-ecommerce/v3https://suite.netpay.com.mx/gateway-ecommerce/v3
Reports REST (devoluciones)https://gateway.netpay-api.com/reports-sandbox/v2https://out.netpay-api.com/reports/v2
Reports GraphQLhttps://gateway.netpay-api.com/reports-sandbox/v1https://gateway.netpay-api.com/reports/v1
🚧

El host de devoluciones cambia entre ambientes

En producción es out.netpay-api.com, no gateway.netpay-api.com. Y la versión es
v2, no v1. Apuntar al host equivocado devuelve 404 o 403, no un error descriptivo.


1. Devoluciones

Una devolución es un PUT sobre el transactionId de la transacción original.

Flujo de dos pasos

El identificador que recibe tu sistema al cobrar es un transactionTokenId (UUID).
El endpoint de devolución no lo acepta: necesita el transactionId, que es otro
identificador con formato distinto. Hay que resolverlo primero.

transactionTokenId  ──►  GET /get/{token}/transactionId  ──►  transactionId
       (UUID)                  Gateway e-commerce            (formato NetPay)
                                                                     │
                                                                     ▼
                                          PUT /transactions/{transactionId}/refund
                                                    Reports REST

Si ya tienes el transactionId (por ejemplo del GraphQL), puedes saltarte el paso 1.

Paso 1 — Resolver el transactionId

GET /gateway-ecommerce/v3/get/{transactionTokenId}/transactionId
Host: suite.netpay.com.mx
Authorization: {secretKey}
Accept: application/json

Ejemplo:

curl -X GET \
  "https://suite.netpay.com.mx/gateway-ecommerce/v3/get/4f78a3a2-ede0-4e80-b3bd-9822b4173bcb/transactionId" \
  -H "Authorization: sk_netpay_..." \
  -H "Accept: application/json"

La respuesta trae el transactionId. Formato observado: 8-4-4-4-12 en mayúsculas,
por ejemplo E1EB047F-D43C-7F91-D066-E1314A985807.

📘

Alternativa

El GraphQL también devuelve transaction_id y permite filtrar por transactionTokenId
u orderId. Si vas a procesar volumen, sale mejor resolverlos en lote por ahí
que uno por uno con este endpoint.

Paso 2 — Ejecutar la devolución

PUT /reports/v2/transactions/{transactionId}/refund
Host: out.netpay-api.com
X-Netpay-Apikey: {secretKey}
Content-Type: application/json
Accept: application/json

Request

CampoTipoRequeridoDescripción
amountstringSíMonto a devolver, en pesos con 2 decimales: "1678.14".
motivestringSíMotivo. Viaja al sistema de NetPay; evita saltos de línea y caracteres de control
{
  "amount": "1678.14",
  "motive": "Cancelacion de reserva"
}
curl -X PUT \
  "https://out.netpay-api.com/reports/v2/transactions/E1EB047F-D43C-7F91-D066-E1314A985807/refund" \
  -H "X-Netpay-Apikey: sk_netpay_..." \
  -H "Content-Type: application/json" \
  -d '{"amount":"1678.14","motive":"Cancelacion de reserva"}'
❗

El header es X-Netpay-Apikey, no Authorization

Este endpoint vive en un host distinto al gateway y usa otro esquema. Mandar
Authorization con la secretKey cruda devuelve un error de autenticación —
ese endpoint espera un JWT, no la secret key.

Response

Éxito — HTTP 200

{
  "message": "Transacción exitosa."
}

Transacción en aclaración o con contracargo — HTTP 409

{
  "message": "La transacción se encuentra en proceso de aclaración o presenta un contracargo"
}

Adquirente no disponible — HTTP 409

{
  "message": "El servicio de adquiriente no está disponible"
}

Distribución real observada en un lote de 1,263 devoluciones en producción:

ResultadoFrecuencia
HTTP 200 · Transacción exitosa.1,218 (96.4 %)
HTTP 409 · adquirente no disponible34 (2.7 %)
HTTP 409 · aclaración o contracargo11 (0.9 %)

Devoluciones parciales

Se soportan: manda un amount menor al de la transacción original. Una transacción puede
recibir varias devoluciones parciales sucesivas. La suma de las devoluciones no puede
exceder el monto autorizado.

Para saber cuánto queda por devolver, consulta el GraphQL y resta las devoluciones ya
aplicadas
del auth_amount original.


Consideraciones críticas para producción

❗

El PUT /refund no es idempotente y no acepta clave de idempotencia

El cuerpo solo admite amount y motive. No hay Idempotency-Key ni equivalente,
así que NetPay no puede deduplicar del lado del servidor.

No reintentes automáticamente. Un timeout de cliente o un 5xx no prueban que la
devolución no se haya aplicado: la petición pudo llegar y procesarse. Un reintento a
ciegas paga dos veces, y eso es irreversible.

Si tu cliente HTTP tiene reintentos por defecto, desactívalos para este endpoint.

Clasificación recomendada de respuestas

Ante una respuesta que no puedas interpretar con certeza, trátala como indeterminada
y reconcilia contra el GraphQL antes de decidir. Un falso "indeterminado" cuesta una
consulta; un falso "no aplicado" invita a duplicar el pago.

CódigoInterpretación segura
200 con confirmación en el cuerpoAplicada
200 con cuerpo vacío o no reconocidoIndeterminada — reconcilia
400, 401, 403, 404No aplicada (rechazo del emisor o de la petición)
408, 409, 429Indeterminada — reconcilia, no reintentes
5xxIndeterminada — reconcilia, no reintentes
Timeout del clienteIndeterminada — reconcilia, no reintentes

El 409 merece atención: no es un rechazo definitivo. En un caso observado, una transacción
que devolvió 409 · en proceso de aclaración apareció como Devolución en el GraphQL
dos días después. Reintentarla habría duplicado el pago.

Ventana de bloqueo

NetPay no permite la operación entre las 21:00 y las 23:59 del mismo día. Fuera de
esa ventana:

  • Antes de las 21:00 del día de la venta → cancelación (no llega a liquidar).
  • A partir del día siguiente → devolución, con 2 a 10 días hábiles de reflejo al
    tarjetahabiente.

El GraphQL tarda en reflejar la devolución

Una devolución aplicada no aparece de inmediato en el GraphQL. En un lote de producción,
transacciones devueltas seguían apareciendo como Aprobada una hora después.

Consecuencia práctica: si tu proceso reintenta usando el GraphQL como fuente de verdad
para "¿ya se devolvió?", vas a duplicar pagos. Lleva tu propio registro persistente de qué
transactionId ya enviaste, y consúltalo antes de cada envío.


2. GraphQL de consulta

Un único endpoint para todas las consultas.

POST /reports/v1/graphql
Host: gateway.netpay-api.com
X-Netpay-Apikey: {secretKey}
Content-Type: application/json
Accept: application/json

Cuerpo estándar de GraphQL:

{ "query": "{ allTransactions(...) { ... } }" }
❗

No uses variables de GraphQL en rangeDateFilter

El servidor responde HTTP 500 si rangeDateFilter recibe sus valores por variables,
tanto anidadas ({ min: $min, max: $max }) como pasando el objeto completo
(rangeDateFilter: $range). Los mismos valores inline funcionan.

Las variables sí funcionan para argumentos escalares (transactionTokenId, transactionId)
y para listas (storeId). Si interpolas fechas en el documento, valida el formato
YYYY/MM/DD antes para no abrir una inyección.

Consultas disponibles

ConsultaArgumentosNotas
allTransactionsver abajoLa principal
allTransactionsV2idénticos a allTransactionsMismos campos; más lenta en las pruebas
transactionorderId: String, transactionId: StringFiltra por ORDER ID. Muy rápida
allDepositsfilter: FilterDepósitos/liquidaciones

allTransactions — filtros

ArgumentoTipoDescripción
rangeDateFilterRangeDateFilterV2Rango por fecha de transacción. { min: "YYYY/MM/DD", max: "YYYY/MM/DD" }, inclusivo
paymentDateFilterRangeDateFilterV2Rango por fecha de pago
storeId[Int!]Uno o varios comercios: [1271824, 1271686]
companyIdIntEmpresa
transactionIdStringTransacción específica
transactionTokenIdStringPor token (el UUID del cobro)
externalReferenceStringReferencia externa
merchantRefCodeStringCódigo de referencia del comercio (MRC)
product[Int!]Producto. [7] = e-commerce
filterPreauth[Boolean!]Filtra preautorizaciones
paymentMethod[String!]Método de pago
promotion[String!]Promoción (meses sin intereses, etc.)
cognitoUserStringUsuario del portal

RangeDateFilterV2:

CampoTipo
minString! — "YYYY/MM/DD"
maxString! — "YYYY/MM/DD"
📘

No hay filtro por estado

No existe argumento para pedir solo Devolución o solo Aprobada. Trae el conjunto y
filtra por status del lado del cliente.

Campos de respuesta

CampoTipoDescripción
transaction_idStringIdentificador de la transacción. El que necesita el endpoint de devolución
transaction_token_idStringToken UUID del cobro
order_idStringNúmero de orden del comercio
transaction_dateString"DD/MM/YYYY HH:mm"
store_idIntComercio
store_nameStringNombre del comercio
auth_amountFloatMonto en pesos con decimales (1678.14), no en centavos
statusStringEstado. Ver tabla abajo
response_msgStringMensaje del emisor
payment_method_descriptionStringMarca/método (VISA, MASTERCARD, …)
span_route_numStringÚltimos dígitos de la tarjeta
product_nameStringProducto

Valores de status

ValorSignificado¿Devolvible?
AprobadaCobro autorizadoSí
DevoluciónRegistro de una devolución aplicadaNo — ya es una devolución
RechazadaEl emisor rechazó el cobroNo
ReversadaReversadaNo
CanceladaCanceladaNo
❗

Devolución lleva acento. Compáralo normalizando (sin acentos, minúsculas) para

no depender de la codificación de tu cliente.

🚧

El GraphQL no refleja los contracargos

Una transacción con contracargo aplicado sigue apareciendo como Aprobada. No hay forma
de detectarlo por esta vía. Si necesitas excluirlas, esa información tiene que venir de
otra fuente (el reporte de contracargos del comercio).


Ejemplos

Transacciones de un rango de fechas

{"query":"{ allTransactions( filterPreauth: true product: [7] rangeDateFilter: { min: \"2026/07/01\", max: \"2026/07/31\" } ) { transaction_id order_id transaction_date store_id store_name auth_amount status response_msg transaction_token_id } }"}

Varios comercios a la vez

{
  allTransactions(
    filterPreauth: true
    product: [7]
    storeId: [1271824, 1271686]
    rangeDateFilter: { min: "2026/07/28", max: "2026/07/28" }
  ) {
    transaction_id  order_id  transaction_date  store_id  store_name
    auth_amount  status  response_msg  transaction_token_id
  }
}
📘

Una secretKey puede ver varios comercios

Las keys no están aisladas por store_id: la key de un comercio consulta transacciones
de otro de la misma empresa. Una consulta sin storeId devuelve todos los comercios
asociados. Tenlo presente al diseñar tu control de acceso.

Por token

{
  allTransactions(
    filterPreauth: true
    product: [7]
    transactionTokenId: "4f78a3a2-ede0-4e80-b3bd-9822b4173bcb"
  ) {
    transaction_id order_id transaction_date status auth_amount
  }
}

Por ORDER ID

{
  transaction(orderId: "17753625933601271686") {
    transaction_id order_id transaction_date store_id auth_amount status transaction_token_id
  }
}

Es la consulta más rápida de las probadas (~0.6 s) y la vía natural si tu sistema
identifica las operaciones por número de orden.


Reconciliar una transacción

El caso más importante en producción: ¿esta transacción ya fue devuelta, y por cuánto?

El cobro y sus devoluciones comparten order_id y transaction_token_id, pero cada uno
tiene su propio transaction_id. Una consulta por cualquiera de los dos identificadores
compartidos devuelve toda la cadena:

{
  transaction(orderId: "17753625933601271686") {
    transaction_id transaction_date status auth_amount
  }
}
{
  "data": {
    "transaction": [
      {
        "transaction_id": "0456B80A-29EA-C68E-70D4-39BC18457FAB",
        "transaction_date": "30/07/2026 18:17",
        "status": "Devolución",
        "auth_amount": 3972.28
      },
      {
        "transaction_id": "C5AA942F-9362-33D2-7406-C2974B5477FF",
        "transaction_date": "04/04/2026 22:16",
        "status": "Aprobada",
        "auth_amount": 3972.28
      }
    ]
  }
}

Cómo interpretarlo

❗

No tomes el primer registro del arreglo. El orden no está garantizado y ambos

registros comparten identificadores. Recorre todos los candidatos y decide:

  1. Filtra los status == "Aprobada". Ese es el cobro original y de ahí sale el
    transaction_id para devolver.
  2. Si hay más de una Aprobada, es ambiguo: detente y revisa a mano.
  3. Suma el auth_amount de todos los registros Devolución. Eso es lo ya devuelto.
  4. disponible = auth_amount del cobro − suma de las devoluciones.
  5. Si disponible <= 0, ya está devuelta por completo. No la vuelvas a enviar.
  6. Verifica que el store_id del registro coincida con el que esperas.

Este procedimiento es también el que resuelve las respuestas indeterminadas del
endpoint de devolución: consulta la cadena y mira si existe una Devolución por el monto
esperado.


Rendimiento

Medido contra producción, comercio con volumen alto:

ConsultaResultadosTiempoTamaño
transaction(orderId:)1–3~0.6 s< 1 KB
allTransactions por token1–32–10 s< 1 KB
allTransactions 1 día~670~1 s~185 KB
allTransactions 1 mes~10,5002.5–6 s~2.6 MB
allTransactions 5 meses~37,0008–15 s~9 MB

No hay paginación ni truncamiento: la suma de cinco ventanas mensuales coincidió
exactamente con la consulta única de cinco meses (36,936 en ambas). Aun así, para rangos
amplios conviene trocear por mes y unir los resultados: cada respuesta es más chica y
el riesgo de timeout baja.

🚧

Cuidado al partir por fechas

Una devolución se registra con la fecha en que se aplicó, no con la del cobro. En datos
reales, el 50 % de las devoluciones cayó en un mes distinto al del cobro, con hasta
105 días de diferencia.

Si consultas solo el mes del cobro para saber si algo ya se devolvió, vas a ver la
Aprobada y no su Devolución, y concluirás que sigue pendiente. La ventana debe llegar
hasta hoy.


Errores comunes

SíntomaCausa
HTTP 500 en una consulta con fechasrangeDateFilter recibió variables de GraphQL. Va inline
HTTP 200 con {"errors": [...]}Error de GraphQL. Un 200 no significa éxito: revisa errors antes de leer data
Error de autenticación en el refundSe mandó Authorization en vez de X-Netpay-Apikey
404 en el refundHost o versión incorrectos: producción es out.netpay-api.com/reports/**v2**
data.allTransactions vacíoLos filtros product y filterPreauth excluyen registros. Prueba sin ellos
Montos ×100 o ÷100auth_amount viene en pesos con decimales, no en centavos
El ORDER ID pierde dígitosTiene 20 dígitos y excede la precisión de un double. Trátalo como string en todo el flujo, y si lo exportas a Excel, tipifica la celda como texto

Checklist de integración

  • Los tres hosts configurados por ambiente, con la versión correcta (v2 para devoluciones).
  • X-Netpay-Apikey en Reports, Authorization en Gateway.
  • Reintentos automáticos desactivados en el PUT /refund.
  • Registro persistente de los transactionId ya enviados, consultado antes de cada envío.
  • Estado indeterminado modelado como algo distinto de éxito y de fallo.
  • Montos manejados en pesos con decimales.
  • order_id y transaction_id tratados como strings, nunca como números.
  • Comparación de status normalizando acentos.
  • Ventanas de consulta que llegan hasta hoy, no solo al mes del cobro.
  • Operación fuera de la ventana 21:00–23:59.