AI 에이전트를 위한 Stripe 결제 링크 API 구축기

내 에이전트들은 계속해서 신용카드를 요구했다.

비유적인 의미가 아니다. 나는 실제 작업을 수행하는 몇 개의 AI 에이전트를 운영하고 있다: 도메인 구매, 인증서 갱신, 테스트 인쇄 주문, API 크레딧 충전 등. 내가 살펴본 모든 에이전트 프레임워크는 결제에 대해 같은 답변을 내놓았는데, 바로 '답변 없음'이었다. 에이전트는 기쁘게 구매 계획을 작성한 다음, 가장 중요한 한 단계에서 멈춰버렸다. 왜냐하면 돈이 오가는 부분을 아무도 해결하지 못했기 때문이다.

그래서 나는 Agent Checkout™을 만들었다. 이 API 호출 하나로 실제 Stripe 결제 링크가 생성된다. 에이전트는 그 URL을 인간 운영자에게 전달한다. 인간은 클릭하고 결제한다. 에이전트는 카드 번호, CVV 또는 로그 파일에 유출할 수 있는 어떤 것도 절대 보지 못한다.

여기에 돈의 흐름(money-flow) 설계가 있다. 이것이 대부분의 사람들이 잘못 이해하는 부분이다.

핵심 규칙은 다음과 같다: 에이전트는 결코 카드 데이터에 접근해서는 안 된다. 이것은 선택 사항이 아니다. 카드 번호가 에이전트의 컨텍스트 윈도우를 통과하는 순간, 그것들은 로그, 트랜스크립트, 도구 추적(tool traces) 등 관찰 가능성 스택(observability stack)에 붙인 모든 곳에 기록된다. PCI 범위가 폭발한다. 따라서 아키텍처는 정책이 아니라 설계 자체로 에이전트를 돈으로부터 거리를 두게 유지한다.

흐름은 다음과 같이 작동한다. 에이전트가 금액, 설명 및 가맹점 식별자(merchant identifier)와 함께 API에 POST 요청을 보낸다. API는 Stripe 결제 링크를 생성하고 URL을 반환한다. 이것이 에이전트에게 노출되는 전체 인터페이스이다. 이후 에이전트의 역할은 재정적인 것이 아니라 사회적인 것이다: 그 링크를 인간 운영자에게 전달하는 것이다.

운영자 개입(Operator-in-the-loop)은 처음부터 설계에 포함된 것이지, 제가 감수해야 했던 제한 사항이 아닙니다. 인간이 사기 점검 역할을 합니다. 감독되지 않는 지출 권한을 가진 에이전트는 새벽 3시에 $4,000짜리 GPU 청구서로 끝나는 이야기입니다. 인간의 클릭은 승인 게이트이자 감사 추적(audit trail) 역할도 겸합니다. 모든 결제에는 그 의도를 가진 사람이 있습니다.

가맹점들은 자체 Stripe 계정을 연결하며, 이는 Stripe Connect OAuth를 통하거나 자체 제한된 API 키를 가져오는 방식 중 하나입니다. 자금은 가맹점에게 직접 정산됩니다. 제 서비스는 잔액을 보유하지 않으며, 지급(payouts)에 손대지 않고, 돈의 중간에 머무르지도 않습니다. 이것이 의도적인 설계였습니다. 자산 보관(Custody)은 규제상의 늪이며 저는 그곳에 발을 담글 관심이 없습니다. 플랫폼은 Connect를 통한 애플리케이션 수수료나 고정 구독료로 수익을 창출합니다. 돈의 흐름 경로는 지루하게 유지됩니다: 고객에서 가맹점으로, 이야기는 끝입니다.

이제 디버깅 주말을 아껴줄 부분에 대해 말씀드리겠습니다: 웹훅 검증(webhook verification).

Stripe는 모든 웹훅에 엔드포인트별로 고유한 비밀 키를 사용하여 서명합니다. checkout.session.completed 이벤트가 도착하면, 그 내용을 믿기 전에 반드시 서명을 검증해야 합니다. 이것이 중요한 이유는 에이전트가 시스템에서 가장 신뢰할 수 없는 행위자이기 때문입니다. 악의적이라서가 아닙니다. 에이전트는 환각(hallucinate)을 일으킵니다. 구매를 완료하고 싶어 하는 에이전트는 때때로 이미 완료되었다고 보고할 것입니다. 유일한 진실의 원천은 서명된 웹훅이거나, Stripe API에서 세션 객체를 서버 측에서 가져오는 것입니다. 에이전트가 보고하는 상태는 절대 신뢰하지 마십시오. 서명을 신뢰하십시오.

제가 겪었던 몇 가지 구체적인 사항들:

• 링크 생성 시 Idempotency keys: 에이전트는 재시도합니다. 네트워크는 불안정합니다. Idempotency key가 없으면, 하나의 논리적 구매가 세 개의 결제 링크와 세 개의 동일한 $14.98 청구서를 보고 당황하는 인간을 만듭니다. 모든 create 호출에 클라이언트가 생성한 idempotency key를 전달하고 중복 시 기존 링크를 반환하십시오.
• 모든 링크의 만료 기한(Expiry): 기본값은 24시간입니다. 열려 있는 결제 링크는 누군가의 머릿속에 떠 있는 열린 탭과 같습니다. 이를 만료시키고, 에이전트가 설명할 수 있는 깔끔한 '만료됨' 상태를 제공하십시오:

메타데이터(Metadata)는 기억이 아닙니다. 주문 컨텍스트(에이전트가 무엇을 구매했는지, 어떤 실행인지, 어떤 운영자가 사용했는지 등)를 결제 링크의 Stripe 메타데이터 필드에 넣어주세요. 웹훅(webhook)이 6시간 후에 발생할 때, 이 메타데이터가 결제를 에이전트의 작업과 다시 연결하는 방법입니다. 에이전트는 잊습니다. 메타데이터는 잊지 않습니다.

이것이 저를 llms.txt로 이끌었습니다. 왜냐하면 에이전트를 위한 API는 에이전트가 실제로 읽을 수 있는 문서화가 필요하기 때문입니다.

Stripe의 문서는 인간을 위해 작성되었으며, 인간에게는 매우 훌륭합니다. 하지만 귀하의 API를 사용하는 에이전트는 웹 브라우징을 하지 않습니다. 파일 하나를 가져와서 전체 계약 내용을 기대합니다. 제 llms.txt는 4KB 미만이며 기본 URL, 중요한 단일 엔드포인트(create link), 입출력의 정확한 JSON 형태, 각 오류 코드의 의미가 담긴 오류 코드 목록, 그리고 완전한 curl 예제를 포함하고 있습니다. 마케팅 글은 없습니다. 시작하기 가이드 같은 서사도 없습니다. 에이전트는 귀하의 창립 이야기에 관심이 없습니다. 필드 이름에 관심이 있습니다.

제가 지키고 싶은 세 가지 관행이 있습니다:

1. 단일 파일, 단일 계약(One file, one contract). 에이전트가 API를 호출하는 데 필요한 모든 것이 llms.txt 안에 있어야 합니다. 만약 에이전트가 요청을 구성하기 위해 세 개의 링크를 따라가야 한다면, 당신은 실패한 것입니다.

2. 설명보다 예제(Examples over explanations). 전체 요청과 전체 응답은 인증에 대한 단락보다 더 빠르게 가르칩니다. 200 코드를 보여준 다음, 400 코드를 보여주세요.

3. API와 함께 버전 관리하기(Version it with the API). llms.txt는 복사본이 아니라 코드입니다. 요청 형태가 변경되면 파일은 동일한 커밋에서 변경되어야 합니다. 오래된 llms.txt는 아예 없는 것보다 더 나쁩니다. 왜냐하면 에이전트는 자신 있게 이전 형태를 전송할 것이기 때문입니다.

무료 등급(free tier)은 카드 필요 없이 하루 100개의 링크가 제공됩니다. 왜냐하면 에이전트를 구축하는 사람들은 실험하고 있으며, 실험은 저렴해야 하기 때문입니다. MCP 서버는 오직 하나의 도구, create_checkout_link만을 노출합니다. 왜냐하면 이것이 필요한 모든 것이 단일 도구이기 때문입니다.

제가 아직 해결하지 못한 부분은 다음과 같습니다: 에이전트가 링크를 생성했는데 사람이 절대 클릭하지 않으면 어떻게 되어야 하는가? 저는 오늘 24시간 후에 만료되도록 설정했지만, 이것이 올바른 답이라고 확신할 수 없습니다. 혹시 '클릭되지 않은 링크' 문제에 대한 좋은 패턴(예: 알림 기능, 이탈 피드백을 에이전트의 플래너에 통합하는 방식 등)을 보셨다면, 진심으로 듣고 싶습니다.

직접 사용해 보세요: https://checkout.ignitionfoundry.com — 무료 티어, 하루 100개 링크 생성 가능, 카드 불필요. MCP 서버(하나의 도구, create_checkout_link)는 https://github.com/oidsdev/agent-checkout-mcp에서 확인할 수 있습니다.