# Stripe + Brew

Stripe 고객을 브랜드 오디언스로 동기화하고, Stripe 이벤트 22개로 자동화를 트리거하고, 미리 만들어 둔 라이프사이클 이메일(웰컴, 체험 종료, 결제 실패 복구, 윈백)을 보내세요.

정식 URL: https://brew.new/ko/browse/integrations/stripe

- 방향: 데이터 가져오기
- 연결 방식: OAuth
- 고객 동기화 + 이벤트 트리거

## 사용 가능한 기능

- **이벤트 트리거**: 구독, 인보이스, 결제 페이지, 견적, 청구, 환불, 결제 의도에 걸친 Stripe 이벤트 22개로 Brew 자동화를 트리거해요.
- **연락처 동기화**: Stripe 고객을 브랜드 오디언스로 동기화하고, `stripe_*` 사용자 지정 필드를 필터링할 수 있는 속성으로 제공해요.
- **고객 일괄 가져오기**: 클릭 한 번으로 모든 Stripe 고객을 현재 브랜드로 한꺼번에 가져와요. Vercel Workflow로 안정적으로 실행되며, 중단돼도 이어서 재개할 수 있어요.
- **라이프사이클 이메일 템플릿**: 웰컴, 체험 종료, 결제 실패 복구, 윈백을 위한 시작 템플릿이에요.

## 결제 이벤트를 유용한 이메일로 바꾸세요

OAuth로 Stripe를 연결하면 구독이 시작되거나, 체험 기간이 끝나 가거나, 인보이스 결제가 실패할 때 브랜드에 맞는 이메일을 보낼 수 있어요. Brew가 웹훅을 등록하고, 지원되는 이벤트를 자동화 트리거로 쓸 수 있게 해 줘요.

결제, 재시도, 환불, 구독 변경은 계속 Stripe가 담당해요. Brew는 이메일을 만들고 보내요.


## 만들 수 있는 것

- 체험 종료 리마인더: customer.subscription.trial_will_end 이벤트로 다음에 어떤 일이 일어나는지 안내하고, 요금제 페이지나 결제 페이지로 연결하세요.
- 결제 실패 안내: invoice.payment_failed 이벤트로 자체 결제 페이지 링크가 담긴 안내를 제때 보내세요. 같은 안내가 두 번 나가지 않도록 Stripe가 보내는 고객 이메일과 조율하세요.
- 구독자 웰컴 이메일: customer.subscription.created 또는 checkout.session.completed 이벤트에서 시작하되, 웰컴 이메일이 중복되지 않도록 트리거는 하나만 고르세요.
- 요금제 변경 이메일: customer.subscription.updated 이벤트에 previousPlan과 newPlan 필드가 포함되어 있으면 그 값을 쓸 수 있어요.
- 결제 확인: invoice.paid 이벤트는 인보이스가 결제되면 발생해요. amount, currency, invoiceNumber를 개인화 태그로 사용하세요.
- 갱신 사전 안내: invoice.upcoming 이벤트는 Stripe가 구독의 다음 인보이스를 만들기 전에 발생하며, amount와 currency를 담고 있어요. 페이로드에 갱신일은 없으니, 자세한 내용은 결제 페이지로 연결해 안내하세요.
- 해지 후속 이메일: customer.subscription.deleted 이벤트는 구독이 해지되거나 삭제되면 발생해요. 새 구독이 생겨도 이미 진행 중인 실행은 멈추지 않으니, 이후에 보내는 이메일마다 그 앞에 contact.stripe_subscription_status 조건을 추가하세요.
- 일시 중지 및 재개 안내: customer.subscription.paused와 customer.subscription.resumed 이벤트로 구독자에게 변경 사항을 확인해 줄 수 있어요.
- 지연 결제 결과: checkout.session.async_payment_succeeded와 checkout.session.async_payment_failed 이벤트는 확정까지 시간이 걸리는 결제 수단이 결제 후 최종적으로 어떻게 처리됐는지 알려 줘요. paymentStatus와 sessionMode를 개인화 태그로 쓸 수 있어요.
- 결제 이탈 리마인더: Brew에는 만료된 Checkout 세션용 트리거가 없어요. 애플리케이션에서 세션 만료를 감지하면 직접 사용자 지정 이벤트를 보내세요.
- 환불 확인: refund.created 이벤트에는 해당 환불의 refundAmount, refundCurrency, refundReason, refundStatus가 담겨 있어요. charge.refunded 이벤트에는 amountRefunded 같은 청구 단위 합계만 담겨 있어요.
- 견적 후속 이메일: quote.finalized, quote.accepted, quote.canceled 이벤트에는 견적 금액, 통화, 상태가 담겨 있어요. 견적 링크 필드는 없으니, 구매자에게는 자체 페이지를 안내하세요.
- 일회성 결제 실패: payment_intent.payment_failed 이벤트에는 failureCode, failureMessage, declineCode가 담겨 있어서, 결제가 실패한 이유를 이메일에 반영할 수 있어요.

## 현재 상태를 확인하는 결제 실패 후속 이메일

invoice.payment_failed 이벤트로 트리거되는 이메일 한 통으로 시작하세요. 이후 리마인더를 보내려면, 애플리케이션이 Stripe에서 인보이스 상태를 새로 확인하도록 예약하세요. 인보이스가 여전히 미결제이고 고객이 계속 대상에 해당할 때만 별도의 Brew 사용자 지정 이벤트를 보내세요.

대기 단계가 지난 뒤에도 이벤트 필드에는 원래 이벤트 페이로드가 그대로 들어 있어요. contact.stripe_subscription_status 조건은 해당 노드가 실행되는 시점에 Brew 연락처에 있는 필드의 현재 값을 읽어요. Stripe를 조회하거나 특정 인보이스가 결제됐음을 증명하지는 않아요. 연락처 업데이트나 새 결제 이벤트가 이전 실행을 자동으로 취소하지도 않아요. 카드를 업데이트했다고 해서 결제가 된 것도 아니에요.

두 경로를 모두 테스트하세요. 인보이스가 아직 미결제이고 여전히 대상에 해당하는 고객은 리마인더를 받고, 예약된 확인 전에 결제한 고객은 받지 않아야 해요. 재시도는 문서에 나온 멱등성 규칙에 맞춰 테스트하세요.


## Brew에서 Stripe 설정하기

- ‘연동’을 열고 Stripe를 선택한 다음 ‘연결’을 누르세요. Stripe OAuth로 접근을 승인하세요.
- Brew가 웹훅과 지원되는 이벤트 유형 22개를 프로비저닝해요. 이벤트별로 켜고 끄는 스위치는 없어요.
- 기존 고객을 가져오려면 ‘관리’를 열고 ‘Stripe에서 고객 동기화’를 선택하세요. 고객 레코드만으로는 마케팅 이메일 수신 동의가 성립하지 않아요.
- 자동화를 만들고 Stripe 이벤트를 선택하세요. 수신자, 페이로드 필드, 이메일 내용, 결제 링크를 검토하세요.
- Brew는 라이브 Stripe 계정을 연결하며, 테스트 모드 이벤트로는 연락처가 동기화되거나 자동화가 시작되지 않아요. 게시하기 전까지 자동화를 초안으로 두고, 직접 관리하는 수신자로 테스트하세요. 일치하는 이벤트가 도착하면 활성 상태인 자동화만 실행돼요.
- 권한이 있는 사람이 앱에서 Stripe 계정을 연결하고 나면, 에이전트가 Brew MCP나 API로 자동화를 만들고, 테스트하고, 게시할 수 있어요.

## 지원되는 Stripe 이벤트

Brew는 다음 이벤트 유형 22개를 지원해요:

- checkout.session.async_payment_succeeded
- checkout.session.async_payment_failed
- checkout.session.completed
- customer.created
- customer.updated
- customer.deleted
- customer.subscription.created
- customer.subscription.updated
- customer.subscription.paused
- customer.subscription.resumed
- customer.subscription.trial_will_end
- customer.subscription.deleted
- invoice.created
- invoice.paid
- invoice.payment_failed
- invoice.upcoming
- quote.finalized
- quote.accepted
- quote.canceled
- charge.refunded
- refund.created
- payment_intent.payment_failed

## 고객 동기화와 개인화

고객 이벤트와 구독 이벤트는 결제 관련 정보로 Brew 연락처를 업데이트할 수 있어요. 사용할 수 있는 연락처 필드에는 stripe_subscription_status, stripe_subscription_plan, stripe_plan_amount_cents, stripe_trial_end, stripe_renews_at, stripe_cancel_at_period_end, stripe_delinquent가 있어요. 실제로 쓸 수 있는지는 Stripe 이벤트와 받은 데이터에 따라 달라요.

개인화 태그에는 선택한 이벤트에 선언된 페이로드 스키마를 사용하세요. 이벤트에 따라 firstName, lastName, amount, currency, status, invoiceNumber, previousPlan, newPlan, failureMessage 같은 필드가 있어요. 스키마가 센트 단위로 명시한 금액은 센트 단위예요.

Stripe 객체 식별자는 자동화 페이로드에서 제거돼요. 인보이스 ID나 구독 ID를 개인화 태그로 쓸 수 있다고 가정하지 마세요. Brew는 Stripe 고객 ID도 연락처에 저장하지 않아요.

이벤트별 ‘전체 이름 동기화’ 설정은 Stripe가 연락처 이름을 업데이트할 수 있는지를 정해요. 트리거를 켜거나 끄는 설정이 아니에요.


## 고객이 결제한 뒤에 리마인더를 멈출 수 있나요?

나중에 들어온 결제 이벤트가 이전 결제 실패로 시작된 실행을 자동으로 취소하지는 않아요. 리마인더 전에 애플리케이션에서 확인하도록 예약하고, 인보이스가 아직 미결제일 때만 새 이벤트를 보내세요.


## 이벤트는 들어왔는데 이메일이 발송되지 않는 이유는 뭔가요?

이벤트 수신과 이메일 발송은 별개의 단계예요. 일치하는 자동화가 활성 상태인지 확인하고, 필터와 실행 기록을 살펴보고, 수신자가 발송 대상인지와 발신 도메인을 확인하세요. ‘전체 이름 동기화’ 설정은 이름 업데이트만 제어해요.


## 제한 사항 및 문제 해결

- Brew는 청구를 만들거나, 환불하거나, Stripe 구독을 수정할 수 없어요.
- ‘관리’의 이벤트 탭에 이벤트가 표시되는데 이메일이 오지 않는다면, 연결된 자동화가 활성 상태인지, 필터와 실행 기록, 수신자, 발신 도메인 준비 상태를 확인하세요.
- 웹훅 서명 오류가 계속되면 Stripe를 다시 연결해 새 웹훅 시크릿을 프로비저닝하세요.
- 이메일에 환불 관련 필드가 필요하면 refund.created 이벤트를 사용하고, 쓸 수 있는 필드는 트리거 스키마에서 확인하세요.
- 각 이메일의 수신 동의와 목적을 검토하세요. 결제 연락처를 가져왔다고 해서 프로모션 이메일을 보내도 되는 건 아니에요.

## 출처 및 설정 가이드

- [Stripe 라이프사이클 이메일 워크플로 만들기](/ko/blog/how-to-automate-lifecycle-emails-from-stripe-subscription-events)
- [Stripe 이메일 연동 비교](/ko/blog/best-email-marketing-tools-with-stripe-integration-subscription-events-and-automation-compared)
- [Stripe 설정 가이드](https://docs.brew.new/integrations/import/stripe)
- [자동화 만들기](https://docs.brew.new/create-emails/build-an-automation)
- [개인화 태그](https://docs.brew.new/create-emails/merge-tags)
- [Stripe 이벤트 레퍼런스](https://docs.stripe.com/api/events/types)
- [Stripe 고객 이메일 설정](https://docs.stripe.com/billing/revenue-recovery/customer-emails)

## 관련 링크

- [전체 연동](https://brew.new/ko/browse/integrations.md)
- [회원가입](https://brew.new/ko/sign-up.md)
- 웹사이트: https://brew.new