Stripe 결제 API는 어떻게 10년을 버텼나 — 설계 원칙에서 배우는 API 디자인

왜 하필 Stripe 이야기를 지금 다시 할까요?

결제 API라고 하면 우리나라 개발자들은 PG사 연동 스펙서 들여다보며 한숨 쉰 기억이 먼저 나실 거예요. XML, 인증서, 희한한 파라미터 이름들… 그러다 Stripe 문서를 처음 봤을 때의 충격을 아직 기억하시는 분들이 많죠. "아, 결제가 이렇게 깔끔하게 될 수도 있구나" 하는.

Stripe의 공식 블로그에 올라온 "결제 API의 첫 10년" 글은 Stripe가 2010년 첫 POST /v1/charges부터 2020년의 PaymentIntents까지, 어떻게 API를 진화시키면서도 하위 호환을 깨지 않았는지를 정리한 회고예요. 표면적으로는 결제 얘기지만, 본질은 "수백만 명이 쓰는 API를 10년 넘게 유지하는 방법"이에요. API를 설계하는 모든 개발자에게 울림이 있는 내용이에요.

결제 API가 세 번의 세대교체를 거친 이유

Stripe 결제 API는 크게 세 세대로 나뉘어요. 1세대 Charges API(2011)는 단순했어요. amount, currency, card 토큰을 보내면 바로 결제가 돼요. 미국 신용카드 위주였고, "한 번에 돈을 빼온다"는 단순한 모델이었거든요.

2세대 Sources API(2016)는 세계 진출이 계기였어요. 유럽의 SEPA 계좌이체, 중국의 알리페이, 독일의 Sofort처럼 신용카드가 아닌 결제 수단이 점점 늘었어요. 이들은 "당장 돈이 빠지는" 방식이 아니에요. 은행에서 승인받고, 며칠 기다려야 하고, 실패하면 환불까지 며칠 더 걸려요. 그래서 "결제 수단(source)"과 "실제 과금(charge)"을 분리하는 추상이 필요했어요.

3세대 PaymentIntents API(2018)는 유럽의 PSD2 규제가 방아쇠였어요. PSD2는 SCA(Strong Customer Authentication), 그러니까 "결제할 때 고객이 휴대폰으로 한 번 더 인증해야 함"을 법으로 강제했거든요. 이게 뭐냐면, 결제 한 번이 여러 단계를 거치는 상태 머신이 된다는 뜻이에요. requires_payment_method → requires_confirmation → requires_action → processing → succeeded 이렇게요. PaymentIntents는 이 상태를 명시적으로 드러내는 리소스예요.

블로그에서 뽑을 수 있는 API 설계 원칙들

Stripe가 강조하는 것 몇 가지를 짚어볼게요. 첫째, 멱등성(idempotency) 키. 결제는 두 번 일어나면 안 되잖아요. Stripe는 모든 POST 요청에 Idempotency-Key 헤더를 붙일 수 있게 했어요. 같은 키로 두 번 요청하면 두 번째는 첫 번째 결과를 그대로 돌려줘요. 네트워크가 끊겨서 재시도해도 중복 과금이 안 생겨요. 이 아이디어는 이제 업계 표준이 됐어요.

둘째, 버전 관리의 영리함. Stripe는 URL에 /v1/을 10년째 안 올렸어요. 대신 날짜 기반 API 버전(예: 2020-08-27)을 요청 헤더로 받아요. 각 계정은 가입 시점의 버전에 고정되고, 원할 때만 수동으로 업그레이드해요. 서버 내부에서는 버전별 변환 레이어가 있어서, 오래된 클라이언트가 최신 엔진과 대화할 수 있어요. "깨진 변경"을 절대 안 하면서도 내부를 계속 리팩터링할 수 있는 비결이에요.

셋째, 확장 필드(expand)와 부분 응답. ?expand[]=customer를 붙이면 연관 객체를 인라인으로 받아요. REST의 단점인 "N+1 요청"을 해결하면서도 기본 응답은 가볍게 유지하는 트릭이에요.

넷째, Webhook의 재시도와 서명. 결제 상태 변화를 클라이언트에 통보할 때, Stripe는 최대 3일간 지수 백오프로 재시도하고 HMAC 서명으로 위변조를 막아요. 이런 디테일이 프로덕션에서 "그냥 되는" 느낌을 만들어줘요.

업계에서 이게 얼마나 영향력 있었냐면요

Stripe의 API 스타일은 Twilio, Shopify, Plaid, Square 같은 여러 회사들의 API 설계에도 영향을 줬어요. 특히 "개발자 경험(Developer Experience, DX)을 1순위로 둔다"는 철학은 한때 업계 표어가 됐죠. 국내에서도 토스페이먼츠가 나오면서 REST 기반의 깔끔한 결제 API를 볼 수 있게 됐는데, Stripe 영향을 숨기지 않아요.

반면 어도비 결제(옛 Braintree), PayPal 구버전 API 같은 건 여전히 SOAP/XML의 흔적이 남아 있어서, 두 세대를 한 문서 안에서 섞어 쓰고 있어요. Stripe가 대단한 건, "이걸 다 갈아엎자"고 했다면 고객을 잃었을 일을 점진적 진화로 해결했다는 점이에요.

한국 개발자가 가져갈 실전 교훈

결제 연동 안 하시는 분도 챙길 게 많아요. 내 API에 날짜 기반 버저닝을 붙여볼까?, 멱등성 키를 쓰기 쉽게 SDK 레벨에서 기본값으로 제공할까?, 필드 확장 기능을 REST에 얹을까 아니면 GraphQL로 갈까? 같은 결정에서 Stripe의 10년 회고는 훌륭한 참고서가 돼요.

특히 스타트업에서 공개 API를 처음 설계하신다면, "하위 호환을 어떻게 지킬지"를 출시 전에 정해두세요. 출시 후에 바꾸려면 고객을 마이그레이션시켜야 하는데, 이게 진짜 지옥이거든요. Stripe 블로그 한 편 읽는 데 30분이면 충분한데, 거기서 배운 걸로 몇 년 치의 실수를 예방할 수 있어요.