Solicitud de autorización - Alignet Integration Docs

El sistema central del comercio inicia un pago mediante una solicitud HTTP a Pay-me PinPAD. POST /authorize es síncrono: la conexión permanece abierta mientras el terminal procesa la operación y devuelve el resultado.

POST /authorize
Content-Type: application/json

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

http://<IP_DEL_PINPAD>:<PUERTO>/authorize

Solicitud mínima

Envía los cuatro campos obligatorios en el cuerpo JSON:

{
  "operationNumber": "44992528",
  "amount": "100",
  "currency": "604",
  "paymentMethod": "QR"
}

Parámetros

Campo	Tipo JSON	Obligatorio	Validación	Descripción
`operationNumber`	String	Sí	Cadena numérica de 1 a 64 dígitos.	Identificador único generado por el sistema central. Se utiliza como clave de idempotencia y referencia de consulta.
`amount`	String	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`	String	Sí	Cadena numérica de exactamente 3 dígitos.	Código numérico ISO 4217 de la moneda. Para soles peruanos, envía `"604"`.
`paymentMethod`	String	Sí	Debe contener un único valor: `CARD` o `QR`.	Método con el que Pay-me PinPAD procesará el pago.
`additionalFields`	Object	No	Todos los valores deben ser String.	Información complementaria asociada al pago.

Respeta los nombres, los tipos JSON y el uso de mayúsculas 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 entre 1 y 64 dígitos;
contener únicamente caracteres del 0 al 9;
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. Utilízala para consultar la operación o para 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 String. No utilices números JSON, valores decimales, signos, espacios ni separadores.

`currency`

Envía currency como un String de tres dígitos que contenga el código numérico ISO 4217 de la moneda. Para pagos en soles peruanos, utiliza "604". Confirma con Alignet cualquier moneda distinta de PEN antes de habilitarla en producción.

`paymentMethod`

Envía exactamente uno de los siguientes valores en mayúsculas:

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", variantes como card o qr, ni valores diferentes de los documentados.

`additionalFields`

Utiliza additionalFields para asociar información complementaria al pago. Cada valor del objeto debe ser una cadena:

{
  "additionalFields": {
    "plate": "ABC-123",
    "tollPointId": "PEAJE-01",
    "laneId": "VIA-03"
  }
}

No envíes números, booleanos, arreglos, objetos anidados ni valores null dentro de additionalFields. Si no necesitas enviar información adicional, omite el objeto.

El catálogo de claves admitidas y el uso de cada valor por el procesador están pendientes de validación con Alignet. Las claves del ejemplo son ilustrativas y no representan un catálogo obligatorio.

Ejemplo con información adicional

El siguiente ejemplo incluye additionalFields con valores String:

{
  "operationNumber": "20260827000001",
  "amount": "1500",
  "currency": "604",
  "paymentMethod": "QR",
  "additionalFields": {
    "plate": "ABC-123",
    "tollPointId": "PEAJE-01",
    "laneId": "VIA-03"
  }
}

Enviar la solicitud

Este ejemplo envía una solicitud mínima:

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

Errores de validación

Una solicitud con campos ausentes o valores inválidos devuelve HTTP 400 con resultCode: "BAD_REQUEST". Este resultado indica un error en la solicitud y no un rechazo financiero.

{
  "status": "ERROR",
  "resultCode": "BAD_REQUEST",
  "resultMessage": "amount inválido: debe ser un entero positivo en unidades menores"
}

Corrige el campo indicado antes de reenviar la solicitud. Conserva el error y el intento en los registros del sistema central para mantener la trazabilidad.

Antes de producción

Confirma las monedas y medios de pago habilitados, el catálogo de additionalFields, el timeout definitivo y el comportamiento de una referencia reutilizada con otro body. Consulta el registro centralizado de Datos por validar. Hasta confirmar el último punto, reenvía exactamente el mismo cuerpo cuando no hayas recibido el resultado. Para consultar su estado, utiliza el operationNumber original.

Lista de verificación

Antes de enviar la solicitud, verifica lo siguiente:

operationNumber está almacenado, es único y contiene únicamente entre 1 y 64 dígitos.
amount es un String numérico de hasta 12 dígitos que representa un entero positivo en unidades menores.
currency es un String numérico de exactamente tres dígitos.
paymentMethod está presente y contiene exactamente un valor: CARD o QR, en mayúsculas.
Todos los valores de additionalFields, si envías el objeto, son cadenas.
La solicitud utiliza Content-Type: application/json.
El timeout del cliente HTTP es el acordado para el ambiente.

Respuestas, consulta y códigos

Implementa los códigos HTTP, los estados y la consulta de operaciones.

​Solicitud mínima

​Parámetros

​Detalle de los parámetros

​operationNumber

​amount

​currency

​paymentMethod

​additionalFields

​Ejemplo con información adicional

​Enviar la solicitud

​Errores de validación

​Antes de producción

​Lista de verificación

Respuestas, consulta y códigos

Solicitud mínima

Parámetros

Detalle de los parámetros

`operationNumber`

`amount`

`currency`

`paymentMethod`

`additionalFields`

Ejemplo con información adicional

Enviar la solicitud

Errores de validación

Antes de producción

Lista de verificación