> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pay-me.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Referencia de endpoints

> Métodos, rutas y códigos HTTP de la interfaz local de Pay-me Transit PinPAD.

El sistema central consume la interfaz HTTP/JSON que expone Pay-me PinPAD en el Wiseasy P5L. Construye todas las solicitudes a partir de la URL configurada para cada terminal:

```text theme={"system"}
http://<IP_DEL_PINPAD>:<PUERTO>
```

El puerto predeterminado es `8080`. Confirma la IP y el puerto de cada terminal antes de integrar.

## Endpoints disponibles

| Método | Ruta | Uso | Respuestas documentadas |
| - | - | - | - |
| `GET` | `/health` | Verificar que Pay-me PinPAD esté accesible. | `200` |
| `POST` | `/authorize` | Iniciar CARD o QR; generar el QR crea la transacción pendiente. | `200`, `202`, `400`, `409`, `503` |
| `GET` | `/payments/{operationNumber}` | Consultar el cobro en la pasarela. | `200`, `400`, `404`, `503`, `504` |
| `POST` | `/cancel` | Solicitar cancelar una autorización activa. | `200`, `202`, `400`, `404`, `409`, `503` |
| `POST` | `/reversals` | Solicitar un extorno explícito de una venta CARD aprobada. No aplica a QR. | `200`, `202`, `400`, `404`, `409`, `502`, `503` |
| `GET` | `/reversals/{operationNumber}` | Consultar el estado local del extorno CARD. | `200`, `202`, `400`, `404`, `502` |

<Note>
  `POST /cancel` y `POST /reversals` son operaciones distintas. Ambas usan el `operationNumber` de la autorización original y se consumen en el mismo host y puerto que `POST /authorize`.
</Note>

No existe un endpoint de consulta de cancelación. Su desenlace se devuelve solo en `POST /cancel`; `/payments` consulta el cobro original. Todas las respuestas incluyen `Connection: close` y `Cache-Control: no-store`; abre una conexión por petición. Solo HTTP `202` añade `Retry-After: 2`.

## Verificar disponibilidad

```http theme={"system"}
GET /health
```

```bash theme={"system"}
curl --header "Connection: close" "http://<IP_DEL_PINPAD>:<PUERTO>/health"
```

Respuesta esperada:

```json theme={"system"}
{
  "status": "UP",
  "service": "Alignet ECR"
}
```

Usa `GET /health` al configurar el terminal y antes de iniciar operaciones cuando necesites comprobar disponibilidad. Una respuesta satisfactoria confirma la aplicación local; no confirma que el SDK esté inicializado ni que el procesador aprobará pagos.

## Autorizar y consultar un pago

`POST /authorize` requiere un cuerpo JSON. Consulta [Solicitud de autorización](/procesamiento-fisico/alignet-transit/parametros-de-envio) para conocer los campos, las validaciones y los ejemplos.

`POST /authorize` devuelve `success`, `resultCode`, `resultMessage` y `result`, sin `status` propio. `GET /payments/{operationNumber}` consulta la pasarela y devuelve `success`, `resultCode`, `resultMessage` y `transaction`, también sin `status` propio. `00` significa encontrada: lee `transaction.state`. Este GET no devuelve `202`; consulta el [contrato y la tabla HTTP](/procesamiento-fisico/alignet-transit/respuesta-estados-y-codigos#consulta-de-estado). No lleva cuerpo. Usa exactamente la referencia enviada en la autorización:

```bash theme={"system"}
curl -i --header "Connection: close" --max-time 20 "http://<IP_DEL_PINPAD>:<PUERTO>/payments/44992528"
```

## Cancelar una autorización activa

`POST /cancel` recibe el `operationNumber` original. Reconoce cancelación exitosa solo con `CANCELLED` y `00`, `16` o `17`, validada por el servicio. HTTP `200` con `DENIED`, incluido `14`, no confirma éxito.

Ante fallo, timeout o incertidumbre, consulta el cobro original; no hay un GET de cancelación. El cierre de pantalla no acredita el resultado. Revisa las [respuestas y acciones de cancelación](/procesamiento-fisico/alignet-transit/cancelacion).

En QR solo se cancela o inhabilita el código; ni `/cancel` ni refund devuelven pagos. Un QR encontrado con `transaction.state: "AUTORIZADO"` conserva el pago aprobado, sin reversa.

## Extornar una venta aprobada

`POST /reversals` solicita un extorno independiente y total de una venta CARD aprobada. No aplica a QR. Usa `GET /reversals/{operationNumber}` ante espera, timeout o pérdida de respuesta. Encontrar el cobro original no determina el resultado del extorno.

Consulta [Extorno de una venta CARD aprobada](/procesamiento-fisico/alignet-transit/extorno) para interpretar `REVERSED`, `DENIED` y el cuerpo compacto de `502 UNKNOWN`.

## Rutas fuera del contrato vigente

Una ruta válida con método incorrecto devuelve HTTP `405` y `METHOD_NOT_ALLOWED`; una ruta desconocida devuelve HTTP `404` y `NOT_FOUND`.

No uses `/payment`, `/api/v1/payments`, `/api/v1/payments/{operationNumber}` ni `DELETE /charges` para esta integración. La autorización vigente sí incluye `result.state` y puede incluir `transactionID`, `processorResponse` y `lifecycle`. No traslades a esta interfaz los códigos locales `P01–P21` de otras especificaciones.

<CardGroup cols={2}>
  <Card title="Solicitud de autorización" icon="file-export" href="/procesamiento-fisico/alignet-transit/parametros-de-envio">
    Implementa el payload de `POST /authorize`.
  </Card>

  <Card title="Respuestas y códigos" icon="list-check" href="/procesamiento-fisico/alignet-transit/respuesta-estados-y-codigos">
    Interpreta códigos HTTP y estados transaccionales.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.