Stripe Payment Intents API 이해하기

Stripe Payment Intents API 이해하기

고객이 결제 버튼을 눌렀다고 해서 결제가 바로 끝나지 않아요. 3D Secure 인증이 필요하거나, 결제 수단이 실패해서 다른 카드를 쓰는 일처럼 중간 단계가 많죠. Stripe의 Payment Intents API는 이렇게 복잡한 결제 흐름을 상태가 바뀌어 가며 추적하는 결제 객체(PaymentIntent) 로 표현해요. 이 페이지에서는 PaymentIntent를 만들고, 확인(confirm)하고, 완료되는 흐름을 공식 문서 기준으로 풀어요.

출처: Stripe 공식 문서 — The Payment Intents API

PaymentIntent란

PaymentIntent는 고객이 지금 결제하려는 의도를 나타내는 객체예요. 보통 애플리케이션의 '장바구니 하나' 또는 '고객 세션 하나'에 대응하며, 지원할 결제 수단(payment methods), 받을 금액(amount), 통화(currency) 같은 거래 정보를 담아요. 이 객체는 PaymentIntent의 수명주기(lifecycle)에 따라 상태가 계속 변해서, 결제가 어디쯤 왔는지를 보여줘요.

생성과 확인 (create & confirm)

Payment Intents 기반 통합에는 두 가지 핵심 동작이 있어요.

  1. 생성 (create) — 서버에서 PaymentIntent를 만들어요. 예를 들어 10.99 USD를 받는 PaymentIntent는 amount와 currency를 지정해 POST https://api.stripe.com/v1/payment_intents로 생성해요.
  2. 확인 (confirm) — 고객이 결제할 의도가 있고 현재 결제 수단을 쓰겠다는 것을 Stripe에 알리는 동작이에요. confirm하면 PaymentIntent는 결제 시작을 시도해요.
curl https://api.stripe.com/v1/payment_intents \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d amount=1099 \
  -d currency=usd

생성 시점과 모범 사례

  • 금액을 아는 순간 생성 — 고객이 체크아웃을 시작할 때처럼 금액을 알게 되면 바로 PaymentIntent를 만들어 구매 유입(purchase funnel)을 추적해요.
  • 같은 장바구니/세션이면 재사용 — 체크아웃이 중단됐다 재개되면 새로 만들지 말고 기존 PaymentIntent를 재사용해요. PaymentIntent는 고유한 ID를 가지니 애플리케이션 데이터 모델의 장바구니/세션에 저장해 두면 필요할 때 retrieve로 꺼낼 수 있어요. 재사용하면 객체 상태가 같은 장바구니의 결제 실패 시도를 계속 추적해 줘요.
  • 멱등성 키 (idempotency key) — 같은 구매에 대해 중복 결제 의도가 생기지 않도록 멱등성 키를 제공해요. 보통 장바구니/고객 세션 ID를 기반으로 만들어요.

client secret — 클라이언트로 전달

PaymentIntent에는 결제 의도마다 고유한 client secret이 있어요. 이 비밀 키는 클라이언트(Stripe.js)가 결제를 완료할 때 써요. 서버에서 변조할 수 없는 정당한 요청만 처리하도록, stripe.confirmCardPayment나 stripe.handleCardAction 같은 함수의 인자로 전달돼요.

client secret은 결제 진행을 완료하는 데만 쓸 수 있고, status·amount·currency 같은 중요한 필드는 열어 주지만 metadata·customer 같은 민감한 필드는 감춰요. 주의점으로, 로그에 남기거나 URL에 넣거나 고객 외 다른 사람에게 노출하지 말아요.

전달 방법은 두 가지가 대표적이에요.

  • SPA 클라이언트 — 브라우저의 fetch로 서버의 엔드포인트를 호출해 client secret을 내려받는 방식이에요. React 같은 모던 프론트엔드에서 자주 써요.
  • 서버 사이드 렌더링 — 체크아웃 폼의 data-secret 속성에 client secret을 심어 결제 시 꺼내 쓰는 방식이에요.

결제 완료 후

클라이언트가 결제를 confirm한 뒤에는 서버에서 웹훅으로 payment_intent.succeeded/실패 이벤트를 모니터링해 결제가 실제로 완료됐는지 확인하는 게 모범 사례예요. 클라이언트만 믿지 말고 서버가 이벤트를 받아 최종 상태를 확정해야 해요.

미래 결제 대비 — setup_future_usage

미래에 다시 결제를 받으려고 결제 수단을 저장하려면 생성 때 setup_future_usage 파라미터를 지정할 수 있어요. 예를 들어 off_session(고객이 자리에서 떠난 상태에서의 결제)을 위해 결제 수단을 저장하려면 이렇게 해요.

curl https://api.stripe.com/v1/payment_intents \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d amount=1099 \
  -d currency=usd \
  -d setup_future_usage=off_session

동적 명세서 설명 (dynamic statement descriptor)

기본적으로 고객의 카드 명세서(statement)에는 우리 계정의 statement descriptor가 표시돼요. 상황에 맞게 이 설명을 바꾸고 싶을 때는 statement_descriptor_suffix 파라미터를 써요. 규칙상 카드 결제에는 statement_descriptor_suffix를, 카드 외 결제에는 statement_descriptor를 써요.

더 알아보기 (Learn more)