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íaEl 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.
| Servicio | Para qué sirve | Header de auth |
|---|---|---|
| Gateway e-commerce | Resolver el transactionId a partir de un token | Authorization |
| Reports — REST | Ejecutar la devolución | X-Netpay-Apikey |
| Reports — GraphQL | Consultar transacciones y su estado | X-Netpay-Apikey |
Las tres usan la misma secretKey del comercio; lo que cambia es el nombre del header.
URLs por ambiente
| Servicio | Sandbox | Producción |
|---|---|---|
| Gateway e-commerce | https://gateway-154.netpaydev.com/gateway-ecommerce/v3 | https://suite.netpay.com.mx/gateway-ecommerce/v3 |
| Reports REST (devoluciones) | https://gateway.netpay-api.com/reports-sandbox/v2 | https://out.netpay-api.com/reports/v2 |
| Reports GraphQL | https://gateway.netpay-api.com/reports-sandbox/v1 | https://gateway.netpay-api.com/reports/v1 |
El host de devoluciones cambia entre ambientesEn producción es
out.netpay-api.com, nogateway.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
transactionIdGET /gateway-ecommerce/v3/get/{transactionTokenId}/transactionId
Host: suite.netpay.com.mx
Authorization: {secretKey}
Accept: application/jsonEjemplo:
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.
AlternativaEl GraphQL también devuelve
transaction_idy permite filtrar portransactionTokenId
uorderId. 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/jsonRequest
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
amount | string | Sí | Monto a devolver, en pesos con 2 decimales: "1678.14". |
motive | string | Sí | 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 esX-Netpay-Apikey, noAuthorizationEste endpoint vive en un host distinto al gateway y usa otro esquema. Mandar
Authorizationcon lasecretKeycruda 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:
| Resultado | Frecuencia |
|---|---|
HTTP 200 · Transacción exitosa. | 1,218 (96.4 %) |
| HTTP 409 · adquirente no disponible | 34 (2.7 %) |
| HTTP 409 · aclaración o contracargo | 11 (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
ElPUT /refundno es idempotente y no acepta clave de idempotenciaEl cuerpo solo admite
amountymotive. No hayIdempotency-Keyni 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ódigo | Interpretación segura |
|---|---|
| 200 con confirmación en el cuerpo | Aplicada |
| 200 con cuerpo vacío o no reconocido | Indeterminada — reconcilia |
| 400, 401, 403, 404 | No aplicada (rechazo del emisor o de la petición) |
| 408, 409, 429 | Indeterminada — reconcilia, no reintentes |
| 5xx | Indeterminada — reconcilia, no reintentes |
| Timeout del cliente | Indeterminada — 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/jsonCuerpo estándar de GraphQL:
{ "query": "{ allTransactions(...) { ... } }" }
No uses variables de GraphQL enrangeDateFilterEl servidor responde HTTP 500 si
rangeDateFilterrecibe 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/DDantes para no abrir una inyección.
Consultas disponibles
| Consulta | Argumentos | Notas |
|---|---|---|
allTransactions | ver abajo | La principal |
allTransactionsV2 | idénticos a allTransactions | Mismos campos; más lenta en las pruebas |
transaction | orderId: String, transactionId: String | Filtra por ORDER ID. Muy rápida |
allDeposits | filter: Filter | Depósitos/liquidaciones |
allTransactions — filtros
allTransactions — filtros| Argumento | Tipo | Descripción |
|---|---|---|
rangeDateFilter | RangeDateFilterV2 | Rango por fecha de transacción. { min: "YYYY/MM/DD", max: "YYYY/MM/DD" }, inclusivo |
paymentDateFilter | RangeDateFilterV2 | Rango por fecha de pago |
storeId | [Int!] | Uno o varios comercios: [1271824, 1271686] |
companyId | Int | Empresa |
transactionId | String | Transacción específica |
transactionTokenId | String | Por token (el UUID del cobro) |
externalReference | String | Referencia externa |
merchantRefCode | String | Có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.) |
cognitoUser | String | Usuario del portal |
RangeDateFilterV2:
| Campo | Tipo |
|---|---|
min | String! — "YYYY/MM/DD" |
max | String! — "YYYY/MM/DD" |
No hay filtro por estadoNo existe argumento para pedir solo
Devolucióno soloAprobada. Trae el conjunto y
filtra porstatusdel lado del cliente.
Campos de respuesta
| Campo | Tipo | Descripción |
|---|---|---|
transaction_id | String | Identificador de la transacción. El que necesita el endpoint de devolución |
transaction_token_id | String | Token UUID del cobro |
order_id | String | Número de orden del comercio |
transaction_date | String | "DD/MM/YYYY HH:mm" |
store_id | Int | Comercio |
store_name | String | Nombre del comercio |
auth_amount | Float | Monto en pesos con decimales (1678.14), no en centavos |
status | String | Estado. Ver tabla abajo |
response_msg | String | Mensaje del emisor |
payment_method_description | String | Marca/método (VISA, MASTERCARD, …) |
span_route_num | String | Últimos dígitos de la tarjeta |
product_name | String | Producto |
Valores de status
status| Valor | Significado | ¿Devolvible? |
|---|---|---|
Aprobada | Cobro autorizado | Sí |
Devolución | Registro de una devolución aplicada | No — ya es una devolución |
Rechazada | El emisor rechazó el cobro | No |
Reversada | Reversada | No |
Cancelada | Cancelada | No |
Devoluciónlleva acento. Compáralo normalizando (sin acentos, minúsculas) parano depender de la codificación de tu cliente.
El GraphQL no refleja los contracargosUna 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
}
}
UnasecretKeypuede ver varios comerciosLas keys no están aisladas por
store_id: la key de un comercio consulta transacciones
de otro de la misma empresa. Una consulta sinstoreIddevuelve 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 ambosregistros comparten identificadores. Recorre todos los candidatos y decide:
- Filtra los
status == "Aprobada". Ese es el cobro original y de ahí sale el
transaction_idpara devolver. - Si hay más de una
Aprobada, es ambiguo: detente y revisa a mano. - Suma el
auth_amountde todos los registrosDevolución. Eso es lo ya devuelto. disponible = auth_amount del cobro − suma de las devoluciones.- Si
disponible <= 0, ya está devuelta por completo. No la vuelvas a enviar. - Verifica que el
store_iddel 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:
| Consulta | Resultados | Tiempo | Tamaño |
|---|---|---|---|
transaction(orderId:) | 1–3 | ~0.6 s | < 1 KB |
allTransactions por token | 1–3 | 2–10 s | < 1 KB |
allTransactions 1 día | ~670 | ~1 s | ~185 KB |
allTransactions 1 mes | ~10,500 | 2.5–6 s | ~2.6 MB |
allTransactions 5 meses | ~37,000 | 8–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 fechasUna 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
Aprobaday no suDevolución, y concluirás que sigue pendiente. La ventana debe llegar
hasta hoy.
Errores comunes
| Síntoma | Causa |
|---|---|
| HTTP 500 en una consulta con fechas | rangeDateFilter 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 refund | Se mandó Authorization en vez de X-Netpay-Apikey |
| 404 en el refund | Host o versión incorrectos: producción es out.netpay-api.com/reports/**v2** |
data.allTransactions vacío | Los filtros product y filterPreauth excluyen registros. Prueba sin ellos |
| Montos ×100 o ÷100 | auth_amount viene en pesos con decimales, no en centavos |
| El ORDER ID pierde dígitos | Tiene 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 (
v2para devoluciones). -
X-Netpay-Apikeyen Reports,Authorizationen Gateway. - Reintentos automáticos desactivados en el
PUT /refund. - Registro persistente de los
transactionIdya enviados, consultado antes de cada envío. - Estado
indeterminadomodelado como algo distinto de éxito y de fallo. - Montos manejados en pesos con decimales.
-
order_idytransaction_idtratados como strings, nunca como números. - Comparación de
statusnormalizando acentos. - Ventanas de consulta que llegan hasta hoy, no solo al mes del cobro.
- Operación fuera de la ventana 21:00–23:59.
