PlaceToPay API 2.30: Confirm y Cancel endpoints

Qué cambió

El 22 de junio de 2026 PlaceToPay (Evertec) publicó la API 2.30. La adición más notable es un par de acciones que faltaban en cada integración que depende de la plataforma: confirm y cancel. Ambas acciones se suman a los verbos existentes (reverse, refund, reauthorization, checkout, dispersion, process y void) y ahora son parte del enum oficial de action. Cuando un merchant envía una petición con cualquiera de los dos verbos, el gateway responde con un nuevo tipo: AUTH_CONFIRM para una confirmación exitosa y AUTH_CANCEL para una cancelación exitosa.

Los nuevos endpoints mantienen la misma estructura de petición que los desarrolladores ya conocen: un body JSON con el token de autenticación, la acción seleccionada, un internalReference que apunta a la transacción original, más campos opcionales de ipAddress y userAgent. El servicio interpreta la llamada como "realizar un reverso, re-autorización, reembolso, checkout, confirmación o cancelación sobre una transacción existente". En la práctica, la API ahora acepta un solo POST a /transactions con el enum actualizado, eliminando la llamada de confirmación separada.

Por qué importa para tu negocio

Muchos clientes de Byxel en Latinoamérica operan flujos de checkout que requieren un paso manual después de la autorización inicial. Una reserva de hotel, una pre-autorización de alquiler de carro, o una factura B2B de alto valor suelen necesitar aprobación humana antes de capturar los fondos. Antes de la API 2.30, los merchants combinaban un void con un nuevo checkout para lograr el mismo efecto, o construían máquinas de estado personalizadas que guardaban la autorización y ejecutaban un process después. Ambos enfoques sumaban latencia, aumentaban el riesgo de doble captura y forzaban a los desarrolladores a escribir workarounds que nunca se sentían limpios. La acción nativa confirm simplifica el flujo. Un merchant puede ahora retener una autorización, correr verificaciones de fraude, y solo cuando el riesgo está despejado, emitir una sola llamada confirm que convierte la retención en un pago capturado.

La acción cancel funciona en sentido contrario. Si una reserva se cancela, se levanta una alerta de fraude, o un oficial de compliance rechaza una transacción, el merchant puede ahora cancelar la autorización pendiente directamente. Esto evita el patrón costoso de hacer un void seguido de un reembolso completo, que suele generar dos entradas en el estado de cuenta del cliente y confunde los registros de auditoría. Con cancel, la transacción desaparece del lote de liquidación, manteniendo la contabilidad ordenada y reduciendo la carga administrativa del equipo de finanzas.

Para las integraciones de Byxel (Credix, Shopify Costa Rica y PaseCR) estos dos verbos abren nuevas capacidades de producto. Credix puede ofrecer líneas de crédito pre-aprobadas donde el oficial autoriza un límite, el borrower hace una compra, y la plataforma confirma el cargo solo después de una verificación manual de crédito. Los merchants de Shopify pueden presentar un botón de "pagar después" que reserva el monto hasta que la orden se revise, y luego confirmar o cancelar con una sola llamada a la API. El flujo de venta de entradas de PaseCR puede retener un asiento, correr un algoritmo de asignación, y solo confirmar el pago cuando el asiento esté asignado, reduciendo carritos abandonados.

Cómo funciona técnicamente

Cuando un pago se autoriza por primera vez, PlaceToPay devuelve un authId que representa una captura pendiente. El merchant guarda este identificador junto con el registro de la orden. Después, cuando el negocio decide avanzar, el merchant envía el mismo authId en un body con action: "confirm". El gateway valida el estado pendiente, revisa banderas de fraude, y cambia el estado de la transacción a capturada. La respuesta incluye status: "AUTH_CONFIRM" y una referencia de liquidación estándar.

Si el merchant decide abortar, el body cambia a action: "cancel". El gateway valida que la transacción siga pendiente y, si es así, la marca como cancelada. El tipo de respuesta es AUTH_CANCEL. Ambas llamadas son atómicas: o tienen éxito completo, o devuelven un error que explica por qué la transición fue rechazada (por ejemplo, la transacción ya estaba capturada).

Checklist de implementación

1. Actualizá el SDK. Descargá la última versión del cliente de PlaceToPay (v2.30). Los nuevos valores del enum ya están definidos.
2. Guardá el authId. Asegurate de que tu servicio de órdenes persista el identificador de autorización devuelto por la llamada inicial de checkout.
3. Definí las reglas de negocio. Identificá el momento exacto en tu flujo donde ocurre una aprobación manual, revisión de fraude o confirmación de inventario.
4. Llamá confirm o cancel. Usá el mismo endpoint (/transactions) con el valor de action correspondiente y el authId guardado.
5. Manejá las respuestas. Tratá AUTH_CONFIRM como captura exitosa y actualizá la orden a Pagada. Tratá AUTH_CANCEL como Cancelada y liberá el inventario reservado.
6. Registrá la transición. Guardá los payloads de petición y respuesta en el log de auditoría; son necesarios para cumplimiento PCI-DSS.
7. Probá el flujo. Corré pruebas end-to-end en el sandbox de PlaceToPay: autorizar, esperar, confirmar; autorizar, esperar, cancelar. Verificá que solo aparezca un registro de liquidación.

Próximos pasos

Si tu integración de pagos todavía depende de workarounds con void-then-checkout, estás pagando comisiones extra de procesamiento y exponiendo a tu equipo de finanzas a trabajo de conciliación evitable. Byxel puede auditar tu flujo de checkout actual, identificar dónde encajan los nuevos endpoints de confirm y cancel, e implementar los cambios con mínima interrupción del servicio.

Coordiná una revisión de integración con nuestro equipo para empezar a capturar solo las transacciones que realmente querés.