Respuestas, consulta y códigos

En Pay-me PinPAD 1.3.25, autorización y consulta usan success, resultCode y result.state / transaction.state, sin status propio. Cancelación y extorno conservan status. HTTP 200 o el mensaje por sí solos no confirman éxito. Todas las respuestas incluyen Connection: close y Cache-Control: no-store. Abre una conexión por petición, sin reutilizar keep-alive. HTTP 202 añade Retry-After: 2.

Estructura de respuesta de pago

Cancelación y extorno utilizan esta forma normal. El bloque describe tipos, no una respuesta de prueba:

{
  "operationNumber": "string",
  "status": "string",
  "resultCode": "string|null",
  "resultMessage": "string",
  "authorizationCode": "string|null",
  "completedAt": "string|null"
}

Campo	Uso
`operationNumber`	Referencia de la operación.
`status`	Estado propio de cancelación o extorno.
`resultCode`	Código SDK conservado o código propio de la app.
`resultMessage`	Mensaje recibido; no sustituye la interpretación del estado y código.
`authorizationCode`	Código de autorización o `null`.
`completedAt`	Fecha UTC en formato `yyyy-MM-dd'T'HH:mm:ss'Z'`, solo cuando la operación terminó; en espera es `null`.

Extorno UNKNOWN con HTTP 502 utiliza una forma compacta distinta:

{
  "operationNumber": "string",
  "status": "UNKNOWN",
  "message": "string"
}

Esta forma no incluye resultCode, resultMessage, authorizationCode ni completedAt. La clave del mensaje es message.

Respuestas de `POST /authorize`

La respuesta contiene operationNumber, success, resultCode, resultMessage y result, sin status propio. Ejemplo sintético mínimo:

{
  "operationNumber": "44992528",
  "success": true,
  "resultCode": "00",
  "resultMessage": "Operación autorizada",
  "result": { "transactionID": "a1b2c3d4-0001", "state": "AUTORIZADO", "amount": "100", "currency": "604" }
}

result puede incluir stateReason, additionalFields, paymentMethod (con name y methodDetail ofuscado), processorResponse como String crudo y lifecycle. Estos campos pertenecen al contrato vigente; authorization_code puede llegar dentro de processorResponse.

HTTP	Campos de decisión	Acción
`200`	`success: true`, `00`, `result.state: "AUTORIZADO"`	Confirmar el cobro.
`200`	`success: false`, código SDK y `result.state` crudo	Interpretar el desenlace del SDK; no decidir solo por HTTP.
`202`	`success: false`, `WAITING_RESULT`, `result: null`	Esperar dos segundos y consultar el cobro.
`400`	`success: false`, `BAD_REQUEST`, `result: null`	Corregir JSON o monto fuera del máximo configurado.
`409`	`success: false`, `POS_BUSY`, `result: null`	Esperar a que termine la operación activa.
`503`	`success: false`, `POS_NOT_AVAILABLE`, `result: null`	Restablecer disponibilidad.

{ "operationNumber": "44992528", "success": false, "resultCode": "WAITING_RESULT", "resultMessage": "Consulte el estado antes de reintentar", "result": null }

HTTP 202 puede corresponder a una solicitud duplicada aún en curso, al tiempo de espera agotado o al control de tiempo del servicio. No inicies otro cobro.

Consulta de estado

GET /payments/{operationNumber} consulta la pasarela, no el estado local ni el resultado de /cancel. Devuelve operationNumber, success, resultCode, resultMessage y transaction, sin status propio. Puede tardar 12–15 segundos; usa un timeout de cliente que cubra esa espera, por ejemplo 20 segundos.

{
  "operationNumber": "44992528",
  "success": true,
  "resultCode": "00",
  "resultMessage": "Operación encontrada",
  "transaction": { "transactionId": "a1b2c3d4-0001", "state": "AUTORIZADO", "amount": "100", "currency": "604", "authorizationCode": "123456" }
}

00 significa operación encontrada; interpreta el resultado financiero mediante transaction.state (por ejemplo, AUTORIZADO o CANCELADO). transaction puede incluir stateReason y lifecycle; no expone processorResponse ni methodDetail crudos. La consulta usa transactionId, mientras la autorización usa transactionID.

HTTP	`resultCode`	Resultado y acción
`200`	`00`	`success: true`, `transaction` encontrada; leer `transaction.state`.
`404`	`05`	`success: false`, `transaction: null`; verificar referencia y terminal.
`503`	`P04` o `POS_NOT_AVAILABLE`	`success: false`, `transaction: null`; restablecer SDK o disponibilidad.
`504`	`SEARCH_TIMEOUT`	`success: false`, `transaction: null`; no verificado a tiempo, consultar de nuevo.
`200`	`03`	`success: false`, `transaction: null`; consulta incierta del servicio.

Otros códigos SDK se reportan tal cual con 200, según el mapeo específico de la guía. Este GET no devuelve 202 ni estados locales. Una consulta fallida, incierta o no encontrada no confirma rechazo ni permite otro cobro.

Estados

Operación	Sigue esperando un resultado	La solicitud terminó
Cancelación (`PaymentStatus`)	`PENDING`	`CANCELLED`, `DENIED`, `ERROR`
Extorno (`ReversalStatus`)	`SEARCHING`, `PROCESSING`, `PENDING`	`REVERSED`, `DENIED`, `UNKNOWN`, `ERROR`

En la forma normal, completedAt se informa solo en los estados de la última columna. Un estado ERROR significa que terminó con error, no que hubo éxito. UNKNOWN en extorno es final y devuelve HTTP 502 con el cuerpo compacto: revisa si se ejecutó con Alignet, sin asumir éxito ni reenviar automáticamente.

Códigos confirmados

Mapeo de códigos SDK

Código SDK	Cancelación	Extorno CARD
`00`	`CANCELLED`	`REVERSED`
`16`, `17`	`CANCELLED`, éxito equivalente	`REVERSED`, éxito equivalente
`P22`	`PENDING`, HTTP `202`	`PENDING`, HTTP `202`
`05`, `07`	HTTP `404`, `ERROR/NOT_FOUND`	HTTP `404`, `ERROR/NOT_FOUND`
`14`, `15`, `18`, `19`, `20`, `01`, `03` y otros	`DENIED`	`DENIED`

Conserva los códigos SDK; no los reemplaces por 00 ni por un código inventado. 14 significa abandono por cierre de autorización en curso; 15, abandono con intento (QR cancelado). No confirman cancelación aprobada ni rechazo típico de tarjeta.

Códigos propios de la app

Código	Significado
`BAD_REQUEST`	JSON, campos o segmento de ruta inválidos.
`NOT_FOUND`	Cancelación, extorno o ruta no encontrados; la consulta del cobro usa `05`.
`POS_NOT_AVAILABLE`	SDK no listo o pantalla no disponible.
`POS_BUSY`	Terminal ocupado.
`CANCELLATION_IN_PROGRESS`	Ya existe una cancelación en curso para esa referencia.
`PROCESSING`, `SEARCHING`	Fases locales del extorno en curso; no son estados de `/payments`.
`WAITING_RESULT`	Tiempo de espera agotado, sin resultado confirmado.
`SEARCH_TIMEOUT`	Consulta del cobro no verificada a tiempo; HTTP `504`.
`UNKNOWN`	Extorno incierto final; HTTP `502`, cuerpo compacto con `message`.
`METHOD_NOT_ALLOWED`	Ruta válida con método HTTP incorrecto.

Matriz de decisión

Endpoint	Qué informa	Acción
`POST /authorize`	Resultado del cobro.	Confirmar `success: true`, `00` y `result.state: "AUTORIZADO"`.
`GET /payments/{operationNumber}`	Cobro en la pasarela.	`00` significa encontrada; interpretar `transaction.state`.
`POST /cancel`	Resultado de esa solicitud de cancelación.	Éxito solo con `CANCELLED` y `00`, `16` o `17`, validado por el servicio. `DENIED/14` no confirma cancelación.
`POST /reversals`	Resultado de un extorno CARD independiente.	Éxito con `REVERSED` y `00`, `16` o `17`.
`GET /reversals/{operationNumber}`	Estado local del extorno CARD.	Consultar cuando corresponda; HTTP `502 UNKNOWN` exige revisión.

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

Consulta después de cancelar

No existe un endpoint de consulta de cancelación: su desenlace se devuelve solo en POST /cancel. Si confirma una cancelación validada, no exige otro GET para reconocerla. Ante fallo, timeout o incertidumbre, consulta el cobro original y aplica la decisión por método. Un pago CARD encontrado con transaction.state: "AUTORIZADO" permite evaluar un extorno independiente; un pago QR aprobado se conserva sin devolución. No sustituyas un resultado confirmado por un 202 WAITING_RESULT tardío de /authorize ni uses el cierre de pantalla como prueba de cancelación.

Guía

Integraciones

Estructura de respuesta de pago

Respuestas de `POST /authorize`

Consulta de estado

Estados

Códigos confirmados

Mapeo de códigos SDK

Códigos propios de la app

Matriz de decisión

Consulta después de cancelar

​Estructura de respuesta de pago

​Respuestas de POST /authorize

​Consulta de estado

​Estados

​Códigos confirmados

​Mapeo de códigos SDK

​Códigos propios de la app

​Matriz de decisión

​Consulta después de cancelar

Estructura de respuesta de pago

Respuestas de `POST /authorize`

Consulta de estado

Estados

Códigos confirmados

Mapeo de códigos SDK

Códigos propios de la app

Matriz de decisión

Consulta después de cancelar