Integración de comerciantes con ACP: sesiones de compra, tokens delegados y reintentos seguros

Qué es

Estado a 25 de octubre de 2026. Este artículo utiliza la versión fechada 2026-04-17 de la especificación ACP y su registro de cambios. Antes de la integración, volver a comprobar la versión de la API acordada, los esquemas de los gestores de pago y las notas de la versión. No sustituirlos de forma implícita por ejemplos de una página web anterior o del directorio de versiones no publicadas del repositorio.

La Agentic Checkout API ofrece al comerciante una interfaz programática para el proceso de compra: crear una sesión, actualizarla o consultarla, completarla o cancelarla. El estado del carrito que devuelve el comerciante es la fuente de referencia. Un agente puede solicitar cambios y presentar el resultado al comprador, mientras que el backend del comerciante se encarga de los cálculos de la compra y del procesamiento del pedido.

Por qué importa

El acuerdo sobre la compra y la delegación de credenciales de pago son operaciones distintas. La Delegate Payment API tokeniza una credencial para que el proveedor de servicios de pago del comerciante pueda usarla con restricciones. Su respuesta contiene un identificador de token de bóveda. Los límites de uso incluyen un importe máximo, la moneda, el identificador de la sesión de compra, el identificador del comerciante y el vencimiento; el motivo de uso documentado es one_time.

Este token no es un permiso general para que el agente realice compras. El comerciante y el proveedor de pagos deben integrar el gestor acordado y hacer cumplir sus restricciones. Como práctica de implementación defensiva, mantener la recopilación de credenciales y la emisión de tokens en componentes de pago específicos, fuera de los prompts del modelo y de los registros habituales de solicitudes.

Cómo aplicarlo

• Exponer las operaciones de sesión. Implementar la creación en /checkout_sessions, la consulta y las actualizaciones sobre el recurso de sesión, y las operaciones /complete y /cancel. Devolver los totales actuales, la información de preparación y entrega, los mensajes y el estado. Mantener la distinción entre ready_for_payment, authentication_required, complete_in_progress y completed.
• Acordar la gestión del pago. Utilizar el gestor anunciado por el proceso de compra y enviar los datos de pago para completar la operación con su handler_id y su esquema de instrumento. Un token de bóveda por sí solo no constituye una solicitud de compra completa. Confirmar que el proveedor puede interpretar el token antes de habilitar esa vía de pago.
• Autenticar la integración. La documentación de seguridad especifica HTTPS y autenticación mediante token de portador. Proporcionar la cabecera obligatoria API-Version conforme al contrato elegido; autorizar el acceso a la sesión dentro de la relación autenticada entre comerciante y agente.
• Implementar reintentos seguros. Esta versión exige Idempotency-Key en las solicitudes POST. Reutilizar una clave únicamente para la misma operación y el mismo cuerpo. La ausencia de la clave produce idempotency_key_required; un duplicado mientras la operación está activa produce idempotency_in_flight; un cuerpo distinto con la misma clave produce idempotency_conflict.
• Verificar las notificaciones de pedidos. La versión define la autenticación de webhooks mediante Merchant-Signature sobre la marca de tiempo y el cuerpo sin procesar, con comprobaciones de una ventana temporal para impedir ataques de repetición. Vincular las actualizaciones autenticadas con la compra y el pedido antes de cambiar el estado local de preparación y entrega.

Trampas

Una respuesta HTTP satisfactoria no implica que la sesión se haya completado. Tras una interrupción, un proceso operativo de conciliación debe comparar los estados de la compra, del pago y del pedido, en lugar de iniciar inmediatamente otra compra.

La versión fechada hace obligatoria la idempotencia, aunque la documentación anterior la describe como opcional. Fijar las versiones de los esquemas y probar esa regla expresamente. La tokenización, la confirmación del comprador, la autorización del pago y la preparación y entrega necesitan pruebas propias; ninguna debe deducirse únicamente de un mensaje de éxito en la conversación.