Stripe API 둘러보기

Stripe API 둘러보기 (Tour of the API)

Stripe 튜토리얼의 복사-붙여넣기 코드를 넘어, 결제 객체들이 서로 어떻게 맞물리는지 이해하면 훨씬 유연한 통합을 짤 수 있어요. Stripe 공식 문서의 'API 둘러보기(Tour of the API)'는 객체 중심 설계, 상태 변화, 결제가 성공하기까지의 경로를 핵심 개념으로 설명해요. 이 페이지에서는 그 핵심 개념을 공식 문서 기준으로 정리해요.

출처: Stripe 공식 문서 — Tour of the API

핵심 개념 — 모든 것은 객체

Stripe 계정에서 일어나는 모든 것은 객체(object) 예요. 잔액은 Balance 객체, 반복 청구는 Subscription 객체, 결제 정보 저장은 PaymentMethod 객체로 표현돼요. API로 만들지 않아도 — 심지어 대시보드에서 상품을 손으로 만들거나 로우코드·노코드 통합을 해도 — 제품은 Product 객체를 만들고, 모든 게 객체로 기록돼요.

객체는 수명을 가진다 (상태 머신)

Stripe 통합은 복잡하기 때문에, API는 각 프로세스를 하나의 객체로 추적해요. 프로세스 시작 시 객체를 만들고, 매 단계마다 status를 확인해 다음에 뭘 해야 하는지 알 수 있어요. 이를 종종 상태 머신(state machine) 이라 불러요. 예를 들어 결제 중 한 결제 수단이 실패하면 requires_payment_method 상태가 "다른 수단을 제시하세요"라는 신호가 돼요. 통합은 이 객체들을 만들고 여러 상태를 거쳐 관리하는 시스템이에요.

결제 객체 (Payment objects)

결제를 받으려면 서로 연관된 여러 객체를 만들어 관리해요. 통합 방식에 따라 Checkout·Payment Links·Subscriptions·Invoicing·Payment Intents 중 우리 상황에 맞는 결제 경로와 객체를 조합해요.

결제로 가는 길 — The path to a payment

현대 Stripe 통합에서 모든 결제는 PaymentIntent 객체를 씁니다. 이름 그대로 '돈을 받으려는 의도'를 나타내며, 그 의도를 이루는 과정을 추적해요. 예를 들어 고객이 100 USD 짜리 장바구니를 들고 Check out 버튼을 누르면, 그 순간 100 USD의 PaymentIntent를 만들어 이후 과정을 추적하죠. 결제가 성공하기까지의 상태를 단순화하면 이렇게 진행돼요.

  1. 결제 수단 — PaymentIntent는 requires_payment_method 상태로 시작해요. 카드 번호나 다른 결제 시스템 자격 정보를 담은 PaymentMethod 객체가 필요해요. 통합에 따라 코드로 직접 만들 수도, Stripe가 수집해 줄 수도 있어요.
  2. 확인 (Confirmation) — 다음 상태는 requires_confirmation이에요. 대화형 결제 흐름에서 고객이 Pay 버튼을 눌러 '이 결제 수단으로 지불하겠다'는 의도를 확정하면 통합이 Stripe에 API 호출로 알려요. 대부분 confirm 시 Charge 객체가 만들어져 이번 송금 시도를 나타내요. 실패하면 같은 PaymentIntent를 새 결제 정보로 다시 confirm해 재시도할 수 있어요 — 즉시 재시도가 전환율을 높이는 경향이 있어요.
  3. 처리와 성공 (Processing and success) — 이제 상태는 processing이 되고 Stripe가 결제를 처리해요. 처리는 Stripe가 대신 맡고 (카드의 경우 '카드가 어떻게 작동하는지'의 여러 단계를 거치며) 결과에 따라 상태를 succeeded로 올리거나 실패 시 requires_payment_method로 되돌려요. 처리가 끝나면 마지막으로 Event 객체가 등장해요 — '결제 성공'이나 '결제 실패' 같은 활동을 표현하며, 어떤 통합은 웹훅으로 이 이벤트를 받아 처리해요.

더 알아보기 (Learn more)