Una integración.
Más formas
de pagar.

Conecta tu negocio con una infraestructura de pagos diseñada para acompañar tu crecimiento.

Tecnología de Alignet. Conexión directa.

Marcas prioritarias

Métodos de pago

BilleteraTransferenciaCompra ahora, paga despuésCódigo YapeG Pay

SEGURIDAD / BUENAS PRÁCTICAS

La confianza tambiénse integra.

Protege cada acceso. Confirma cada operación. Diseña una integración que puedas entender y acompañar cuando algo no salga como esperas.

SEGURIDAD EN CADA CAPA

✓

Accesos privadosSecretos en tu servidor

02
Estado verificadoAntes de confirmar la venta

03
Rastro de la operaciónSin exponer datos sensibles

Controles complementarios.
Ninguno sustituye a los demás.

## Tres principios para empezar
01 / PROTEGE
Secretos en el servidor.
Las credenciales privadas nunca forman parte del navegador, la app ni el repositorio.
02 / VERIFICA
El estado, desde backend.
La respuesta visual no basta para confirmar una venta o entregar un pedido.
03 / REGISTRA
Trazabilidad sin exponer.
Relaciona pedido y operación. Registra lo necesario, no los datos sensibles.
## Aplica los controles * Guarda Client Secret, llaves privadas y tokens sensibles en variables de entorno o un gestor de secretos del servidor. * Mantén separadas las configuraciones de sandbox y producción. * Ejecuta las operaciones sensibles desde backend mediante HTTPS y limita el acceso a las credenciales. * No incluyas secretos en URLs, capturas, mensajes de soporte ni registros. Ante una exposición, coordina su revocación o rotación. * Relaciona el identificador de tu pedido con el de la operación de Pay-me. * Verifica desde backend el estado mediante el mecanismo documentado para tu integración. * Comprueba la correspondencia del pedido, importe y moneda antes de actualizar tu sistema. * Trata los estados pendientes o inciertos como tales. Un timeout no demuestra que un pago haya sido rechazado. * Cuando tu flujo utilice notificaciones, valida su autenticidad según la guía específica del canal. * Evita procesar dos veces un mismo evento o ejecutar dos veces la entrega de un pedido. * Contempla eventos duplicados o fuera de orden, y conserva estados coherentes en tu sistema. * Antes de repetir una operación con resultado incierto, consulta o reconcilia su estado según el flujo documentado. * Conserva identificadores, fecha, entorno, código de respuesta y resultado esperado para investigar incidencias. * Enmascara los datos personales necesarios. No registres CVV, números completos de tarjeta, secretos ni tokens sensibles. * Define alertas para errores repetidos, timeouts o variaciones inusuales en los resultados. * Prueba los medios de pago habilitados y los escenarios aplicables: aprobación, rechazo, pendiente, expiración y error controlado. ## Aterrízalo en tu canal Esta base es transversal. Los mecanismos concretos, parámetros y responsabilidades dependen de tu integración. Plugins, pedidos y operación de tu tienda. Flex, callbacks y experiencia de pago web. Sesiones, callbacks y pruebas en dispositivos. Autenticación, respuestas y responsabilidades del servidor. ## El siguiente paso Ejecuta los escenarios de tu canal, reúne evidencias y coordina la certificación. # Checklist de certificación Source: https://docs.pay-me.com/primeros-pasos/checklist-de-certificacion Prueba tu integración, reúne evidencias y coordina la validación antes de operar en producción con Pay-me.
PRUEBAS Y PRODUCCIÓN / CERTIFICACIÓN
Prueba con criterio.Lanza con confianza.
Valida el recorrido completo del pago y prepara las evidencias para la revisión técnica. Esta es tu ruta; los requisitos específicos están en la guía de tu canal.

COBERTURA DE TUS PRUEBAS
✓AprobaciónConfirma el pedido
×RechazoControla la respuesta
◷PendienteConserva el estado
↻RecuperaciónResuelve la incertidumbre
Evidencia por escenario
IDENTIFICADORPedido ↔ OperaciónRESULTADOEsperado ↔ Obtenido
Esquema ilustrativo, no una aprobación.
Valida los casos aplicables a tu canal.
## Elige tu checklist técnico Completa los criterios específicos del canal que implementaste, además de las verificaciones generales de esta página. WooCommerce, PrestaShop y VTEX. Flujos de Flex y Modal. Aplicaciones Android e iOS. Integración de servidor a servidor. ## 01 · Valida en sandbox | Qué comprobar | Evidencia que debes conservar | | - | - | | Pago aprobado de principio a fin | Pedido, identificador de operación y estado confirmado en backend. | | Rechazo y errores controlados | Respuesta recibida, mensaje al cliente y estado correcto del pedido. | | Pendiente o expiración, cuando aplique | Transiciones de estado y tratamiento del pedido sin confirmar antes de tiempo. | | Cada medio de pago habilitado | Resultado de los escenarios que correspondan a tu comercio. | | Retorno, cancelación o interrupción del flujo | Comportamiento del canal y recuperación de un resultado incierto. | Utiliza los datos y escenarios de prueba documentados para tu integración. Si un caso no está disponible en sandbox, coordina su validación con el equipo de integraciones. ## 02 · Revisa la implementación * Configuración de autenticación y renovación de tokens según el canal. * Separación de credenciales y endpoints por entorno. * Identificadores de pedido, importe, moneda y demás parámetros válidos según la API utilizada. * URLs de retorno y notificación configuradas cuando correspondan. * HTTPS y protección de endpoints críticos; secretos fuera del frontend. * Recepción de los eventos previstos por tu integración, cuando aplique. * Validación de autenticidad según el mecanismo documentado. * Procesamiento idempotente: un evento duplicado no duplica acciones. * Manejo de eventos fuera de orden y actualización consistente del pedido. * Verificación del resultado desde backend antes de confirmar la venta. * Manejo de respuestas inesperadas, timeouts y excepciones. * Consulta o reconciliación de operaciones con resultado incierto antes de reintentarlas. * Relación trazable entre pedido y operación de Pay-me. * Registros y alertas suficientes para investigar incidencias, sin secretos ni datos sensibles de tarjeta. ## 03 · Prepara las evidencias
UN CASO, UN RESULTADO COMPROBABLE
Haz que la revisión sea clara.
Por cada escenario, reúne el entorno y la fecha, el canal y versión, el identificador del pedido y de la operación, el resultado esperado y el obtenido. Añade registros o capturas enmascarados cuando ayuden a explicar el comportamiento.
Si una prueba falla: registra el hallazgo, corrige la causa y vuelve a ejecutar el escenario antes de presentarlo como completado.
No compartas Client Secret, tokens sensibles, CVV ni números completos de tarjeta. La evidencia debe permitir revisar el caso sin exponer credenciales o datos de pago. Coordina con el equipo de integraciones los escenarios exigidos y el formato de entrega. Esta página no sustituye la revisión técnica ni representa una aprobación automática. ## 04 · Coordina la salida a producción Las pruebas en producción pueden generar cargos reales. Ejecútalas únicamente tras recibir la habilitación y credenciales correspondientes, y con el alcance acordado con el equipo de integraciones. Antes de la salida, confirma: * Configuración productiva revisada, sin datos ni credenciales de sandbox. * Flujo completo validado según el plan de pruebas controladas acordado. * Notificaciones y consistencia del pedido comprobadas, cuando apliquen. * Medios de pago habilitados revisados y monitoreo operativo preparado. * Confirmación de aprobación y pasos de activación por parte del equipo de integraciones. ## Continúa con apoyo Protección de accesos, validación y trazabilidad. Comparte tu canal y el estado de las pruebas, sin enviar secretos. # Arquitectura, red y seguridad Source: https://docs.pay-me.com/procesamiento-fisico/alignet-transit/arquitectura-y-trazabilidad Componentes, responsabilidades, direccionamiento local, configuración inicial y protección de datos. ## Arquitectura ```mermaid theme={"system"} flowchart TD CENTRAL[Sistema central] -->|HTTP local| PINPAD[Pay-me PinPAD] PINPAD --> SDK[SDK del P5L] SDK --> INTERACTION[Tarjeta o QR] SDK --> PLATFORM[Pasarela y procesador] CENTRAL -->|GET payments: consulta a pasarela| PINPAD ``` El sistema central inicia todas las llamadas hacia la IP y el puerto configurados en el Wiseasy P5L. Pay-me PinPAD muestra la pantalla de pago, coordina la tarjeta o genera el QR con su transacción pendiente, procesa el pago y devuelve la respuesta cruda del SDK en autorización. La consulta del cobro lee la pasarela; cancelación y extorno usan modelos propios con `status`. La comunicación de Pay-me PinPAD con el procesador o banco es transparente para el sistema central. ## Responsabilidades | Componente | Responsabilidades | | - | - | | Sistema central del comercio — **cliente HTTP** | Calcular el monto, generar y persistir `operationNumber`, enviar solicitudes, configurar timeouts, interpretar respuestas, recuperar operaciones pendientes y aplicar la decisión de negocio. Puede ser un POS, caja, backend o SCC. | | Pay-me PinPAD — **servidor HTTP** | Escuchar en la red local, validar el JSON, asegurar idempotencia y exclusión mutua, coordinar la interacción de pago y conservar el resultado por operación. | | Wiseasy P5L y SDK | Leer tarjeta contactless, chip o banda, capturar PIN cuando corresponda y comunicarse con la plataforma de pagos. No requieren integración directa con el sistema central. | | Procesador o banco | Aprobar o rechazar la transacción. No tiene una interfaz directa con el sistema central. | ## Requisitos de red Antes de integrar, verifica lo siguiente: * El sistema central y el Wiseasy P5L están en la misma red local y existe conectividad entre ambos. * El punto de acceso no usa **AP Isolation** o **Client Isolation** entre el sistema central y el terminal. * El puerto TCP configurado en Pay-me PinPAD es accesible desde el sistema central. El valor predeterminado es `8080`. * El terminal mantiene una IP estable, preferiblemente mediante una reserva DHCP o una dirección estática. * Las reglas de firewall permiten tráfico desde el sistema central hacia la IP y el puerto del terminal. * La aplicación Pay-me PinPAD permanece abierta y en estado listo durante la operación. La URL base sigue este formato: ```text theme={"system"} http://: ``` Ejemplo: ```text theme={"system"} http://: ``` La dirección del ejemplo es ilustrativa. Confirma la IP y el puerto de cada terminal. Si cambia la IP del Wiseasy P5L, actualiza la configuración del sistema central. ### Verificación desde el sistema central Primero verifica alcance IP y después la aplicación: ```bash theme={"system"} ping "" curl --header "Connection: close" "http://:/health" ``` Una respuesta válida de la aplicación es: ```json theme={"system"} { "status": "UP", "service": "Alignet ECR" } ``` Si `ping` responde pero `GET /health` no, revisa el puerto, el firewall y que Pay-me PinPAD esté abierta. Algunos entornos bloquean ICMP; en ese caso, usa `GET /health` como prueba definitiva de la aplicación. La [configuración inicial](/procesamiento-fisico/alignet-transit/configuracion#configurar-pay-me-pinpad) se realiza una vez por terminal e incluye la IP, el puerto, la verificación de conectividad y la inyección de llaves. Todas las respuestas usan `Connection: close`: abre una conexión por petición y no reutilices keep-alive. Usa un timeout superior a aproximadamente 90 segundos en los POST y cubre los 12–15 segundos de la consulta a la pasarela. ## Trazabilidad Por cada intento, registra únicamente información no sensible: * `operationNumber`; * `amount`, `currency` y `paymentMethod` enviados; * código HTTP recibido; * `success`, `resultCode`, `resultMessage` y `result.state` o `transaction.state` en cobro; * `status`, `authorizationCode` y `completedAt` en cancelación o extorno, cuando existan; * `transactionID` de autorización o `transactionId` y `authorizationCode` de consulta, cuando existan; * fecha y hora del envío, la respuesta y las consultas; * timeouts, pérdidas de conexión y reintentos de consulta; * solicitud de cancelación, cierre visual y consultas posteriores; * resultado de cancelación y evidencia del extorno CARD independiente, registrados por separado del cobro. La autorización puede incluir `transactionID`, `paymentMethod`, `stateReason`, `processorResponse` y `lifecycle` dentro de `result`. La consulta devuelve `transaction` y no expone `processorResponse` ni `methodDetail` crudos. Consulta el [contrato por endpoint](/procesamiento-fisico/alignet-transit/respuesta-estados-y-codigos) y sanitiza las evidencias. ## Seguridad y protección de datos * Mantén la red local controlada y restringe el puerto a los sistemas autorizados mediante segmentación y reglas de firewall. * No expongas el puerto de Pay-me PinPAD a Internet. * No incluyas nombres, documentos, placa u otros datos personales dentro de `operationNumber`. * No registres PAN completo, CVV, PIN, PIN Block, Track 1, Track 2 ni datos EMV sensibles. * Protege los logs y limita su acceso según la política de retención de tu organización. * Conserva `operationNumber` y `authorizationCode` para conciliación y comprobantes. La versión vigente documenta HTTP dentro de la red local y no define headers de autenticación para la interfaz entre el sistema central y Pay-me PinPAD. Consulta [Autenticación y control de acceso](/procesamiento-fisico/alignet-transit/autenticacion) antes de incorporar controles adicionales. # Autenticación y control de acceso Source: https://docs.pay-me.com/procesamiento-fisico/alignet-transit/autenticacion Controles de acceso aplicables a la interfaz local entre el sistema central y Pay-me PinPAD. La interfaz vigente de Pay-me Transit PinPAD opera mediante HTTP dentro de la red local. El contrato documentado **no define credenciales, tokens, certificados de cliente ni headers de autenticación** para las solicitudes entre el sistema central y Pay-me PinPAD. No envíes un header `Authorization` ni agregues un esquema de firma por iniciativa propia. Un control no previsto por Pay-me PinPAD puede hacer que la integración no sea compatible. La ausencia de autenticación a nivel de aplicación no convierte el endpoint en un servicio público. No expongas la IP ni el puerto del terminal a Internet o a redes no autorizadas. ## Controles requeridos en la red * Ubica el sistema central y el Wiseasy P5L en una red local controlada. * Restringe el puerto TCP del terminal a los orígenes autorizados mediante segmentación y reglas de firewall. * Desactiva **AP Isolation** o **Client Isolation** únicamente cuando impida la comunicación requerida entre los equipos autorizados. * Mantén una IP estable para el terminal mediante reserva DHCP o configuración estática. * Protege los logs y los datos de conciliación de acuerdo con la política de acceso y retención del comercio. * No registres PAN completo, CVV, PIN, PIN Block, pistas ni datos EMV sensibles. ## Headers de la interfaz | Header | Operación | Uso | | - | - | - | | `Content-Type: application/json` | `POST /authorize`, `POST /cancel` y `POST /reversals` | Obligatorio para enviar el cuerpo JSON. | | `Connection: close` | Todas las respuestas | Abre una conexión por petición; no reutilices keep-alive. | | `Cache-Control: no-store` | Todas las respuestas | Evita reutilizar una respuesta guardada en caché. | | `Retry-After: 2` | Todas las respuestas HTTP `202` | Espera dos segundos antes de consultar el cobro o extorno correspondiente. | | `Authorization` | Todas | No forma parte del contrato vigente. | ## Controles adicionales Si la política de seguridad del comercio exige TLS, autenticación de red, VPN, proxy o filtrado adicional, coordina el diseño con Alignet antes de implementarlo. La documentación disponible no define HTTPS ni autenticación mutua en el Wiseasy P5L y no permite asegurar que un intermediario sea compatible sin validación. Revisa los métodos, rutas, cuerpos y respuestas disponibles. # Cancelación de una autorización en curso Source: https://docs.pay-me.com/procesamiento-fisico/alignet-transit/cancelacion Cancelación validada y recuperación del cobro original ante fallos o incertidumbre. `POST /cancel` solicita cancelar una autorización activa. El servicio debe comprobar que la cancelación se ejecutó y que el resultado corresponde al `operationNumber` solicitado. Cerrar la pantalla del POS no confirma la cancelación. Si no se ejecutó o el resultado corresponde a otra operación, el servicio debe devolver un error, sin informar éxito. ## CARD `POST /authorize` inicia el cobro y el PinPAD solicita la tarjeta. Si la cancelación falla y el cobro original queda `transaction.state: "AUTORIZADO"` en una consulta `200/00`, puedes evaluar un [extorno independiente](/procesamiento-fisico/alignet-transit/extorno). Un error de `/cancel` no ejecuta automáticamente `/reversals`. ```mermaid theme={"system"} flowchart TD A[Cobro con tarjeta] --> B[Solicitar cancelación] B -->|Confirmada| C[Operación cancelada] B -->|No se confirmó| D[Consultar pasarela: transaction.state] D -->|200 y 00: AUTORIZADO| E[Evaluar extorno CARD] D -->|Otro desenlace financiero confirmado| F[Registrar desenlace] D -->|03 o 05 o 503 o 504| G[Consultar de nuevo o escalar] D -->|Sin confirmar| D ``` ## QR Al generar el QR ya existe una transacción pendiente asociada al `operationNumber`. Mostrar o escanear el código no confirma el pago. En QR, `/cancel` solo cancela o inhabilita el código. Ni `/cancel` ni refund devuelven un monto pagado; `/reversals` aplica únicamente a CARD. ```mermaid theme={"system"} flowchart TD A[Generar QR] --> B[QR pendiente] B -->|Pago aprobado| C[Pago aprobado] B --> D[Solicitar cancelación] D -->|Confirmada| E[QR cancelado] D -->|No se confirmó| F[Consultar pasarela: transaction.state] F -->|200 y 00: AUTORIZADO| C F -->|Otro desenlace financiero confirmado| G[Registrar desenlace] F -->|03 o 05 o 503 o 504| H[Consultar de nuevo o escalar] F -->|Sin confirmar| F ``` Si recuperas un QR `transaction.state: "AUTORIZADO"` en una consulta `200/00`, conserva el pago aprobado. No lo marques como cancelado, devuelto ni extornado; registra la discrepancia para revisión. ## Solicitud Envía al mismo PinPAD de la autorización original: ```http theme={"system"} POST /cancel Content-Type: application/json Connection: close ``` ```json theme={"system"} { "operationNumber": "44992528" } ``` | Campo | Tipo | Obligatorio | Uso | | - | - | - | - | | `operationNumber` | String | Sí | Referencia original: 1–64 caracteres sin espacios (`^\S{1,64}$`). | No generes otra referencia ni envíes monto, moneda, método o datos de tarjeta. ```bash theme={"system"} curl --header "Connection: close" -i --request POST "http://:/cancel" \ --header "Content-Type: application/json" \ --max-time 110 \ --data '{"operationNumber":"44992528"}' ``` ## Resultados por método Estas reglas aplican a CARD y QR. Evalúa el estado, el código y la validación del servicio; HTTP `200` por sí solo no confirma éxito. | HTTP | `status` y `resultCode` | Acción | | - | - | - | | `200` | `CANCELLED` con `00`, `16` o `17` | Cancelación confirmada o éxito equivalente, validado por el servicio. No exige otra consulta para reconocerla. | | `200` | `DENIED` con `14`, `15`, `18`, `19`, `20`, `01`, `03` u otro código SDK | Cancelación rechazada o abandonada. Consulta el cobro original; no marques cancelación exitosa. | | `202` | `PENDING` con `P22` | Resultado todavía no confirmado. Consulta el cobro original; este GET no informa el desenlace de `/cancel`. | | `404` | `ERROR/NOT_FOUND` | Venta inexistente o resultado SDK `05/07`. Verifica referencia y terminal. | | `409` | `ERROR/CANCELLATION_IN_PROGRESS` | Ya hay una cancelación de esa referencia en curso. No envíes otra. | | `503` | `ERROR/POS_NOT_AVAILABLE` | Restablece SDK o pantalla disponible; consulta el cobro antes de decidir otro envío. | | `400` | `ERROR/BAD_REQUEST` | Corrige el JSON. | Reenviar una cancelación ya finalizada devuelve el resultado guardado; una segunda cancelación en curso devuelve `409 CANCELLATION_IN_PROGRESS`. Ejemplos de campos de decisión, sin representar pruebas ejecutadas: ```json Abandono con 14 theme={"system"} { "operationNumber": "44992528", "status": "DENIED", "resultCode": "14" } ``` ```json Cancelación confirmada con 16 theme={"system"} { "operationNumber": "44992528", "status": "CANCELLED", "resultCode": "16" } ``` `DENIED/14` indica abandono por cierre de autorización en curso; `15` indica abandono con intento (QR cancelado). No confirman cancelación aprobada ni son rechazo típico de tarjeta. Decide con estado y código. No normalices `16` o `17` a `00`. ## Verificar el resultado final No existe un endpoint de consulta de cancelación. La respuesta de `POST /cancel` informa el resultado de esa solicitud. Ante fallo, timeout o incertidumbre, `GET /payments/{operationNumber}` consulta **la pasarela** y devuelve `success`, `resultCode`, `resultMessage` y `transaction`, sin `status` propio. `00` significa encontrada: lee `transaction.state`. Este GET no devuelve `202`. Aplica el [contrato de consulta](/procesamiento-fisico/alignet-transit/respuesta-estados-y-codigos#consulta-de-estado): | Estado del cobro | Acción | | - | - | | CARD: `transaction.state: "AUTORIZADO"` en una consulta `200/00` | Tras una cancelación fallida, evalúa `POST /reversals` con la referencia original, sin duplicar extornos. | | QR: `transaction.state: "AUTORIZADO"` en una consulta `200/00` | Conserva el pago aprobado, sin refund ni reversa. | | `200/00` con `transaction.state: "CANCELADO"` | La pasarela registra el cobro cancelado; no es una consulta del desenlace de `/cancel`. | | `200/00` con otro `transaction.state` | Interpreta el literal financiero del SDK; la guía no enumera todos los estados. | | `200/03`, `404/05`, `503/P04` o `POS_NOT_AVAILABLE`, `504/SEARCH_TIMEOUT` | Cobro no verificado. Conserva la referencia, vuelve a consultar o escala; no deduzcas rechazo ni habilites otra venta. | En los ciclos del gráfico, repite únicamente el GET. No reenvíes `/cancel` ni generes otra venta mientras no conozcas el resultado del cobro. Un `202 WAITING_RESULT` tardío de `/authorize` no sustituye un resultado confirmado. ## Fallos de cancelación | Situación | Tratamiento | | - | - | | Cancelación no ejecutada o resultado de otra operación | El servicio devuelve un error; no puede informar cancelación exitosa. | | Timeout, desconexión o fallo del backend | Muestra **Cancelación no confirmada** y recupera el cobro original. Si falta conexión, restablécela primero. | | Cancelación ejecutada y resultado validado | Reconoce la respuesta de éxito de `/cancel`. El cierre visual por sí solo no acredita este resultado. | La matriz no especifica la respuesta cuando la cancelación no se ejecuta o el resultado corresponde a otra operación. No asignes a ese caso un HTTP, código ni cuerpo JSON sin confirmación de desarrollo. ## Manejo de 202 y pérdida de conexión Todas las respuestas incluyen `Cache-Control: no-store`. HTTP `202` añade `Retry-After: 2`: espera dos segundos antes de consultar el cobro original. Una desconexión no garantiza recepción de `/cancel` ni cierre de pantalla. # Configuración por ambiente Source: https://docs.pay-me.com/procesamiento-fisico/alignet-transit/configuracion Configura Pay-me PinPAD y registra la asociación entre el sistema central y cada terminal. Configura cada Wiseasy P5L antes de probar los endpoints. No copies las direcciones de los ejemplos en un ambiente real. ## Configurar Pay-me PinPAD Al iniciar Pay-me PinPAD por primera vez, el operador verá un asistente con tres etapas: **Bienvenida**, **Conexión** y **Verificación**. La dirección `192.168.20.50` mostrada en la imagen es ilustrativa. Ingresa la IP asignada al Wiseasy P5L. El puerto predeterminado es `8080`; confirma el valor de cada terminal. En **Bienvenida**, selecciona **Empezar**. Ingresa la **Dirección IP** del propio Wiseasy P5L y el **Puerto** en el que escuchará Pay-me PinPAD. El sistema central usará ambos valores para construir `http://:`. La pantalla final valida **Conexión disponible** e **Inyección de llaves**. Envía un `GET /health` real desde el sistema central. Pay-me PinPAD verifica las llaves de seguridad en el terminal. Cuando ambos indicadores estén en verde, selecciona **Continuar**. Pay-me PinPAD mostrará **Listo para el siguiente vehículo** cuando termine la configuración. Este es el texto actual de la interfaz del producto; no obliga a que el sistema integrador sea un SCC. El sistema central no inyecta llaves ni inicializa directamente el SDK de pagos. ## Configuración por terminal Registra para cada Wiseasy P5L: | Parámetro | Ejemplo | Responsable | | - | - | - | | Identificador interno del terminal | `P5L-PUNTO-03` | Comercio / Alignet | | Punto de atención asociado | `PUNTO-03` | Comercio o integrador | | Dirección IP | `192.168.68.121` | Administración de red | | Puerto TCP | `8080` | Alignet / administración de red | | Dirección MAC, si se reserva DHCP | Valor del terminal | Administración de red | | Ambiente | Integración, UAT o producción | Alignet / comercio o integrador | | Versión de Pay-me PinPAD | Versión entregada | Alignet | No copies la IP de ejemplo en un ambiente real. ## Ambientes | Ambiente | Objetivo | Salida esperada | | - | - | - | | Integración | Validar red, contrato JSON y control de errores. | Cliente compatible con los endpoints y códigos HTTP. | | UAT | Validar el flujo físico y la decisión de negocio. | Evidencias aprobadas de escenarios normales y de recuperación. | | Producción | Procesar cobros reales. | Parámetros definitivos registrados, monitoreo y soporte habilitados. | ## Control de cambios Registra la versión de Pay-me PinPAD y la fecha de vigencia junto con la configuración de cada terminal. Un cambio en rutas, campos, tipos, estados, timeouts o semántica requiere revisar el cliente antes del despliegue. Confirma timeouts, políticas de consulta, códigos y habilitaciones antes de producción. Implementa únicamente las rutas del contrato vigente. # Datos por validar Source: https://docs.pay-me.com/procesamiento-fisico/alignet-transit/datos-por-validar Decisiones abiertas y datos que deben confirmarse con Alignet antes de habilitar producción. Esta página reúne la información ambigua, incompleta o dependiente de cada implementación. Los valores de referencia sirven para desarrollo y pruebas; no los conviertas en reglas de producción hasta recibir confirmación. Estos pendientes no cambian los endpoints ni los contratos documentados. Si una definición futura modifica rutas, campos, tipos o semántica, trata el cambio como una nueva versión de integración. ## Parámetros operativos | Punto | Referencia disponible | Validación requerida | | - | - | - | | Espera interna de Pay-me PinPAD | Aproximadamente `90` segundos para los POST, según la guía 1.3.25. | Valor definitivo por ambiente. | | Timeout del cliente HTTP | Al menos `100–110` segundos con la espera de referencia. | Valor definitivo, siempre superior a la espera del terminal. | | Frecuencia de consulta | HTTP `202` incluye `Retry-After: 2`. | Backoff y tiempo máximo de consulta por ambiente. | | Operación no resuelta | No iniciar otro cobro ante consulta fallida o incierta (`200/03`, `404/05`, `503` o `504`). | Procedimiento de inmovilización, escalamiento y decisión de negocio. | | Reinicio durante un extorno | Puede producir `UNKNOWN`. | Confirmar si el procesador recibió la reversa y cómo conciliarla. | | Cancelación con resultado incierto | `POST /cancel` puede responder `202` con `Retry-After`, o perderse la conexión antes de recibir el resultado. | Consultar el cobro original con `GET /payments/{operationNumber}`; no existe consulta de cancelación. Acordar revisión si el cobro continúa sin resolver. | ## Contrato y habilitación | Punto | Referencia disponible | Validación requerida | | - | - | - | | `operationNumber` | String de 1–64 caracteres sin espacios; la ruta GET no admite `/` adicional. | Acordar el formato del comercio. La guía no define la consulta por ruta de referencias que contengan `/`. | | Referencia reutilizada con otro body | No está documentado. | Comportamiento de Pay-me PinPAD; hasta entonces, reenvía exactamente el mismo payload. | | `additionalFields` | Objeto opcional; todos sus valores son String. | El comercio define las claves que necesita enviar como información complementaria. | | Monedas | PEN usa `currency: "604"`. | Otras monedas habilitadas para el comercio y el ambiente. | | Métodos de pago | El contrato admite `CARD` y `QR`, uno por solicitud. | Métodos efectivamente habilitados para el comercio y el ambiente. | | Códigos financieros | Autorización: `success: true`, `00` y `result.state: "AUTORIZADO"`. Consulta: `00` indica encontrada; leer `transaction.state`. | La guía no enumera todos los estados financieros de la pasarela; validar literales por método. `00` aislado no confirma un cobro. | | Cancelación validada | `CANCELLED` con `00`, `16` o `17`; `DENIED/14` no confirma éxito. | Verificar que la versión instalada aplique el [mapeo vigente](/procesamiento-fisico/alignet-transit/respuesta-estados-y-codigos#c%C3%B3digos-confirmados). | | Validación fallida de `/cancel` | Si no se ejecutó o el resultado pertenece a otra operación, devolver error, sin informar éxito. | La matriz recibida no especifica HTTP, código ni cuerpo de este error de validación; desarrollo debe definirlos. | | SDK `07` en consulta del cobro | La tabla general de la guía menciona `404`; el mapeo específico de `/payments` reporta otros códigos SDK con `200`. | Aplicar el mapeo específico y confirmar la discrepancia en el entorno. Cancelación/extorno usan `404 ERROR/NOT_FOUND` ante `05/07`. | | Recepción y corte visual | El PinPAD corta el flujo visual cuando recibe y procesa la solicitud. | Validar fallos de conexión sin presumir recepción o cierre; distinguirlos de fallos internos tras la recepción. | | Cancelación QR | Solo inhabilita el código; no devuelve pagos. | Evidencia de cancelación ejecutada y correspondencia con la referencia solicitada. | | `tollData` | Datos de peaje con valores String; se fusionan con `additionalFields` y prevalece `tollData`. | Acordar claves y convenciones por comercio, sin convertirlas en restricciones del servidor. | ## Extornos | Punto | Referencia disponible | Validación requerida | | - | - | - | | Extorno tras cancelación fallida | Si el cobro CARD se encuentra con `transaction.state: "AUTORIZADO"`, se evalúa `POST /reversals` como acción independiente. | Evidencia del extorno y conciliación cuando no se confirma éxito. | | Discrepancia de cancelación QR | Solo se cancela o inhabilita el código. Ni `/cancel` ni refund devuelven pagos QR; un QR encontrado con `transaction.state: "AUTORIZADO"` se conserva como aprobado. | Definir evidencias, responsables y revisión de discrepancias; no generar refund ni reversa. | | Presentación de tarjeta | El extorno explícito puede requerir interacción con el PinPAD. | Obligatoriedad por versión, uso de tarjeta original y pasos reales. | | Prevención de duplicados | No repetir `REVERSED`, `NOT_FOUND` ni un extorno en curso. Tras `DENIED`, `UNKNOWN` o `ERROR` finales, un nuevo POST puede ejecutar otro intento; no es un reintento automático. | Evidencia y consulta para descartar ambos antes de una reversa adicional. | Confirma también: * la ventana máxima para solicitar un extorno; * el tratamiento de ventas cerradas o liquidadas; * cuándo se refleja la reversa para el tarjetahabiente y cuál es su efecto contable; * la semántica y el procedimiento de conciliación de `UNKNOWN` después de un reinicio; * los códigos del procesador que permiten reintentar una reversa. ## Infraestructura y soporte Completa por ambiente: * la IP, el puerto y la asociación entre sistema central y Wiseasy P5L; * la versión aprobada de Pay-me PinPAD; * los contactos, horarios, severidades y procedimiento de soporte; * los responsables de decidir qué hacer cuando el resultado aún no está confirmado; * cualquier requisito adicional de seguridad de red. ## Registro de decisión Por cada punto, registra responsable, definición aprobada, ambiente, fecha de vigencia y evidencia. Conserva este registro junto con la versión de Pay-me PinPAD certificada. Convierte las definiciones aprobadas en criterios verificables antes de habilitar cobros reales. # Ejemplos de integración Source: https://docs.pay-me.com/procesamiento-fisico/alignet-transit/ejemplos-de-integracion Ejemplos en cURL, Java, C#, Python y Node.js para consumir Pay-me PinPAD. El sistema central del comercio actúa como **cliente HTTP**. La aplicación Pay-me PinPAD instalada en el Wiseasy P5L actúa como **servidor HTTP** sobre la red local. Reemplaza `` y `` por la configuración de tu terminal. Estos ejemplos ilustran el contrato HTTP; no son evidencia de pruebas ejecutadas. Consulta la [referencia de endpoints](/procesamiento-fisico/alignet-transit/referencia-de-endpoints) y el contrato de cada operación antes de adaptar estos ejemplos. ## cURL ### Disponibilidad ```bash theme={"system"} curl --header "Connection: close" "http://:/health" ``` ### Autorización ```bash theme={"system"} curl --header "Connection: close" --request POST "http://:/authorize" \ --header "Content-Type: application/json" \ --max-time 110 \ --data '{ "operationNumber": "44992528", "amount": "100", "currency": "604", "paymentMethod": "QR", "tollData": { "plate": "ABC-123", "tollPointId": "PEAJE-01", "laneId": "VIA-03" }, "additionalFields": {} }' ``` Los datos estructurados del peaje van en `tollData`. Se fusionan con `additionalFields`; ante claves coincidentes prevalece `tollData`. Usa `additionalFields` para información complementaria. Para CARD cambia únicamente `paymentMethod` a `"CARD"` en una operación nueva y resuelta de forma independiente; el PinPAD solicitará la tarjeta. En QR, generar el código ya crea la transacción pendiente. ### Consulta del cobro ```bash theme={"system"} curl --max-time 20 --header "Connection: close" -i "http://:/payments/44992528" ``` Usa `-i` para comprobar `Connection: close` y `Cache-Control: no-store`. Solo los endpoints que devuelven HTTP `202` añaden `Retry-After: 2`; este GET consulta la pasarela y no devuelve `202`. ### Solicitar cancelación ```bash theme={"system"} curl --header "Connection: close" -i --request POST "http://:/cancel" \ --header "Content-Type: application/json" \ --max-time 110 \ --data '{"operationNumber":"44992528"}' ``` La respuesta informa el resultado de la solicitud de cancelación. Usa el GET del cobro únicamente para recuperarlo ante fallo, timeout o incertidumbre; no existe un GET de cancelación. | Caso del ejemplo | Resultado esperado | Acción | | - | - | - | | Cancelación ejecutada y validada | HTTP `200`, `CANCELLED` con `00`, `16` o `17`. | Reconocer la cancelación sin exigir otra consulta. | | Cancelación rechazada | HTTP `200`, `DENIED`, incluido el código `14`. | No registrar cancelación exitosa; consultar el cobro original. | | Cancelación no ejecutada | Respuesta de error, sin valores específicos definidos. | No registrar éxito; consultar el cobro original. | | Resultado de otra operación | El servicio devuelve un error de validación. | Conservar la referencia solicitada y consultar su cobro. | | Timeout o resultado incierto | Sin cancelación confirmada; `PENDING` con `P22` sigue pendiente. | Consultar el cobro original; en HTTP `202`, esperar `Retry-After: 2`. | | Cancelación fallida y cobro CARD `transaction.state: "AUTORIZADO"` en una consulta `200/00` | El cobro original está aprobado. | Evaluar `POST /reversals` con la referencia original; consultar el extorno cuando corresponda. | En `/cancel`, `DENIED/14` indica abandono por cierre de autorización en curso; `15` indica abandono con intento (QR cancelado). Ninguno confirma cancelación aprobada ni rechazo típico de tarjeta. `CANCELLED` con `16` o `17` es éxito equivalente, validado por el servicio. Si el cobro QR aparece `transaction.state: "AUTORIZADO"` en una consulta `200/00`, conserva el pago aprobado y registra la discrepancia. Ni `/cancel` ni refund devuelven pagos QR; no uses `/reversals` para QR. ## Java 11 o posterior ```java theme={"system"} import java.net.URI; import java.net.URLEncoder; import java.nio.charset.StandardCharsets; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.time.Duration; public final class PinpadClient { private final String baseUrl; public PinpadClient(String baseUrl) { this.baseUrl = baseUrl; } // Recibe JSON serializado con la biblioteca de tu aplicación. public HttpResponse authorize(String json) throws Exception { HttpRequest request = HttpRequest.newBuilder() .uri(URI.create(baseUrl + "/authorize")) .header("Content-Type", "application/json") .timeout(Duration.ofSeconds(110)) .POST(HttpRequest.BodyPublishers.ofString(json)) .build(); return HttpClient.newBuilder().version(HttpClient.Version.HTTP_1_1) .build().send(request, HttpResponse.BodyHandlers.ofString()); } public HttpResponse query(String operationNumber) throws Exception { HttpRequest request = HttpRequest.newBuilder() .uri(URI.create(baseUrl + "/payments/" + URLEncoder.encode(operationNumber, StandardCharsets.UTF_8))) .timeout(Duration.ofSeconds(20)) .GET() .build(); return HttpClient.newBuilder().version(HttpClient.Version.HTTP_1_1) .build().send(request, HttpResponse.BodyHandlers.ofString()); } } ``` En Java, cada envío crea su cliente y usa HTTP/1.1; el servidor responde `Connection: close`. No configures reutilización de conexiones. ## C# con .NET ```csharp theme={"system"} using System.Net.Http.Json; public sealed class PinpadClient { private readonly HttpClient _http; public PinpadClient(string baseUrl) { _http = new HttpClient { BaseAddress = new Uri(baseUrl), Timeout = TimeSpan.FromSeconds(110) }; _http.DefaultRequestHeaders.ConnectionClose = true; } public async Task<(int StatusCode, string Body)> AuthorizeAsync( string operationNumber, string amount, string currency, string paymentMethod) { var payload = new { operationNumber, amount, currency, paymentMethod }; using var response = await _http.PostAsJsonAsync("/authorize", payload); return ((int)response.StatusCode, await response.Content.ReadAsStringAsync()); } public async Task<(int StatusCode, string Body)> QueryAsync(string operationNumber) { using var timeout = new CancellationTokenSource(TimeSpan.FromSeconds(20)); using var response = await _http.GetAsync( $"/payments/{Uri.EscapeDataString(operationNumber)}", timeout.Token); return ((int)response.StatusCode, await response.Content.ReadAsStringAsync()); } } ``` ## Python con requests ```python theme={"system"} import requests from urllib.parse import quote BASE_URL = "http://:" def authorize(operation_number, amount, currency, payment_method): payload = { "operationNumber": operation_number, "amount": amount, "currency": currency, "paymentMethod": payment_method, } response = requests.post( f"{BASE_URL}/authorize", json=payload, headers={"Connection": "close"}, timeout=110, ) return response.status_code, response.json() def query_status(operation_number): response = requests.get( f"{BASE_URL}/payments/{quote(operation_number, safe='')}", headers={"Connection": "close"}, timeout=20, ) return response.status_code, response.json() ``` ## Node.js 18 o posterior ```javascript theme={"system"} const BASE_URL = "http://:"; async function authorize(operationNumber, amount, currency, paymentMethod) { const controller = new AbortController(); const timeout = setTimeout(() => controller.abort(), 110_000); try { const response = await fetch(`${BASE_URL}/authorize`, { method: "POST", headers: { "Content-Type": "application/json", "Connection": "close" }, body: JSON.stringify({ operationNumber, amount, currency, paymentMethod }), signal: controller.signal, }); return { statusCode: response.status, body: await response.json(), retryAfter: response.headers.get("retry-after"), }; } finally { clearTimeout(timeout); } } async function queryStatus(operationNumber) { const controller = new AbortController(); const timeout = setTimeout(() => controller.abort(), 20_000); try { const response = await fetch( `${BASE_URL}/payments/${encodeURIComponent(operationNumber)}`, { headers: { "Connection": "close" }, signal: controller.signal }, ); return { statusCode: response.status, body: await response.json() }; } finally { clearTimeout(timeout); } } ``` ## Reglas para cualquier lenguaje * Persiste `operationNumber` antes del `POST`. * Envía `operationNumber` como String de 1–64 caracteres sin espacios; evita `/` para consultarlo por ruta. `amount` acepta entero o String numérico positivo. Moneda y método son opcionales (`604` y `CARD`); el método no distingue mayúsculas. * Abre una conexión por petición, sin keep-alive; todas las respuestas usan `Connection: close`. * Configura 110 segundos para los POST, por encima de la espera aproximada de 90 segundos. Cubre los 12–15 segundos de consulta del cobro; los ejemplos usan 20 segundos. * Conserva por separado el código HTTP y el JSON. * Confirma autorización con HTTP `200`, `success: true`, `resultCode: "00"` y `result.state: "AUTORIZADO"`. En consulta `200/00`, interpreta `transaction.state`: `00` solo significa encontrada. * Reconoce cancelación validada con `CANCELLED` y `00`, `16` o `17`. `DENIED/14` y HTTP `200` aislado no confirman éxito. * Ante cancelación fallida o incierta, consulta el cobro original. Una consulta fallida o incierta (`200/03`, `404/05`, `503`, `504`) no permite otro cobro ni confirma rechazo. * Una falla de conexión no garantiza recepción de `/cancel` ni cierre de pantalla. * Los ciclos repiten solo el GET correspondiente; no reenvían `/cancel` ni generan otra venta. * Ante timeout, desconexión o fallo del backend, muestra **Cancelación no confirmada** y consulta el estado. * No repitas un extorno exitoso o en curso. Tras `DENIED`, `UNKNOWN` o `ERROR` finales, un nuevo POST puede ejecutar otro intento; consulta y decide antes, sin reintento automático ante incertidumbre. * No sustituyas un resultado confirmado por un `202 WAITING_RESULT` tardío de `/authorize`. * Autorización `202` usa `WAITING_RESULT` y `result: null`. La consulta del cobro no tiene `status` propio ni devuelve `202`. Extorno `UNKNOWN` devuelve `502` y es final localmente; revisa si se ejecutó sin asumir éxito. * El cuerpo compacto de extorno `UNKNOWN` utiliza `message`. * Conserva los códigos SDK; en cancelación y extorno, `P22` se clasifica como `PENDING`. No extrapoles el modelo propio a la autorización o consulta del cobro. * Respeta `Retry-After: 2` en HTTP `202`. * Serializa los cobros dirigidos al mismo terminal. * No registres datos sensibles de tarjeta. La solicitud y consulta de extorno están en [Extorno de una venta CARD aprobada](/procesamiento-fisico/alignet-transit/extorno). Los ejemplos se concentran en el contrato HTTP. En producción, serializa JSON con la biblioteca estándar del lenguaje, valida las respuestas y persiste el estado antes de ejecutar una acción de negocio irreversible. # Extorno de una venta CARD aprobada Source: https://docs.pay-me.com/procesamiento-fisico/alignet-transit/extorno Extorno explícito CARD y consulta de resultados; QR no admite extornos ni devoluciones. `POST /reversals` aplica **solo a CARD** y solicita el extorno total de una venta aprobada. Conserva el `operationNumber` original. ## Cancelación y extorno | Flujo | Uso | Verificación | | - | - | - | | `POST /cancel` | Solicitar cancelar una autorización activa. | Su respuesta informa el resultado de la cancelación. Ante fallo o incertidumbre, consulta el cobro original. | | `POST /reversals` | Solicitar un extorno independiente de una venta CARD aprobada. | `GET /reversals/{operationNumber}` cuando el resultado no esté confirmado. | En **QR**, únicamente cancelas o inhabilitas el código generado. Ni `/cancel` ni refund devuelven un monto pagado; `/reversals` no aplica. Si aparece `transaction.state: "AUTORIZADO"` en una consulta `200/00` después de solicitar cancelación, conserva el pago aprobado y registra la discrepancia para revisión. Una cancelación fallida permite evaluar el extorno cuando `GET /payments/{operationNumber}` confirma el cobro CARD como `transaction.state: "AUTORIZADO"` en una consulta `200/00`. Usa el `operationNumber` de esa venta; el error de cancelación no genera un extorno automático. ## Requisitos por método | Método | Requisito | | - | - | | CARD | Venta encontrada con `transaction.state: "AUTORIZADO"` y cobro vigente. Presenta la tarjeta cuando la solicite el PinPAD. | | QR | No aplica este flujo: solo puedes cancelar o inhabilitar el código, sin devolver un monto pagado. | Antes del POST, verifica que no exista un extorno completado o en curso. No dupliques la solicitud mientras falte resolución. ## Solicitud Envía al mismo host y puerto de la autorización: ```http theme={"system"} POST /reversals Content-Type: application/json Connection: close ``` ```json theme={"system"} { "operationNumber": "44992528" } ``` | Campo | Tipo | Obligatorio | Uso | | - | - | - | - | | `operationNumber` | String | Sí | Referencia original aceptada en la autorización; consulta [Parámetros](/procesamiento-fisico/alignet-transit/parametros-de-envio). | No envíes monto, moneda, método ni datos de tarjeta. El extorno es total. ```bash theme={"system"} curl --header "Connection: close" --request POST "http://:/reversals" \ --header "Content-Type: application/json" \ --max-time 110 \ --data '{"operationNumber":"44992528"}' ``` Si el resultado no está confirmado o se pierde la respuesta, consulta el extorno: ```bash theme={"system"} curl --header "Connection: close" -i "http://:/reversals/44992528" ``` Todas las respuestas incluyen `Connection: close` y `Cache-Control: no-store`. Abre una conexión por petición. HTTP `202` añade `Retry-After: 2`; espera dos segundos antes de consultar el extorno. ## Respuestas del POST | HTTP | Resultado documentado | Acción | | - | - | - | | `200` | `REVERSED` con `00`, `16` o `17` | Registrar extorno confirmado o éxito equivalente. | | `200` | `DENIED` con `14`, `15`, `18`, `19`, `20`, `01`, `03` u otro código SDK | No registrar éxito; conservar código y mensaje. No reintentar automáticamente. | | `202` | `SEARCHING`, `PROCESSING` o `PENDING`; códigos `SEARCHING`, `WAITING_RESULT` o `P22` | Respetar `Retry-After: 2` y consultar; no duplicar. | | `400` | `BAD_REQUEST` | Corregir el cuerpo. No es un rechazo financiero. | | `404` | `NOT_FOUND` | Verificar referencia y terminal; no confirma ausencia de cobro. | | `409` | `POS_BUSY` | Esperar a que termine la operación activa antes de reintentar la solicitud no aceptada. | | `502` | `UNKNOWN`, cuerpo compacto con `message`; sin `resultCode` | Búsqueda ambigua o control de tiempo agotado. Revisar con Alignet; no registrar éxito ni reenviar automáticamente. | | `503` | `POS_NOT_AVAILABLE` | Restablecer disponibilidad y consultar antes de decidir otro envío. | La forma normal conserva `operationNumber`, `status`, `resultCode`, `resultMessage`, `authorizationCode` y `completedAt` (fecha ISO 8601 UTC o `null` si no aplica). Ejemplo de extorno aprobado; no representa una prueba ejecutada: ```json theme={"system"} { "operationNumber": "44992528", "status": "REVERSED", "resultCode": "00", "resultMessage": "Extorno aprobado", "authorizationCode": "123456", "completedAt": "2026-08-27T20:30:00Z" } ``` El código aislado no basta: el éxito exige `REVERSED` con `00`, `16` o `17`. Conserva los códigos SDK sin normalizaciones adicionales. El cuerpo compacto de `UNKNOWN` utiliza `message`, no `resultMessage`. Forma compacta de HTTP `502` (esquema, no evidencia de prueba): ```json theme={"system"} { "operationNumber": "string", "status": "UNKNOWN", "message": "string" } ``` ## Consulta del extorno explícito | HTTP de `GET /reversals/{operationNumber}` | Significado | Acción | | - | - | - | | `200` | `REVERSED`, `DENIED` o `ERROR` guardado. | Reconocer éxito solo con `REVERSED` y `00`, `16` o `17`. | | `202` | Extorno en curso. | Respetar `Retry-After: 2` y continuar consultando. | | `404` | No existe solicitud registrada o la venta original no fue encontrada. | Verificar terminal y referencia; no deducir un resultado financiero. | | `400` | `ERROR/BAD_REQUEST`: segmento vacío o inválido. | Corregir la referencia en la ruta. | | `502` | `UNKNOWN`: la solicitud terminó con error. | Revisar si se ejecutó el extorno con Alignet; no registrar éxito. | `GET /reversals/{operationNumber}` consulta el estado **local** guardado por la app. El cobro y el extorno son resultados independientes. Encontrar `transaction.state: "AUTORIZADO"` en `GET /payments/{operationNumber}` no confirma ni descarta el extorno; consulta este último en `/reversals/{operationNumber}`. ## Estados del extorno | Estado | Interpretación | | - | - | | `SEARCHING` | Se está buscando la venta original. Sigue consultando el extorno. | | `PROCESSING`, `PENDING` | Extorno en proceso o espera HTTP agotada; continuar consultando. | | `REVERSED` con `00`, `16` o `17` | Extorno confirmado o éxito equivalente. | | `DENIED` | Solicitud denegada; no registres extorno exitoso. | | `UNKNOWN` | La solicitud terminó con HTTP `502`, pero no se sabe si se ejecutó el extorno. Revisa el caso con Alignet. | | `ERROR` | Evaluar HTTP, código y mensaje; no equivale a extorno. | `DENIED`, `ERROR` y `UNKNOWN` no confirman un extorno exitoso. `UNKNOWN` no debe tratarse como un pendiente de cobro con HTTP `202`. ## Recuperación e idempotencia * Ante timeout o desconexión, consulta la misma referencia: el timeout no determina el resultado financiero. * Si el mismo extorno está `SEARCHING`, `PROCESSING` o `PENDING`, el POST devuelve `202` sin iniciar otro. * Si ya fue `REVERSED`, devuelve `200` con el resultado guardado sin repetir el extorno; si fue `NOT_FOUND`, devuelve `404` sin otro intento. * Tras un resultado final `DENIED`, `UNKNOWN` o `ERROR`, un nuevo `POST /reversals` con la misma referencia **puede ejecutar otro intento real**. Esta capacidad no autoriza reintentos automáticos ante incertidumbre: consulta, revisa el resultado financiero y decide antes de reenviar. * Otra referencia activa devuelve `409 POS_BUSY`. Serializa operaciones por terminal. * No reenvíes en paralelo ni cambies el cuerpo. Consulta antes de cualquier reenvío permitido. * No sustituyas un resultado confirmado por un `PENDING` tardío ni inicies otra venta mientras no conozcas el resultado anterior. # Habilitación y soporte Source: https://docs.pay-me.com/procesamiento-fisico/alignet-transit/habilitacion-y-soporte Información que el comercio, el integrador y Alignet deben intercambiar para pruebas y producción. Completa esta información antes de ejecutar las pruebas conjuntas. Evita incluir credenciales o datos sensibles en documentos de coordinación sin protección. ## Información del comercio o integrador ### Sistema central y despliegue * nombre y versión del componente que realizará las llamadas HTTP; * sistema operativo, runtime y biblioteca HTTP; * relación entre instancias del sistema central, puntos de atención y terminales; * estrategia de persistencia de operaciones abiertas; * mecanismo de serialización de cobros por terminal; * procedimiento de recuperación después de un reinicio. ### Red * subred y dirección IP del sistema central; * reglas de firewall aplicables; * confirmación de que AP/Client Isolation está desactivado; * reserva DHCP o mecanismo de IP estática del Wiseasy P5L; * contacto responsable de red durante las pruebas. ### Operación * formato utilizado para `operationNumber`, según [Parámetros](/procesamiento-fisico/alignet-transit/parametros-de-envio), de 1–64 caracteres sin espacios; * regla que garantiza unicidad por operación real; * montos y referencias de prueba; * datos estructurados del peaje en `tollData` y claves complementarias en `additionalFields`, si aplica; * decisión de negocio según `result.state` en autorización, `transaction.state` en consulta a pasarela y `status` en cancelación/extorno; * formato de comprobante y datos de conciliación. ### Observabilidad y soporte * evidencia técnica disponible en el sistema central; * retención y protección de logs; * responsables de desarrollo, QA, redes y operación; * procedimiento para inmovilizar una operación incierta y escalarla. ## Información de Alignet Alignet debe confirmar antes de la salida a producción: * Wiseasy P5L y versión de Pay-me PinPAD asignados; * IP y puerto configurados para cada terminal; * espera interna definitiva de Pay-me PinPAD; * recomendación definitiva de timeout del sistema central; * intervalo, backoff y límite de consulta; * catálogo aplicable de códigos por método y operación; * versión instalada conforme al mapeo de códigos de cobro, cancelación y extorno; * HTTP, código y cuerpo del error cuando la cancelación no se ejecutó o corresponde a otra operación; * evidencia y revisión de discrepancias cuando QR sigue aprobado tras solicitar cancelación, sin refund ni reversa; * presentación de tarjeta en el extorno explícito CARD; * monedas y medios de pago habilitados; * claves de `additionalFields` definidas por el comercio y su finalidad; * contactos, horarios y procedimiento de soporte. El registro completo, incluida la semántica pendiente de extornos y referencias reutilizadas, está en [Datos por validar](/procesamiento-fisico/alignet-transit/datos-por-validar). ## Ficha por terminal | Campo | Valor | | - | - | | Ambiente | Por completar | | Punto de atención | Por completar | | Identificador del Wiseasy P5L | Por completar | | Versión de Pay-me PinPAD | Por completar | | IP | Por completar | | Puerto | `8080` por defecto; confirmar | | Sistema central autorizado | Por completar | | Fecha de `GET /health` exitoso | Por completar | | Timeout del sistema central | Por completar | | Política de consulta | Por completar | | Contacto de soporte | Por completar | ## Evidencia mínima por caso * identificador y descripción del caso; * fecha, hora y ambiente; * terminal y sistema central utilizados; * `operationNumber` y método CARD o QR; * evidencia de recepción de `/cancel`, fallo de conexión o fallo interno, y cierre visual observado; * resultado de `/cancel`, consultas del cobro ante fallo o incertidumbre y resultado del extorno CARD independiente, si se solicitó; * mensaje **Cancelación no confirmada** ante timeout, desconexión o fallo del backend; * solicitud y respuesta sanitizadas; * código HTTP, `Connection: close`, `Cache-Control: no-store` y `Retry-After: 2` en HTTP `202`; * campos del contrato correspondiente a cada endpoint; en extorno `502 UNKNOWN`, solo `operationNumber`, `status` y `message`; * tiempos de inicio, respuesta y consultas; * resultado esperado, resultado observado y conformidad. No incluyas PAN completo, CVV, PIN, PIN Block, pistas ni datos EMV sensibles. ## Entregables de habilitación Asociación entre sistema central, punto de atención y Wiseasy P5L, IP, puerto, versión y timeouts. Acción del sistema central para cada código HTTP y estado transaccional. Casos normales, errores, concurrencia, timeout y recuperación. Contactos, severidades, datos de diagnóstico y escalamiento. # Operación y recuperación Source: https://docs.pay-me.com/procesamiento-fisico/alignet-transit/operacion-y-recuperacion Flujo síncrono, timeouts, consulta, idempotencia, concurrencia y recuperación segura. ## Secuencia por método | Método | Secuencia normal | | - | - | | CARD | Autorizar → solicitar tarjeta y PIN cuando corresponda → procesar → confirmar resultado. | | QR | Autorizar → generar QR y transacción pendiente → esperar confirmación de pago → confirmar resultado. | El POST espera un resultado hasta agotar su tiempo de espera. La transacción QR existe desde que se genera el código. Consulta los [diagramas CARD y QR](/procesamiento-fisico/alignet-transit/cancelacion). ## Después de cancelar Para ambos métodos, el PinPAD corta el flujo visual cuando recibe y procesa `/cancel`. Si falla la conexión, no puedes asegurar recepción ni cierre visual. Reconoce la cancelación confirmada y validada en la respuesta del POST. Ante fallo, timeout o incertidumbre, consulta el cobro original con `GET /payments/{operationNumber}`. Un cobro CARD aprobado permite evaluar un extorno independiente. Si QR aparece `transaction.state: "AUTORIZADO"` en una consulta `200/00` después de solicitar cancelación, conserva el pago aprobado y registra la discrepancia; no solicites refund ni reversa. Aplica la [tabla de resolución](/procesamiento-fisico/alignet-transit/cancelacion#verificar-el-resultado-final). En QR, la cancelación solo inhabilita el código; ni `/cancel` ni refund devuelven un monto pagado. Ante timeout, desconexión o fallo del backend, el frontend muestra **Cancelación no confirmada** y consulta el estado. Sin solicitud de cancelación, un QR `transaction.state: "AUTORIZADO"` en una consulta `200/00` confirma el pago y permite ejecutar la acción de negocio. Los ciclos de consulta repiten únicamente el GET; no reenvían `/cancel`. No inicies una nueva transacción mientras la anterior siga sin resolverse. Un `202 WAITING_RESULT` tardío de `/authorize` no reemplaza un resultado final confirmado. ## Timeouts Los POST de autorización, cancelación y extorno esperan al PinPAD aproximadamente **90 segundos**, según la guía 1.3.25. Configura un timeout superior y valida la duración en tu ambiente. Configura el timeout de lectura del cliente HTTP por encima de la espera del terminal: ```text theme={"system"} Espera aproximada de los POST: 90 s Timeout HTTP del sistema central: al menos 100–110 s ``` `GET /payments` puede esperar aproximadamente 12–15 segundos por la pasarela; usa, por ejemplo, 20 segundos de timeout. `GET /health` y `GET /reversals` responden inmediatamente. Todas las respuestas incluyen `Connection: close`: abre una conexión por petición, sin keep-alive. Un cobro puede tomar decenas de segundos. No uses el mismo timeout corto que aplicarías a una API convencional. Si el timeout del sistema central vence antes que el del terminal, el pago puede continuar aunque el comercio haya perdido la conexión. Un timeout de red nunca equivale a rechazo. El valor definitivo de la espera interna, el timeout del sistema central y el tiempo máximo de recuperación deben validarse con Alignet antes de producción. ## Recuperación de una operación incierta Usa `GET /payments/{operationNumber}` para consultar el cobro original **en la pasarela**. Devuelve `success`, `resultCode`, `resultMessage` y `transaction`, sin `status` propio; `00` indica encontrada y el desenlace financiero se lee en `transaction.state`. No existe consulta de cancelación. Para un extorno CARD, usa `GET /reversals/{operationNumber}`; HTTP `502 UNKNOWN` termina esa solicitud sin confirmar éxito y requiere revisión financiera. Consulta cuando ocurra cualquiera de estos casos: * `POST /authorize` devuelve HTTP `202` con `WAITING_RESULT` y `result: null`; * el timeout del cliente HTTP vence sin recibir respuesta; * la conexión se interrumpe durante el cobro; * el sistema central se reinicia con una operación abierta; * la consulta no verifica el cobro (`200/03`, `404/05`, `503` o `504`) o su estado financiero no permite concluir. ```mermaid theme={"system"} flowchart TD A[Guardar referencia] --> B[Consultar pasarela: GET payments] B -->|200 y 00: encontrada| C[Interpretar transaction.state] C -->|Desenlace confirmado| F[Registrar resultado financiero] C -->|Sin confirmar| D[Esperar según política de consulta] B -->|03 o 05 o 503 o 504: no verificado| D D --> B D -->|Límite alcanzado| E[Escalar sin otro cobro] ``` Procedimiento: 1. Conserva el `operationNumber` original. 2. Mantén la operación como no resuelta en el sistema central. 3. No ejecutes la acción de negocio asociada ni marques un rechazo definitivo. 4. Ejecuta `GET /payments/{operationNumber}`. 5. Si el POST previo devolvió `202`, respeta `Retry-After: 2` antes del primer GET. Este GET no devuelve `202`; interpreta su [tabla HTTP](/procesamiento-fisico/alignet-transit/respuesta-estados-y-codigos#consulta-de-estado). 6. Sigue consultando hasta conocer el resultado del cobro o alcanzar el límite de espera acordado. 7. Si alcanzas ese límite sin verificar el resultado financiero, escala la operación para resolución. No inicies automáticamente otro cobro. ## Idempotencia `operationNumber` es la clave de idempotencia del cobro. Esta tabla aplica a `/authorize`; el [extorno](/procesamiento-fisico/alignet-transit/extorno#recuperaci%C3%B3n-e-idempotencia) permite otro intento tras `DENIED`, `UNKNOWN` o `ERROR` finales. | Escenario | Comportamiento garantizado | | - | - | | Misma referencia mientras se procesa | No se inicia un segundo cobro. Pay-me PinPAD responde HTTP `202` sin iniciar otro cargo; interpreta `WAITING_RESULT` y `result: null`. | | Misma referencia ya finalizada | No se inicia un segundo cobro. Pay-me PinPAD responde HTTP `200` con el resultado almacenado. | | Resultado perdido por el sistema central | El sistema central puede consultar o reenviar la misma referencia para recuperar el resultado existente. | | Nueva operación real | El sistema central debe generar una referencia nueva. | ```text theme={"system"} 1 operación real de cobro = 1 operationNumber ``` No cambies el monto ni la moneda al reutilizar una referencia. El contrato vigente no documenta el comportamiento para una misma referencia con un payload diferente; evita esa condición y escálala si ocurre. ## Concurrencia Pay-me PinPAD procesa una sola operación a la vez: * Si llega el mismo `operationNumber`, aplica la regla de idempotencia. * Si llega otro `operationNumber` mientras existe un cobro activo, responde HTTP `409` con `POS_BUSY`. * El sistema central debe serializar los cobros destinados al mismo terminal. * Después de `POS_BUSY`, espera a que el terminal se libere antes de reintentar la solicitud que no fue aceptada. Si varios procesos pueden enviar pagos al mismo Wiseasy P5L, coordínalos mediante una cola o bloqueo único en el sistema central. ## Reinicios ### Reinicio del sistema central Al iniciar, recupera las operaciones guardadas cuyo resultado aún no conoces y consulta cada `operationNumber` antes de decidir si hubo cobro. ### Reinicio del Wiseasy P5L durante el cobro El resultado del cobro puede quedar sin verificar. La guía no define un estado de respuesta específico para el reinicio. No marques la operación como aprobada ni rechazada. Consulta la referencia y solicita revisión si no logras conocer el resultado dentro del límite de espera acordado. ## Flujo recomendado del sistema central ```text theme={"system"} 1. GET /health para confirmar disponibilidad. 2. Generar y persistir un operationNumber único. 3. POST /authorize con timeout de al menos 100–110 s. 4. Evaluar HTTP, success, resultCode y result.state. 5. Confirmar autorización con 200 + success true + 00 + AUTORIZADO. En consulta 200/00, leer transaction.state; 00 solo significa encontrada. Reconocer cancelación validada en la respuesta de POST /cancel. Si falla y el cobro CARD está aprobado, evaluar un extorno independiente. Conservar QR aprobado sin refund ni reversa; registrar la discrepancia. 6. Ante 202, timeout o desconexión, consultar la referencia original. 7. Iniciar otro cobro solo después de confirmar el desenlace financiero anterior, con un operationNumber nuevo y después de la decisión del usuario. ``` ## Decisión de negocio Define antes de producción qué hará el comercio cuando todavía no sabe si se cobró. No confirmes la venta ni ejecutes una acción irreversible —por ejemplo, abrir una barrera— hasta confirmar `success: true`, `resultCode: "00"` y `result.state: "AUTORIZADO"` en autorización, o una consulta `200/00` con `transaction.state: "AUTORIZADO"`. La política para operaciones sin verificar, incluido el escalamiento manual, requiere acuerdo entre el integrador y Alignet. ## Persistencia mínima Guarda, cuando existan: ```text theme={"system"} operationNumber amount currency paymentMethod tollData additionalFields código HTTP success y result.state (autorización) success y transaction.state (consulta a pasarela) status (cancelación y extorno) resultCode y resultMessage, o message en extorno 502 UNKNOWN identificador de transacción y código de autorización, cuando existan completedAt (cancelación o extorno, cuando exista) fecha y hora de cada solicitud y respuesta ``` No almacenes datos sensibles de tarjeta. Conserva por separado los eventos de cancelación, la autorización original y cualquier extorno explícito. Guarda su estado y marcas de tiempo para evitar decisiones basadas en una respuesta anterior. # Solicitud de autorización Source: https://docs.pay-me.com/procesamiento-fisico/alignet-transit/parametros-de-envio Parámetros, validaciones y ejemplos para iniciar un pago con POST /authorize. El sistema central del comercio inicia el procesamiento del pago mediante `POST /authorize` a Pay-me PinPAD. La conexión permanece abierta mientras el terminal procesa la operación, hasta recibir un resultado o completar el tiempo de espera de la solicitud. Mientras la autorización continúa en curso, puedes solicitar su [cancelación](/procesamiento-fisico/alignet-transit/cancelacion) mediante `POST /cancel` con el mismo `operationNumber`. La solicitud original de `/authorize` puede seguir abierta hasta completar su tiempo de espera, aunque la cancelación ya se haya procesado y el PINPAD haya salido de la pantalla de pago. Si la conexión falla al solicitar cancelación, no puedes asegurar que el PinPAD la recibió ni que cerró la pantalla. Consulta siempre la referencia original; sin solicitud de cancelación, un QR con `transaction.state: "AUTORIZADO"` en una consulta `200/00` confirma el pago. Si posteriormente `/authorize` responde HTTP `202` con `success: false`, `resultCode: "WAITING_RESULT"` y `result: null`, significa que venció la espera de esa solicitud. Esta respuesta no invalida una cancelación confirmada. Si aún no conoces el resultado del cobro, consulta `GET /payments/{operationNumber}`. ```http theme={"system"} POST /authorize Content-Type: application/json Connection: close ``` Construye la URL con la dirección IP y el puerto configurados en el terminal: ```text theme={"system"} http://:/authorize ``` ## Flujos por método | Método | Inicio | Confirmación del cobro | | - | - | - | | CARD | El PinPAD solicita la tarjeta después de `POST /authorize`. | `success: true`, `resultCode: "00"` y `result.state: "AUTORIZADO"`. | | QR | `POST /authorize` genera el QR y crea una transacción pendiente asociada a `operationNumber`. | La misma aprobación de autorización; mostrar o escanear el QR no basta. | Consulta los [diagramas y las respuestas de cancelación](/procesamiento-fisico/alignet-transit/cancelacion). Si la cancelación falla o no está confirmada, consulta el cobro original; no existe una consulta de cancelación. ## Solicitud mínima Solo `operationNumber` y `amount` son obligatorios. Este ejemplo también indica moneda y método: ```json theme={"system"} { "operationNumber": "44992528", "amount": "100", "currency": "604", "paymentMethod": "QR" } ``` ## Parámetros | Campo | Tipo JSON | Obligatorio | Validación | Descripción | | - | - | - | - | - | | `operationNumber` | String | Sí | Cadena de 1 a 64 caracteres sin espacios (`^\S{1,64}$`). | Identificador único generado por el sistema central. Se utiliza como clave de idempotencia y referencia de consulta. | | `amount` | Entero o String numérico | Sí | Cadena numérica que representa un entero positivo de 1 a 12 dígitos, expresado en unidades menores. | Importe total del pago. Por ejemplo, `"1500"` representa S/ 15.00. | | `currency` | Número o String | No | Exactamente 3 dígitos (`^\d{3}$`); predeterminado `604`. | Código numérico ISO 4217 de la moneda. Para soles peruanos, envía `"604"`. | | `paymentMethod` | String | No | `CARD` o `QR`, sin distinguir mayúsculas; predeterminado `CARD`. | Método con el que Pay-me PinPAD procesará el pago. | | `tollData` | Object | No | Sus campos deben enviarse como String. | Datos de la operación de peaje. Pueden enviarse para fines de trazabilidad. | | `additionalFields` | Object | No | Todos los valores deben ser String. | Información complementaria asociada al pago. | Respeta los nombres y los tipos JSON de cada campo. Por ejemplo, envía `paymentMethod`, no `payment_method`. ## Detalle de los parámetros ### `operationNumber` Genera un `operationNumber` nuevo para cada pago y almacénalo antes de llamar a `POST /authorize`. El valor debe cumplir estas condiciones: * ser una cadena de 1 a 64 caracteres sin espacios; * ser único para una operación real de pago; * permanecer asociado a la operación hasta obtener un resultado final. Si no recibes el resultado por un timeout o una pérdida de conexión, conserva la referencia original. Consulta el estado actualizado antes de decidir si corresponde reenviar exactamente la misma solicitud. No generes otro `operationNumber` después de un timeout. La solicitud original puede haber producido un cargo. ### `amount` Expresa el importe en unidades menores, sin símbolo de moneda, separadores ni decimales: | Importe | Valor válido de `amount` | | - | -: | | S/ 1.00 | `"100"` | | S/ 8.50 | `"850"` | | S/ 15.00 | `"1500"` | | S/ 125.40 | `"12540"` | Envía `amount` como entero JSON o String numérico positivo de 1 a 12 dígitos (`^\d{1,12}$`). No utilices decimales, signos, espacios ni separadores. El servidor puede aplicar un máximo configurado; el ejemplo S/ 500.00 de la guía no establece un límite universal. ### `currency` `currency` es opcional: acepta un número de tres dígitos o su String. Si lo omites, se usa `604`. Para pagos en soles peruanos, utiliza `"604"`. Confirma con Alignet cualquier moneda distinta de PEN antes de habilitarla en producción. ### `paymentMethod` Si envías `paymentMethod`, usa uno de estos valores, sin distinguir mayúsculas. Si lo omites, se usa `CARD`: | Valor | Método de pago | | - | - | | `CARD` | Tarjeta de crédito o débito. | | `QR` | Código QR. | Cada solicitud admite un solo método de pago. No envíes `CARD` y `QR` juntos, arreglos, valores combinados como `"CARD,QR"`, ni valores diferentes de los documentados. `card` y `qr` son válidos. ### `tollData` Utiliza `tollData` para enviar datos de la operación de peaje con fines de trazabilidad. El objeto y todos sus campos son opcionales. Se fusiona con `additionalFields`; ante claves coincidentes prevalece `tollData`. Las claves siguientes son convenciones de peaje, no un catálogo de restricciones del servidor. | Campo | Tipo JSON | Obligatorio | Descripción | | - | - | - | - | | `shiftId` | String | No | Identificador del turno y la vía. Su formato se acuerda para cada integración; no existe una composición única para todos los operadores. | | `tollOperatorId` | String | No | Identificador del operador del peaje. | | `tollPointId` | String | No | Identificador del punto de peaje. | | `laneId` | String | No | Identificador de la vía o carril. | | `transactionDateTime` | String | No | Fecha y hora de la operación en formato ISO 8601, con zona horaria. | | `plate` | String | No | Placa del vehículo. | | `tollAmount` | String | No | Importe del peaje expresado en unidades menores. | | `withholdingAmount` | String | No | Importe de la retención expresado en unidades menores. | | `direction` | String | No | Sentido de circulación. | | `vehicleClass` | String | No | Categoría del vehículo. | | `axleCount` | String | No | Número de ejes. | Como recomendación de conciliación para el comercio, relaciona los importes de peaje y retención así; la guía no documenta esta igualdad como validación del servidor: ```text theme={"system"} amount = tollAmount + withholdingAmount ``` #### Interpretación de `shiftId` para reportes El formato de `shiftId` se acuerda para cada integración. Por ejemplo, si el formato acordado es `punto + vía + turno + fecha operativa (AAAAMMDD)`, el valor ilustrativo `AB2N20260710` se interpreta así: | Componente | Valor | Significado | | - | - | - | | Punto | `AB` | Debe coincidir con `tollPointId`. | | Vía | `2` | Debe coincidir con `laneId`. | | Turno | `N` | Código del turno según la convención acordada. | | Fecha operativa | `20260710` | Fecha asociada al turno en formato `AAAAMMDD`. | Con la convención acordada, estos componentes pueden usarse como filtros y columnas del reporte de conciliación. En esta convención, deriva `shift` y `shiftDate` de `shiftId` para reportes; no necesitas duplicarlos en el request. Define también cómo interpretar la fecha operativa cuando un turno cruza la medianoche; puede ser distinta del día indicado por `transactionDateTime`. Si el formato del identificador es diferente, define la regla de extracción antes de usarlo en reportes. No apliques el formato ilustrativo a todas las integraciones. ### `additionalFields` El comercio puede declarar en `additionalFields` cualquier otro dato complementario que necesite. Los valores se envían como cadenas. ```json theme={"system"} { "additionalFields": {} } ``` Si el comercio no necesita agregar información complementaria, puede enviar un objeto vacío u omitir `additionalFields`. ## Ejemplo de autorización para peaje El siguiente ejemplo ilustra los datos de la operación de peaje con identificadores genéricos. El formato de `shiftId` mostrado es solo un ejemplo de composición: código del punto (`AB`) + vía (`2`) + turno (`N`) + fecha operativa (`20260710`). Cada integración debe acordar su propia convención. ```json theme={"system"} { "operationNumber": "012001000039", "amount": "3150", "currency": "604", "paymentMethod": "CARD", "tollData": { "shiftId": "AB2N20260710", "tollOperatorId": "OPERADOR_01", "tollPointId": "AB", "laneId": "2", "transactionDateTime": "2026-07-10T00:13:00-05:00", "plate": "TIY953", "tollAmount": "2583", "withholdingAmount": "567", "direction": "NORTH", "vehicleClass": "HEAVY", "axleCount": "3" }, "additionalFields": {} } ``` ## Enviar la solicitud Este ejemplo envía una solicitud mínima: ```bash theme={"system"} curl --header "Connection: close" --request POST "http://:/authorize" \ --header "Content-Type: application/json" \ --max-time 110 \ --data '{ "operationNumber": "44992528", "amount": "100", "currency": "604", "paymentMethod": "QR" }' ``` Reemplaza `` y `` por los valores configurados en tu terminal. ## Respuestas de autorización Interpreta `success`, `resultCode`, `resultMessage` y `result`; este endpoint no devuelve `status` propio. Consulta el [contrato, los ejemplos y la tabla HTTP](/procesamiento-fisico/alignet-transit/respuesta-estados-y-codigos#respuestas-de-post-%2Fauthorize). La respuesta de `/cancel` se interpreta por separado en [Cancelación](/procesamiento-fisico/alignet-transit/cancelacion). ## Verificar el resultado final 1. Conserva `operationNumber`; ante HTTP `202 WAITING_RESULT`, timeout o incertidumbre, consulta la pasarela con `GET /payments/{operationNumber}`. 2. En una consulta `200/00`, interpreta `transaction.state`; `00` solo indica que la operación fue encontrada. 3. Una consulta `200/03`, `404/05`, `503` o `504` no confirma rechazo ni permite otro cobro. Mantén la operación sin resolver y consulta o escala. 4. No sustituyas un resultado confirmado por un `202 WAITING_RESULT` tardío ni decidas por el cierre de pantalla. Tras cancelación fallida, un CARD autorizado permite evaluar un extorno independiente; conserva QR autorizado sin devolución. # Certificación y salida a producción Source: https://docs.pay-me.com/procesamiento-fisico/alignet-transit/pruebas-y-salida-a-produccion Casos de prueba, evidencias y checklist de certificación para Pay-me Transit PinPAD. La certificación debe validar el contrato HTTP, la interacción física con el Wiseasy P5L, la decisión de negocio y la recuperación sin doble cobro. Las tablas describen **resultados esperados**, no pruebas ejecutadas. Registra el resultado real y su evidencia antes de marcar un criterio como cumplido. ## Preparación Antes de ejecutar casos: * registra la versión de Pay-me PinPAD instalada; * confirma la asociación entre sistema central, punto de atención y Wiseasy P5L; * configura una IP estable y el puerto del terminal; * ejecuta `GET /health` desde el sistema central; * completa la verificación de llaves en el terminal; * configura 110 segundos para los POST y 20 segundos para la consulta del cobro; abre una conexión por petición, sin keep-alive; * habilita persistencia y logs sanitizados; * acuerda referencias, montos y medios de pago de prueba. ## Casos de contrato | Caso | Estímulo | Resultado esperado | | - | - | - | | Disponibilidad | `GET /health` | HTTP `200`, `status: "UP"`, `service: "Alignet ECR"`. | | Solicitud mínima | Solo `operationNumber` y `amount` válidos | Se procesa con moneda `604` y método `CARD` predeterminados. | | Solicitud completa | Incluye campos obligatorios, `tollData` y `additionalFields` con valores String | La autorización se procesa sin error de validación. | | Referencia numérica | `operationNumber: "44992528"` | Se acepta como String numérico. | | Referencia alfanumérica | `operationNumber: "CAJA-01_A"` | Se acepta: 1–64 caracteres sin espacios; no se exige que sea numérica. | | Límites de referencia | Cadenas de 1 y 64 caracteres; vacía, de 65 o con espacios | Aceptar las dos primeras; las otras devuelven `400 BAD_REQUEST`. | | Monto como cadena | `amount: "100"` | Se acepta como String numérico en unidades menores. | | Monto como número JSON | `amount: 100` | Se acepta como entero positivo en unidades menores. | | Moneda como cadena | `currency: "604"` | Se acepta como String numérico de tres dígitos. | | Moneda como número JSON | `currency: 604` | Se acepta como número de tres dígitos. | | Moneda ausente | No incluye `currency` | Se usa `604`. | | Método de pago | Ejecuta solicitudes independientes con `paymentMethod: "CARD"` y `paymentMethod: "QR"` | Cada valor se acepta por separado. | | Método de pago ausente | No incluye `paymentMethod` | Se usa `CARD`. | | Método sin distinguir mayúsculas | `card` o `qr` en solicitudes independientes | Se acepta cada valor. | | Métodos de pago simultáneos | Envía `CARD` y `QR` juntos, como arreglo o valor combinado | HTTP `400` con `BAD_REQUEST`. | | Método de pago inválido | Envía un valor distinto de `CARD` o `QR` | HTTP `400` con `BAD_REQUEST`. | | Referencia inválida | Vacía, de más de 64 caracteres o con espacios | HTTP `400` con `BAD_REQUEST`. | | Monto inválido | Cero, negativo, decimal, no numérico o mayor de 12 dígitos | HTTP `400` con `BAD_REQUEST`. | | Moneda inválida | No contiene exactamente tres dígitos | HTTP `400` con `BAD_REQUEST`. | | Colisión de datos | Misma clave con valores diferentes en `tollData` y `additionalFields` | Prevalece el valor de `tollData` en los campos fusionados. | | Campo adicional inválido | Valor que no es String | HTTP `400` con `BAD_REQUEST`. | ## Casos transaccionales | Caso | Resultado esperado | Decisión del sistema central | | - | - | - | | Pago aprobado | HTTP `200`, `success: true`, `resultCode: "00"`, `result.state: "AUTORIZADO"`, sin `status` propio. | Confirmar y aplicar la regla de apertura. | | Pago rechazado | HTTP `200`, `success: false`, código SDK distinto de `00` y `result.state` crudo de la pasarela. | No confirmar. | | Extorno explícito CARD aprobado | HTTP `200`, `REVERSED` con `00`, `16` o `17`. | Registrar extorno confirmado o éxito equivalente. | | Extorno pendiente | HTTP `202`; `SEARCHING`, `PROCESSING` o `PENDING`. `P22` se clasifica como `PENDING`. | Esperar `Retry-After: 2` y consultar `GET /reversals/{operationNumber}`. | | Extorno denegado | HTTP `200`, `DENIED`. | No registrar como extornado ni reintentar automáticamente. | | Cobro sin confirmar | HTTP `202`, `success: false`, `WAITING_RESULT`, `result: null`, sin `status`. | Seguir consultando con la misma referencia, sin otro cobro. | | Extorno sin confirmar | HTTP `502`, `UNKNOWN`: la solicitud terminó con error. El cuerpo incluye solo `operationNumber`, `status` y `message`. | Revisar si se ejecutó el extorno; no registrar éxito ni reenviar automáticamente. | | Método incorrecto | Usar un método no admitido en una ruta válida. | HTTP `405`, `METHOD_NOT_ALLOWED`. | | Consulta inválida | Consultar `/payments` o `/reversals` con segmento vacío o inválido. | HTTP `400` según el error de ruta; no inferir un resultado financiero. | | Headers de respuesta | Todas incluyen `Connection: close` y `Cache-Control: no-store`; HTTP `202` añade `Retry-After: 2`. | Comprobar headers y respetar el intervalo de consulta. | | Espera agotada | Autorización: HTTP `202`, `success: false`, `WAITING_RESULT`, `result: null`. | Consultar, sin nuevo cobro. | | Terminal ocupado | Otra referencia durante un cobro activo devuelve `409 POS_BUSY`. | Esperar y reintentar cuando se libere. | | Terminal no listo | HTTP `503 POS_NOT_AVAILABLE`. | Recuperar disponibilidad antes de reintentar. | | Referencia inexistente | La consulta del cobro devuelve `404/05`, `success: false`, `transaction: null`. | Verificar la referencia; no asumir rechazo financiero. | ## Consulta del cobro en la pasarela Comprueba esta forma en todas las respuestas: `operationNumber`, `success`, `resultCode`, `resultMessage` y `transaction`, sin `status` propio. El GET no devuelve `202` ni estados locales. | Caso | Resultado esperado | Decisión | | - | - | - | | Operación encontrada | `200/00`, `success: true`, `transaction.state` crudo | `00` significa encontrada. `AUTORIZADO` confirma aprobación; `CANCELADO` confirma cancelación del cobro. | | Operación no encontrada | `404/05`, `success: false`, `transaction: null` | Verificar referencia y terminal; no confirmar rechazo ni habilitar otro cobro. | | SDK no inicializado o terminal sin disponibilidad | `503/P04` o `POS_NOT_AVAILABLE`, `success: false`, `transaction: null` | Restablecer disponibilidad y consultar de nuevo. | | Espera interna agotada | `504/SEARCH_TIMEOUT`, `success: false`, `transaction: null` | Cobro no verificado; consultar de nuevo o escalar. | | Servicio incierto | `200/03`, `success: false`, `transaction: null` | No confirmar rechazo ni iniciar otro cobro. | | Consulta lenta | Respuesta en aproximadamente 12–15 segundos | El timeout de ejemplo de 20 segundos permite leerla; una desconexión conserva la operación sin resolver. | ## Validación de cancelación Aplica estos casos a CARD y QR. El servicio valida ejecución y correspondencia con la operación; el cierre visual no acredita éxito. | Caso | Estímulo | Resultado esperado | | - | - | - | | Cancelación abandonada con `14/15` | Recibir `DENIED/14` o `DENIED/15`. | No reconocer cancelación exitosa; consultar el cobro original. | | Cancelación confirmada | Cancelar una autorización activa y obtener un resultado de esa operación. | `CANCELLED` con `00`, `16` o `17`, validado por el servicio; reconocer el resultado sin consulta obligatoria. | | Éxito equivalente de cancelación | Recibir HTTP `200`, `CANCELLED` con `16` o `17`. | Reconocer cancelación validada; conservar el código SDK sin convertirlo a `00`. | | Cancelación no ejecutada | Simular un fallo que impida ejecutar la cancelación. | Respuesta de error, sin informar éxito; consultar el cobro original. No se anticipan HTTP, código ni mensaje del nuevo error. | | Resultado de otra operación | Entregar al servicio un resultado que no corresponda al `operationNumber` solicitado. | Rechazarlo con una respuesta de error; no cerrar la operación como cancelada. | | Cancelación denegada | Obtener `DENIED` con `14`, `15`, `18`, `19`, `20`, `01`, `03` u otro código SDK. | Cancelación rechazada o abandonada; recuperar el cobro original sin asumir su resultado. | | Segunda cancelación concurrente | Enviar otro `/cancel` para la misma referencia mientras se procesa el primero. | HTTP `409`, `ERROR`, `CANCELLATION_IN_PROGRESS`; no repetir el POST. | | Venta no encontrada | Obtener `05` o `07` del SDK en cancelación. | HTTP `404`; no inferir el resultado financiero del cobro. El cuerpo usa `status: "ERROR"`, `resultCode: "NOT_FOUND"`. | | Timeout o incertidumbre | Perder la respuesta o recibir HTTP `202`, `PENDING` con `P22`. | Mostrar **Cancelación no confirmada**; consultar el cobro original, respetando `Retry-After: 2` en HTTP `202`. | Comprueba que `GET /payments/{operationNumber}` informa el cobro original, no el resultado de la solicitud de cancelación. Consulta la pasarela, sin `status` propio ni HTTP `202`. Ante `200/03`, `404/05`, `503` o `504`, conserva la referencia y no habilites otro cobro. Los ciclos repiten solo el GET. ## Cancelación CARD | Caso | Estímulo | Resultado esperado | | - | - | - | | Cobro aprobado tras cancelación fallida | Recuperar `200/00` con `transaction.state: "AUTORIZADO"` en el cobro original. | Evaluar un extorno independiente con `POST /reversals` y el `operationNumber` de la venta, sin duplicados. Reconocer éxito con `REVERSED` y `00`, `16` o `17`; consultar `/reversals/{operationNumber}` si no está confirmado. | No debe generarse un extorno automático ante cualquier error de cancelación. Presenta la tarjeta cuando el PinPAD la solicite en el extorno. ## Cancelación QR | Caso | Estímulo | Resultado esperado | | - | - | - | | QR pendiente | Generar el QR sin pagar. | Ya existe la transacción pendiente asociada al `operationNumber`; mostrar o escanear no confirma el pago. | | Cancelación validada | Cancelar o inhabilitar el QR pendiente. | Reconocer `CANCELLED` con `00`, `16` o `17`, sujeto a la validación del servicio. | | Pago aprobado tras cancelación fallida | Recuperar `200/00` con `transaction.state: "AUTORIZADO"` en el cobro original. | Conservar el pago aprobado y registrar la discrepancia. Ni `/cancel` ni refund devuelven el monto; no enviar `/reversals`. | ## Casos de idempotencia y recuperación | Caso | Validación esperada | | - | - | | Misma referencia durante el proceso | El segundo envío no inicia otro cobro y devuelve `202 WAITING_RESULT`, `success: false`, `result: null`, sin `status` propio. | | Misma referencia finalizada | Devuelve `200` con el resultado guardado sin otro cargo. | | Otra referencia concurrente | Devuelve `409 POS_BUSY`. | | Timeout del sistema central | El sistema central consulta la referencia original antes de aceptar otro intento. | | Pérdida de red | Al reconectar, el sistema central consulta las operaciones abiertas. | | Reinicio del sistema central | Recupera las referencias guardadas y consulta los cobros cuyo resultado aún no conoce. | | Reinicio del P5L durante el cobro | Consultar la pasarela con la referencia original; no anticipar un estado local de respuesta ni concluir rechazo. | | `202` de POST o de consulta local de extorno | Respetar `Retry-After: 2`; el GET del cobro no devuelve `202`. | | Extorno exitoso o en curso repetido | `REVERSED` devuelve `200` guardado; `SEARCHING`/`PROCESSING`/`PENDING` devuelve `202`, sin otro intento. | | Extorno previo `NOT_FOUND` | Otro POST devuelve `404` sin ejecutar otro intento. | | Nuevo extorno tras `DENIED`, `UNKNOWN` o `ERROR` final | Tras consulta y decisión controlada, el POST puede ejecutar otro intento real. No activar reintento automático por incertidumbre. | ## Verificaciones de seguridad El puerto del terminal no es accesible desde redes no autorizadas ni desde Internet. `operationNumber` no contiene datos personales. Las solicitudes, respuestas y evidencias no contienen PAN completo, CVV, PIN, PIN Block, pistas ni datos EMV sensibles. El acceso y la retención de logs están controlados. ## Lista de verificación para producción Cada Wiseasy P5L tiene IP fija o reserva DHCP y puerto documentado. El sistema central distingue cancelación validada de recuperación del cobro ante fallo o incertidumbre, para CARD y QR. El timeout definitivo del sistema central es mayor que la espera interna confirmada de Pay-me PinPAD. La frecuencia, el backoff y el límite de consulta están acordados. La autorización se confirma con `200`, `success: true`, `00` y `result.state: "AUTORIZADO"`; en consulta `200/00`, se interpreta `transaction.state`. La lógica de idempotencia, concurrencia, timeout y reinicio superó las pruebas. La decisión de negocio para resultados inciertos y estados propios de cancelación/extorno está aprobada. Los datos del peaje permanecen en `tollData`; las claves complementarias, monedas y métodos están confirmados. Las clasificaciones de cobro, cancelación y extorno respetan los códigos SDK sin normalizaciones adicionales. Existen monitoreo, contactos de soporte y un procedimiento de escalamiento. El integrador y Alignet aprobaron las evidencias de integración y UAT. Se valida el extorno CARD independiente tras cancelación fallida y se conservan pagos QR aprobados sin devolución. ## Criterio de aceptación No habilites producción mientras exista riesgo de interpretar una consulta incierta, un timeout o `404/05` como rechazo y generar un cobro adicional. La salida requiere demostrar que toda operación incierta conserva su referencia original hasta resolverse o escalarse. # Referencia de endpoints Source: https://docs.pay-me.com/procesamiento-fisico/alignet-transit/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://: ``` 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` | `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`. 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://:/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://:/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. Implementa el payload de `POST /authorize`. Interpreta códigos HTTP y estados transaccionales. # Requisitos y responsabilidades Source: https://docs.pay-me.com/procesamiento-fisico/alignet-transit/requisitos-y-responsabilidades Requisitos y responsabilidades del comercio, el integrador, Pay-me PinPAD y Alignet. ## Matriz de responsabilidades | Área | Comercio o integrador — sistema central | Pay-me PinPAD / Alignet | Validación conjunta | | - | - | - | - | | Red local | Alcanzar la IP y el puerto del terminal; configurar firewall y timeout. | Exponer el servidor HTTP en el Wiseasy P5L. | Ejecutar `GET /health` desde el sistema central. | | Operación | Calcular el monto, generar y persistir `operationNumber` y aplicar la decisión de negocio. | Validar la solicitud; ejecutar el cobro, cancelación o extorno; y devolver el resultado. | Probar aprobación, rechazo, cancelación y recuperación por método; extorno únicamente CARD. | | Idempotencia | Mantener una sola referencia por operación real y consultar ante incertidumbre. | Evitar un segundo cargo para la misma referencia y conservar el resultado. | Simular timeout, reenvío y consulta. | | Concurrencia | Serializar solicitudes destinadas al mismo terminal. | Procesar una operación a la vez y devolver `409 POS_BUSY` a otra referencia. | Enviar solicitudes concurrentes controladas. | | Configuración | Registrar IP, puerto y asociación entre sistema central, punto de atención y terminal. | Instalar la aplicación, configurar IP/puerto y verificar llaves. | Confirmar el estado operativo que muestra Pay-me PinPAD. | | Seguridad | Proteger la red, los logs y los datos de conciliación. | No exponer datos sensibles de tarjeta en la respuesta. | Revisar evidencias sanitizadas. | | Soporte | Conservar solicitudes, respuestas, códigos HTTP y marcas de tiempo. | Correlacionar la operación y apoyar el diagnóstico. | Definir responsables y escalamiento. | ## Requisitos del sistema central ### Cliente HTTP * Implementa `GET /health`, `POST /authorize`, `GET /payments/{operationNumber}`, `POST /cancel`, `POST /reversals` y `GET /reversals/{operationNumber}`. * Envía `Content-Type: application/json` en la autorización, la cancelación y el extorno. * Configura al menos 100 a 110 segundos de timeout para `POST /authorize`, `POST /cancel` y `POST /reversals` con la espera de desarrollo actual. * Abre una conexión por petición: todas las respuestas usan `Connection: close`; no reutilices keep-alive. * Configura la consulta del cobro para cubrir aproximadamente 12–15 segundos, por ejemplo con timeout de 20 segundos. * Lee el HTTP y el JSON; verifica `Cache-Control: no-store` y respeta `Retry-After: 2` en HTTP `202`. * Maneja `200`, `202`, `400`, `404`, `405`, `409`, `502`, `503` y `504` según la operación. * Mantén una cola o bloqueo por terminal para no enviar cobros concurrentes. ### Estado transaccional * Persiste la referencia y los datos del cobro antes del envío. * Confirma autorización con `success: true`, `resultCode: "00"` y `result.state: "AUTORIZADO"`. En consulta `200/00`, interpreta `transaction.state`. Ante cancelación fallida, evalúa un extorno independiente solo en CARD; conserva QR aprobado sin devolución. * Interpreta `/cancel` por su respuesta. Ante fallo, timeout o incertidumbre, consulta el cobro original; no existe un GET de cancelación. * Solo en CARD, verifica el extorno completado o en curso antes de solicitar otro; conserva abiertas las operaciones cuya resolución no puedas comprobar. * Consulta la pasarela ante cobros sin verificar; `200/03`, `404/05`, `503` o `504` no confirman rechazo ni permiten otro cargo. Un extorno `UNKNOWN` con HTTP `502` requiere revisión; no confirma éxito. * Recupera las operaciones abiertas después de un reinicio del sistema central. * No conviertas un timeout o `404` de consulta en rechazo financiero. ### Decisión de negocio * Define la acción que ejecutará el comercio después de una aprobación —por ejemplo, confirmar una venta o abrir una barrera— y cómo informará un rechazo o una cancelación. * Define el límite de espera y el escalamiento de una operación no resuelta. * Crea una referencia nueva solo después de resolver la operación anterior y verificar su resultado final. Distingue cancelación y rechazo por método, estado, código y mensaje. * Conserva `authorizationCode` y `operationNumber` para el comprobante y la conciliación. ## Preparación del Wiseasy P5L Alignet y el operador deben: * instalar la versión de Pay-me PinPAD correspondiente al package `com.alignet.pinpad.ecr`; * conectar el terminal a la red local y asignarle una IP estable; * configurar la IP y el puerto de escucha, cuyo valor predeterminado es `8080`; * confirmar la llamada real de `GET /health` desde el sistema central; * completar la verificación de inyección de llaves; * dejar la aplicación en **Listo para el siguiente vehículo**; * confirmar que el terminal dispone de la conectividad necesaria para procesar el pago. ## Lista de verificación inicial El sistema central y el Wiseasy P5L están en la misma red local y sin aislamiento entre clientes. La IP del terminal es fija o tiene una reserva DHCP. `GET /health` responde HTTP `200` desde el equipo donde se ejecuta el sistema central. El sistema central genera y persiste un `operationNumber` válido y único por cobro. `operationNumber` es un String de 1–64 caracteres sin espacios. `amount` es entero o String numérico positivo en unidades menores. Moneda y método son opcionales, con valores predeterminados `604` y `CARD`. El cliente maneja la consulta, idempotencia, concurrencia y reinicios. Está definido qué hacer ante un pago aprobado, rechazado o cuyo resultado aún no se conoce. Los logs de pruebas no contienen información sensible de tarjeta. # Respuestas, consulta y códigos Source: https://docs.pay-me.com/procesamiento-fisico/alignet-transit/respuesta-estados-y-codigos Esquemas JSON, códigos SDK y respuestas HTTP de cobro, cancelación y extorno. 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: ```json theme={"system"} { "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: ```json theme={"system"} { "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: ```json theme={"system"} { "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. | ```json theme={"system"} { "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. ```json theme={"system"} { "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](/procesamiento-fisico/alignet-transit/cancelacion#verificar-el-resultado-final). 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. # Solución de problemas Source: https://docs.pay-me.com/procesamiento-fisico/alignet-transit/solucion-de-problemas Diagnóstico de conectividad, solicitudes inválidas, terminal ocupado y operaciones pendientes. Usa HTTP, `resultCode` y `operationNumber`. En autorización interpreta `success` y `result.state`; en consulta a pasarela, `success` y `transaction.state`; en cancelación/extorno, `status`. No uses el mensaje como única base para decidir. El extorno `502 UNKNOWN` utiliza el cuerpo compacto con `message`. ## Diagnóstico rápido | Síntoma | Causa probable | Acción | | - | - | - | | `GET /health` no responde | IP o puerto incorrectos, firewall, aislamiento de clientes o aplicación cerrada. | Verifica la IP del terminal, la misma red local, AP/Client Isolation, puerto TCP y estado de Pay-me PinPAD. | | `ping` no responde | Sin ruta IP o ICMP bloqueado. | Verifica direccionamiento. Si la red bloquea ICMP, prueba directamente `GET /health`. | | `404` al autorizar | El sistema central llama a una ruta anterior o incorrecta. | Usa exactamente `POST /authorize`; no uses `/payment` ni `/api/v1/payments`. | | `400 BAD_REQUEST` | JSON o campo inválido. | Revisa tipo, obligatoriedad, longitud y formato. Corrige antes de reenviar. | | `409 POS_BUSY` | Existe otra operación activa. | Espera a que termine. Serializa los cobros por terminal. | | `503 POS_NOT_AVAILABLE` | Pay-me PinPAD o el SDK de pagos no está listo. | El operador debe abrir la aplicación y dejarla en estado **Listo**. | | El sistema central pierde la respuesta de autorización | Timeout menor que la duración del cobro o pérdida de red. | No inicies otro cobro. Consulta el `operationNumber` original mediante `GET /payments/{operationNumber}`. | | Autorización `202 WAITING_RESULT` o extorno `202` en curso | Venció la espera, pero la operación puede seguir activa. | Usa el GET correspondiente y respeta `Retry-After: 2`. | | `202` o timeout en cancelación | No hay cancelación confirmada. | Muestra **Cancelación no confirmada**, consulta `GET /payments/{operationNumber}` y respeta `Retry-After`. | | `404/05` al consultar `/payments` | La operación no fue encontrada en la pasarela. | Verifica el valor exacto y el terminal consultado. No asumas rechazo financiero. | | Consulta `/payments` con `200/03`, `503/P04` o `POS_NOT_AVAILABLE`, `504/SEARCH_TIMEOUT` | No se pudo verificar el cobro. | Conserva la referencia y consulta de nuevo o escala; no concluyas rechazo ni generes otra venta. | | Timeouts o respuestas cruzadas al reutilizar sockets | El servidor cierra cada conexión. | Respeta `Connection: close`; abre una conexión por petición y desactiva keep-alive. | | Extorno `502 UNKNOWN` | Búsqueda ambigua o vencimiento del control de espera. | La solicitud terminó sin confirmar éxito. Conserva el cuerpo compacto y solicita revisión financiera; no reintentes automáticamente. | | `/cancel` con HTTP `200`, `DENIED`, incluido `14` | Cancelación rechazada o abandonada. | No registres cancelación exitosa; consulta el cobro original. | | Pantalla cerrada tras procesar cancelación | El cierre visual no determina el resultado financiero. | Evalúa la respuesta de `/cancel`. Ante fallo o incertidumbre, consulta el cobro original; reconoce éxito solo si está validado. | | Falla de conexión durante `/cancel` | No hay certeza de que el PinPAD recibió la solicitud o cerró la pantalla. | Muestra **Cancelación no confirmada**, recupera conexión y consulta la referencia original, sin repetir automáticamente el POST. | | Fallo interno de `/cancel` | La pantalla puede haberse cerrado sin resolver la cancelación financiera. | Muestra **Cancelación no confirmada** y consulta el estado. El POST debe reflejar el fallo o pendiente real. Falta definir la respuesta específica cuando no se ejecutó o no coincide la operación. | | QR `transaction.state: "AUTORIZADO"` en una consulta `200/00` sin solicitud de cancelación | Pago normal aprobado. | Confirmar pago y ejecutar la acción de negocio; no iniciar reversión. | | Cobro CARD `transaction.state: "AUTORIZADO"` en una consulta `200/00` tras cancelación fallida | El cobro original sigue aprobado. | Evalúa un extorno independiente con `POST /reversals`; no lo ejecutes automáticamente ante cualquier error. | | Pago QR confirmado durante cancelación | La transacción existía desde la generación del QR. | Ante cancelación fallida o incierta, consulta el cobro. Si aparece `transaction.state: "AUTORIZADO"` en una consulta `200/00`, conserva el pago aprobado y registra la discrepancia, sin refund ni reversa. | | `/cancel` devuelve `409 CANCELLATION_IN_PROGRESS` | Ya se procesa otra cancelación de la misma referencia. | No repitas el POST. Conserva la referencia y recupera el cobro original si no recibes el resultado. | | Método incorrecto en ruta válida | El método HTTP no está admitido. | HTTP `405`, `METHOD_NOT_ALLOWED`; corrige el método. | | `202 WAITING_RESULT` tardío de `/authorize` | Venció la espera de esa solicitud. | Conserva el resultado confirmado y consulta si queda una discrepancia. | ## `GET /health` no responde Sigue este orden: 1. Confirma en el Wiseasy P5L la IP y el puerto configurados. 2. Confirma que el sistema central usa esos valores y no una dirección anterior. 3. Verifica que ambos equipos estén en la misma red local. 4. Desactiva AP Isolation o Client Isolation para esos equipos. 5. Verifica que el firewall permita el puerto TCP configurado, `8080` por defecto. 6. Abre Pay-me PinPAD y confirma que la aplicación continúa en primer plano y lista. 7. Ejecuta nuevamente `GET /health` desde el mismo host y proceso de red que usará el sistema central. Respuesta esperada: ```json theme={"system"} { "status": "UP", "service": "Alignet ECR" } ``` ## `400 BAD_REQUEST` Verifica: * `operationNumber`: String de 1–64 caracteres sin espacios; conserva la referencia original y evita `/` para consultarla por ruta; * `amount`: entero JSON o String numérico positivo de 1 a 12 dígitos en unidades menores; * `currency`: número o String de exactamente tres dígitos; opcional, predeterminado `604`; * `paymentMethod`: opcional, predeterminado `CARD`; acepta `CARD` o `QR` sin distinguir mayúsculas; * `tollData`: objeto opcional de valores String; se fusiona con `additionalFields` y prevalece en colisiones; * `additionalFields`: objeto opcional cuyos valores son únicamente String; * header `Content-Type: application/json`; * JSON bien formado. Conserva el `resultMessage` para saber qué validación falló. No lo muestres sin control al usuario final. ## Timeout o desconexión Un timeout describe la conexión del sistema central, no el resultado financiero. El siguiente flujo corresponde a `POST /authorize`. Para una cancelación, conserva la referencia y aplica el [procedimiento de `/cancel`](/procesamiento-fisico/alignet-transit/cancelacion#manejo-de-202-y-p%C3%A9rdida-de-conexi%C3%B3n). El extorno CARD es una acción independiente y tiene su propia consulta. ```text theme={"system"} POST sin respuesta → conservar operationNumber → GET /payments/{operationNumber} → leer transaction.state si responde 200/00 → consultar de nuevo o escalar ante 200/03, 404/05, 503 o 504 → registrar solo un resultado confirmado ``` `GET /payments` puede tardar aproximadamente 12–15 segundos; usa un timeout de cliente de ejemplo de 20 segundos. No devuelve `202` ni estados locales. Confirma que el timeout del `POST` sea mayor que la espera interna del terminal. Con la referencia de desarrollo de 90 segundos, utiliza al menos 100 a 110 segundos. ## Operación pendiente por demasiado tiempo 1. Mantén el mismo `operationNumber`. 2. Si el POST devolvió HTTP `202`, respeta `Retry-After: 2` antes de consultar. En las siguientes consultas a pasarela, aplica el intervalo y límite acordados. 3. Verifica que el terminal conserve conectividad local y conectividad con la plataforma de pagos. 4. Al alcanzar el límite acordado, inmoviliza la operación y escala. No crees automáticamente otra venta. El límite máximo de consulta y la decisión de negocio deben definirse antes de producción. ## Datos para soporte Comparte: * ambiente, fecha y hora con zona horaria; * identificador del sistema central, punto de atención y Wiseasy P5L; * versión de Pay-me PinPAD; * IP y puerto, sin exponer información innecesaria fuera del canal de soporte; * `operationNumber` y `paymentMethod`; * cierre visual y secuencia de autorización, cancelación, consultas y extorno; * evidencia de extorno completado, en curso o todavía no verificable; * código HTTP, `Connection`, `Cache-Control` y `Retry-After`; * cuerpo de solicitud y respuesta sanitizados; * duración del `POST` y secuencia de consultas; * cambios de red o reinicios observados. No compartas PAN completo, CVV, PIN, PIN Block, pistas ni datos EMV sensibles. Revisa el algoritmo de consulta, idempotencia y concurrencia. Ejecuta los casos antes de habilitar cobros reales. # Response Source: https://docs.pay-me.com/response Estructura de respuesta para autorizaciones Ecommerce y POS mediante el endpoint POST /authorize. La respuesta del servicio de autorización aplica para ambos canales: * Ecommerce * POS Esta estructura permite identificar si la petición fue procesada, el resultado enviado por la marca, los identificadores de trazabilidad y el estado interno de la operación. ## Response exitoso ```json theme={"system"} { "success": "true", "transaction": { "tk_transaction_identifier": "42c2ff66-3eb0-4a69-9848-430fc722f6bc", "processor_response": { "message": { "code": "00", "description": "Pago exitoso" }, "brand_transaction_identifier": "306190611475347", "authorization_identification_response": "087657", "retrieval_reference_code": "619016007284", "system_trace_audit": "007284", "response_code": "00", "date_settlement": "0710" }, "meta": { "status": { "code": "success_operation", "message_ilgn": [ { "locale": "es_PE", "value": "Petición procesada correctamente" } ] }, "metrics": { "aggregate": { "start": "1783616336421", "end": "1783616348410", "duration": { "milliseconds": "11988" } } } } } } ``` ## Descripción de campos | Campo | Tipo | Descripción | | - | - | - | | `success` | string | Indica si la operación fue procesada por el servicio. Valores: `true` o `false`. | | `transaction.tk_transaction_identifier` | string UUID | Identificador único de la transacción en el sistema. | | `transaction.processor_response.message.code` | string | Código de respuesta de la marca. `00` indica operación aprobada. | | `transaction.processor_response.message.description` | string | Descripción legible del resultado de la operación. | | `transaction.processor_response.brand_transaction_identifier` | string | Identificador de la transacción asignado por la marca. | | `transaction.processor_response.authorization_identification_response` | string | Código de autorización de la operación. Normalmente contiene 6 dígitos. | | `transaction.processor_response.retrieval_reference_code` | string | RRN, Retrieval Reference Number. Se utiliza para consultas, trazabilidad y conciliación. | | `transaction.processor_response.system_trace_audit` | string | STAN, System Trace Audit Number. Identificador de auditoría de la transacción. | | `transaction.processor_response.response_code` | string | Código ISO de respuesta. `00` indica aprobación. | | `transaction.processor_response.date_settlement` | string | Fecha estimada de liquidación en formato `MMDD`. | | `transaction.meta.status.code` | string | Estado interno de la operación. Ejemplos: `success_operation`, `invalid_request`. | | `transaction.meta.status.message_ilgn` | array | Lista de mensajes localizados asociados al resultado de la operación. | | `transaction.meta.status.message_ilgn[].locale` | string | Locale del mensaje. Ejemplo: `es_PE`. | | `transaction.meta.status.message_ilgn[].value` | string | Mensaje descriptivo del resultado de la operación. | | `transaction.meta.metrics.aggregate.start` | string | Marca de tiempo de inicio del procesamiento. | | `transaction.meta.metrics.aggregate.end` | string | Marca de tiempo de fin del procesamiento. | | `transaction.meta.metrics.aggregate.duration.milliseconds` | string | Tiempo total de procesamiento en milisegundos. | ## Interpretación de respuesta exitosa Una autorización se considera aprobada cuando los principales campos de respuesta tienen los siguientes valores: | Campo | Valor esperado | Interpretación | | - | - | - | | `success` | `true` | La petición fue procesada por el servicio. | | `processor_response.message.code` | `00` | La marca respondió con aprobación. | | `processor_response.response_code` | `00` | Código ISO de aprobación. | | `meta.status.code` | `success_operation` | Estado interno exitoso. | ## Identificadores de trazabilidad Los siguientes campos pueden utilizarse para seguimiento transaccional, consultas, conciliación, soporte operativo y validación con la marca. | Campo | Uso | | - | - | | `tk_transaction_identifier` | Identificador único interno de la transacción. | | `brand_transaction_identifier` | Identificador asignado por la marca. | | `authorization_identification_response` | Código de autorización de la transacción. | | `retrieval_reference_code` | RRN utilizado para trazabilidad, consultas y conciliación. | | `system_trace_audit` | STAN de la transacción. | | `date_settlement` | Fecha estimada de liquidación. | ## Objeto `processor_response` El objeto `processor_response` contiene la respuesta recibida desde el procesador o la marca. ```json theme={"system"} { "processor_response": { "message": { "code": "00", "description": "Pago exitoso" }, "brand_transaction_identifier": "306190611475347", "authorization_identification_response": "087657", "retrieval_reference_code": "619016007284", "system_trace_audit": "007284", "response_code": "00", "date_settlement": "0710" } } ``` | Campo | Descripción | | - | - | | `message.code` | Código de respuesta de la marca. | | `message.description` | Descripción del resultado de la operación. | | `brand_transaction_identifier` | Identificador de la transacción asignado por la marca. | | `authorization_identification_response` | Código de autorización. | | `retrieval_reference_code` | RRN de la transacción. | | `system_trace_audit` | STAN de la transacción. | | `response_code` | Código ISO de respuesta. | | `date_settlement` | Fecha estimada de liquidación en formato `MMDD`. | ## Objeto `meta.status` El objeto `meta.status` contiene el estado interno de la operación dentro del sistema. ```json theme={"system"} { "status": { "code": "success_operation", "message_ilgn": [ { "locale": "es_PE", "value": "Petición procesada correctamente" } ] } } ``` | Campo | Descripción | | - | - | | `code` | Código interno del estado de la operación. | | `message_ilgn` | Lista de mensajes localizados. | | `message_ilgn[].locale` | Locale del mensaje. | | `message_ilgn[].value` | Descripción localizada del resultado. | ## Objeto `meta.metrics` El objeto `meta.metrics` contiene información de tiempos de procesamiento de la operación. ```json theme={"system"} { "metrics": { "aggregate": { "start": "1783616336421", "end": "1783616348410", "duration": { "milliseconds": "11988" } } } } ``` | Campo | Descripción | | - | - | | `aggregate.start` | Marca de tiempo de inicio del procesamiento. | | `aggregate.end` | Marca de tiempo de fin del procesamiento. | | `aggregate.duration.milliseconds` | Duración total del procesamiento en milisegundos. | ## Consideraciones * El campo `success` indica si la petición fue procesada por el servicio. * Una operación aprobada debe validar el código de respuesta de la marca y el estado interno de la operación. * El campo `tk_transaction_identifier` debe almacenarse para consultas posteriores. * El `retrieval_reference_code` y el `system_trace_audit` son relevantes para trazabilidad operativa. * El `authorization_identification_response` debe utilizarse como código de autorización de la operación. * El campo `date_settlement` permite identificar la fecha estimada de liquidación. * Los tiempos de `meta.metrics` pueden utilizarse para monitoreo, soporte y análisis de performance. *** ## Relación con los canales de autorización Ver trama autorización Ecommerce. Ver trama de autorización POS.

Una integración.
Más formas
de pagar.

Tu negocio. Tu forma de integrar.

E-commerce

Checkout Web

SDK Mobile

Distintos canales.
Un punto de conexión.