판매자의 ACP 연동: 체크아웃 세션, 위임 토큰과 안전한 재시도

무엇인가

2026년 10월 25일 기준입니다. 이 글은 날짜가 명시된 ACP 2026-04-17 명세 스냅샷과 해당 릴리스 변경 이력을 기준으로 합니다. 연동하기 전에 합의된 API 버전, 결제 핸들러 스키마, 릴리스 노트를 다시 확인합니다. 예전 웹사이트 페이지나 저장소의 미출시 디렉터리에 있는 예제로 대체할 경우 그 사실을 명시해야 합니다.

Agentic Checkout API는 판매자에게 프로그램으로 사용하는 체크아웃 인터페이스를 제공합니다. 세션을 생성하고, 갱신하거나 조회하며, 완료하거나 취소할 수 있습니다. 판매자가 반환하는 장바구니 상태가 최종 기준이 됩니다. 에이전트는 변경을 요청하고 결과를 구매자에게 보여 줄 수 있으며, 체크아웃 금액 계산과 주문 처리는 판매자의 백엔드가 담당합니다.

왜 중요한가

체크아웃 내용에 대한 합의와 결제 자격 증명의 위임은 별도의 작업입니다. Delegate Payment API는 판매자의 결제 서비스 제공자가 제한된 범위에서 사용할 수 있도록 자격 증명을 토큰화합니다. 응답에는 보관소 토큰 식별자가 포함됩니다. 허용 범위에는 최대 금액, 통화, 체크아웃 세션 식별자, 판매자 식별자, 만료 시간이 포함되며, 문서에 명시된 사용 사유는 one_time입니다.

이 토큰은 에이전트가 자유롭게 쇼핑해도 된다는 포괄적 허가가 아닙니다. 판매자와 결제 제공자는 합의된 핸들러를 연동하고 그 제약 조건을 적용해야 합니다. 방어적인 구현 실무로서 자격 증명 수집과 토큰 발급은 전용 결제 구성 요소에서 처리하고, 모델 프롬프트와 일반 요청 로그에는 포함하지 않습니다.

적용 방법

• 세션 작업을 제공합니다. /checkout_sessions에서의 생성, 세션 리소스에서의 조회와 갱신, /complete와 /cancel 작업을 구현합니다. 현재 합계 금액, 주문 이행 정보, 메시지, 상태를 반환합니다. ready_for_payment, authentication_required, complete_in_progress, completed의 구분을 유지합니다.
• 결제 처리 방식을 합의합니다. 체크아웃에서 지원한다고 알린 핸들러를 사용하고, 해당 handler_id와 결제 수단 스키마를 사용해 완료 처리용 결제 데이터를 전송합니다. 보관소 토큰만으로는 완전한 체크아웃 요청이 되지 않습니다. 해당 결제 경로를 활성화하기 전에 제공자가 토큰을 처리할 수 있는지 확인합니다.
• 연동을 인증합니다. 보안 문서는 HTTPS와 bearer-token 인증을 명시합니다. 선택한 API 계약에 필요한 API-Version 헤더를 제공하고, 인증된 판매자와 에이전트의 관계 안에서 세션 접근 권한을 부여합니다.
• 안전한 재시도를 구현합니다. 이 릴리스에서는 POST 요청에 Idempotency-Key가 필수입니다. 같은 작업과 같은 본문에만 키를 재사용합니다. 키가 없으면 idempotency_key_required, 아직 처리 중인 요청과 중복되면 idempotency_in_flight, 같은 키로 본문을 바꾸면 idempotency_conflict가 발생합니다.
• 주문 알림을 검증합니다. 이 릴리스는 타임스탬프와 원본 본문을 대상으로 하는 Merchant-Signature webhook 인증을 정의하며, 재전송 공격을 막기 위한 타임스탬프 허용 시간 범위 검사도 포함합니다. 로컬 주문 이행 상태를 바꾸기 전에 인증된 갱신 내용을 해당 체크아웃 및 주문과 연결합니다.

함정

HTTP 요청이 성공했다고 해서 세션이 완료된 것은 아닙니다. 중단이 발생한 뒤에는 곧바로 다른 구매를 시작하기보다 운영 대사 절차를 통해 체크아웃, 결제, 주문 상태를 비교해야 합니다.

예전 문서에서는 멱등성을 선택 사항으로 설명하지만, 날짜가 명시된 이 릴리스에서는 필수입니다. 스키마 버전을 고정하고 이 규칙을 명시적으로 테스트합니다. 토큰화, 구매자 확인, 결제 승인, 주문 이행에는 각각 별도의 증거가 필요합니다. 대화에서 성공했다는 메시지가 나왔다는 이유만으로 어느 것도 추정해서는 안 됩니다.