API de Consulta

El API de Consulta permite consultar una transacción generada previamente por el API de Autorización para ecommerce. Es la forma recomendada de confirmar el estado final desde backend, especialmente en métodos asíncronos o cuando necesitas una segunda validación del resultado.

GET /charges/{merchant_code}/{merchant_operation_number}/{transaction_id}

endpoint

Pre-Producción

https://api.preprod.alignet.io/charges/{merchant_code}/{merchant_operation_number}/{transaction_id}

Producción

https://api.alignet.io/charges/{merchant_code}/{merchant_operation_number}/{transaction_id}

Usa este API para validar el resultado final de una operación desde backend. También aplica al flujo Checkout Web (Flex) como segunda validación luego de responseCallback, redirect o cualquier confirmación preliminar mostrada al usuario.

¿Qué cubre esta sección?

Validación final

Confirma desde backend si la transacción terminó en estado autorizado, pendiente, expirado, cancelado u otro estado relevante para tu negocio.

Métodos asíncronos

Es especialmente útil para QR, Transferencia Bancaria, Cuotéalo y PagoEfectivo, donde el resultado final puede cambiar luego de la autorización inicial.

Checkout Web (Flex)

Si integras Flex, usa esta consulta como segunda validación antes de cerrar la orden o marcar el pago como exitoso en tu sistema.

Conciliación y soporte

Conserva merchant_code, merchant_operation_number y transaction_id para conciliación, soporte operativo y seguimiento de reclamos.

Métodos disponibles

API de Consulta con Tarjeta

Verifica el resultado de cobros con tarjeta y realiza conciliación.

API de Consulta con Yape

Consulta el estado de pagos con Yape cuando necesitas respaldo adicional.

API de Consulta con Transferencia Bancaria

Consulta operaciones con retorno diferido o pendientes de confirmación.

API de Consulta con QR

Úsala para validar pagos QR luego del redirect o durante polling controlado.

API de Consulta con Cuotéalo

Consulta el estado actualizado de operaciones en cuotas.

API de Consulta con PagoEfectivo

Verifica operaciones que completan su confirmación fuera de la sesión inicial.

Request

Antes de consumir este endpoint, solicita tu Access Token en Autenticación.

Path

GET {{base}}/charges/{merchant_code}/{merchant_operation_number}/{transaction_id}

Campo	Descripción	Formato	Tipo
`merchant_code`	Identificador del comercio.	Cadena alfanumérica	String
`merchant_operation_number`	Número de operación registrado por el comercio.	Cadena alfanumérica	String
`transaction_id`	Identificador único de la transacción. Se usa para consultar una sola transacción dentro de una operación.	Cadena alfanumérica	String

Headers

Campo	Descripción	Valor	Tipo	Obligatorio
`Authorization`	Token de identificación creado previamente en API de Seguridad.	`Bearer {access_token}`	String	SI
`ALG-API-VERSION`	Versión del API a usar.	`1709847567`	String	SI
`payment-facilitator-code`	Identificador del Facilitador de Pago.	Cadena alfanumérica	String	NO

Authorization: Bearer {access_token}
ALG-API-VERSION: 1709847567
payment-facilitator-code: {pf_code}

Response

El orquestador responde el detalle de la operación y el listado de transacciones asociadas. Si consultas una transacción específica, la estructura es la misma y operation.transactions contendrá solo la transacción solicitada.

Operación

Campo	Descripción	Tipo	Obligatorio
`success`	Indica si el proceso se realizó correctamente. Valores esperados: `true` o `false`.	String	SI
`merchant_code`	Identificador del comercio.	String	SI
`operation`	Objeto con el detalle de la operación.	Object	SI
`operation.merchant_operation_number`	Número de pedido de la operación consultada.	String	SI
`operation.amount`	Monto total de la operación.	String	SI
`operation.currency`	Código de moneda de la operación.	String	SI
`operation.state`	Estado actual de la operación. Valores frecuentes: `REGISTRADO`, `PENDIENTE`, `AUTORIZADO`, `CANCELADO`, `EXPIRADO`, `LIQUIDADO`, `DEPOSITADO`.	String	SI
`operation.transactions`	Lista de transacciones realizadas sobre la operación. Cambia según el método de pago: Tarjeta, Transferencia Bancaria, QR, Yape, Cuotéalo, PagoEfectivo.	Array	SI

Transacción

Campo	Descripción	Tipo	Obligatorio
`operation.transactions[].transaction_id`	Identificador único de la transacción.	String	SI
`operation.transactions[].channel`	Canal en el que se realizó la transacción. Valor esperado: `ecommerce`.	String	SI
`operation.transactions[].state`	Estado actual de la transacción. Puede ser `REGISTRADO`, `PENDIENTE`, `AUTORIZADO`, `CANCELADO`, `EXPIRADO`, `LIQUIDADO` o `DEPOSITADO`.	String	SI
`operation.transactions[].state_reason`	Observación o motivo del estado.	String	SI
`operation.transactions[].amount`	Monto de la transacción.	String	SI
`operation.transactions[].currency`	Código de moneda de la transacción.	String	SI
`operation.transactions[].payment_method`	Objeto con información del método de pago usado en la transacción.	Object	SI
`operation.transactions[].payment_method.method_name`	Nombre del método de pago usado. Ejemplos: `CARD`, `BANK_TRANSFER`, `QR`, `YAPE`, `CUOTEALO`, `PAGOEFECTIVO`.	String	SI
`operation.transactions[].payment_method.method_details`	Objeto con información específica del método. Su estructura varía por flujo y se documenta en cada página de método.	Object	SI

Campos condicionales

Campo	Descripción	Tipo	Obligatorio
`operation.transactions[].payment_method.method_details.redirect_url`	URL de redirect enviada durante la autorización.	String	NO
`operation.transactions[].payment_method.method_details.callback_url`	URL de callback enviada durante la autorización.	String	NO
`operation.transactions[].continue_url`	Visible en estado `PENDIENTE`. Se usa para continuar el flujo de pago en `CARD` con redirect, `BANK_TRANSFER` y `CUOTEALO`.	String	NO
`operation.transactions[].expiration_date`	Visible en estado `PENDIENTE`. Objeto con la fecha de expiración de la transacción para `CARD` con redirect, `BANK_TRANSFER`, `PAGOEFECTIVO`, `QR` y `CUOTEALO`.	Object	NO
`operation.transactions[].expiration_date.utc_time`	Fecha de expiración en UTC.	String	NO
`operation.transactions[].expiration_date.unix_time`	Fecha de expiración en Unix time.	Integer	NO
`operation.transactions[].processor_response`	Resultado detallado del procesamiento. Visible normalmente en estados como `AUTORIZADO`, `DENEGADO` o `EXTORNADO`. Su estructura cambia según el método y debe tomarse como referencial.	Object	NO
`operation.transactions[].additional_fields`	Datos adicionales enviados durante la autorización.	Dictionary	NO

Lifecycle y meta

Campo	Descripción	Tipo	Obligatorio
`operation.transactions[].lifecycle`	Historial de estados por los que pasó la transacción.	Array	SI
`operation.transactions[].lifecycle[].state`	Estado del ciclo de vida. Valores frecuentes: `REGISTRADO`, `PENDIENTE`, `AUTORIZADO`, `EXTORNADO`, `CANCELADO`, `EXPIRADO`, `LIQUIDADO`, `DEPOSITADO`.	String	SI
`operation.transactions[].lifecycle[].date`	Objeto con la fecha del cambio de estado.	Object	SI
`operation.transactions[].lifecycle[].date.utc_time`	Fecha en UTC.	String	SI
`operation.transactions[].lifecycle[].date.unix_time`	Fecha en Unix time.	Integer	SI
`meta`	Objeto con metadatos del flujo ejecutado.	Object	SI
`meta.status`	Objeto con el resultado del flujo ejecutado.	Object	SI
`meta.status.code`	Código del resultado técnico del servicio o request. No valida si el pago fue autorizado o denegado.	String	SI
`meta.status.message_ilgn`	Lista de mensajes resultantes del flujo.	Array	SI
`meta.status.message_ilgn[].locale`	Localidad del mensaje.	String	SI
`meta.status.message_ilgn[].value`	Mensaje resultante del flujo.	String	SI

Si consultas una transacción puntual, recibirás la misma estructura de respuesta que una operación, pero operation.transactions incluirá solo la transacción solicitada.

Para validar el resultado del pago, usa operation.transactions[].state y no meta.status.code. Un meta.status.code exitoso solo indica que el servicio respondió correctamente; la transacción todavía puede estar PENDIENTE, DENEGADO, EXPIRADO u otro estado.

Recomendaciones de uso

Polling controlado

Si el método es asíncrono, consulta con intervalos razonables y evita usar polling agresivo como única estrategia.

Complemento de S2S

Si ya recibes Notificaciones, usa este API como respaldo y validación adicional, no como único origen de verdad.

Flex como segunda validación

En Checkout Web (Flex), no cierres la orden solo con el resultado visual del frontend. Confirma el estado final consultando desde backend.

Conserva identificadores

Guarda merchant_operation_number y transaction_id desde la autorización para evitar consultas ambiguas y facilitar soporte.

Siguiente paso

API de Consulta con Tarjeta

Revisa el primer flujo específico por método para aterrizar la respuesta y validaciones de negocio.

Notificaciones

Combina consulta con notificaciones S2S para confirmar estados sin depender del frontend.

Primeros pasos

Integración

Pagos

Gestión y Operaciones

Pre-Producción

Producción

¿Qué cubre esta sección?

Validación final

Métodos asíncronos

Checkout Web (Flex)

Conciliación y soporte

Métodos disponibles

API de Consulta con Tarjeta

API de Consulta con Yape

API de Consulta con Transferencia Bancaria

API de Consulta con QR

API de Consulta con Cuotéalo

API de Consulta con PagoEfectivo

Request

Path

Headers

Response

Recomendaciones de uso

Polling controlado

Complemento de S2S

Flex como segunda validación

Conserva identificadores

Siguiente paso

API de Consulta con Tarjeta

Notificaciones

Pre-Producción

Producción

​¿Qué cubre esta sección?

Validación final

Métodos asíncronos

Checkout Web (Flex)

Conciliación y soporte

​Métodos disponibles

API de Consulta con Tarjeta

API de Consulta con Yape

API de Consulta con Transferencia Bancaria

API de Consulta con QR

API de Consulta con Cuotéalo

API de Consulta con PagoEfectivo

​Request

​Path

​Headers

​Response

​Recomendaciones de uso

Polling controlado

Complemento de S2S

Flex como segunda validación

Conserva identificadores

​Siguiente paso

API de Consulta con Tarjeta

Notificaciones

¿Qué cubre esta sección?

Métodos disponibles

Request

Path

Headers

Response

Recomendaciones de uso

Siguiente paso