Solicitud de autorización

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 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}.

POST /authorize
Content-Type: application/json
Connection: close

Construye la URL con la dirección IP y el puerto configurados en el terminal:

http://<IP_DEL_PINPAD>:<PUERTO>/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. 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:

{
  "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:

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.

{
  "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.

{
  "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:

curl --header "Connection: close" --request POST "http://<IP_DEL_PINPAD>:<PUERTO>/authorize" \
  --header "Content-Type: application/json" \
  --max-time 110 \
  --data '{
    "operationNumber": "44992528",
    "amount": "100",
    "currency": "604",
    "paymentMethod": "QR"
  }'

Reemplaza <IP_DEL_PINPAD> y <PUERTO> 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. La respuesta de /cancel se interpreta por separado en Cancelación.

Verificar el resultado final

Conserva operationNumber; ante HTTP 202 WAITING_RESULT, timeout o incertidumbre, consulta la pasarela con GET /payments/{operationNumber}.
En una consulta 200/00, interpreta transaction.state; 00 solo indica que la operación fue encontrada.
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.
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.

Guía

Integraciones

Flujos por método

Solicitud mínima

Parámetros

Detalle de los parámetros

`operationNumber`

`amount`

`currency`

`paymentMethod`

`tollData`

Interpretación de `shiftId` para reportes

`additionalFields`

Ejemplo de autorización para peaje

Enviar la solicitud

Respuestas de autorización

Verificar el resultado final

​Flujos por método

​Solicitud mínima

​Parámetros

​Detalle de los parámetros

​operationNumber

​amount

​currency

​paymentMethod

​tollData

​Interpretación de shiftId para reportes

​additionalFields

​Ejemplo de autorización para peaje

​Enviar la solicitud

​Respuestas de autorización

​Verificar el resultado final

Flujos por método

Solicitud mínima

Parámetros

Detalle de los parámetros

`operationNumber`

`amount`

`currency`

`paymentMethod`

`tollData`

Interpretación de `shiftId` para reportes

`additionalFields`

Ejemplo de autorización para peaje

Enviar la solicitud

Respuestas de autorización

Verificar el resultado final