Stripe 커넥터

Stripe 커넥터

Stripe 계정을 Tajo를 통해 Brevo에 연결하여 완전한 결제 데이터 동기화, 구독 라이프사이클 관리, 매출 기반 마케팅 자동화를 구현하세요.

개요

속성
플랫폼Stripe
카테고리이커머스
설정 난이도쉬움
공식 통합
동기화되는 데이터고객, 결제, 구독, 인보이스, 이벤트
API 기본 URLhttps://api.stripe.com/v1

주요 기능

  • 고객 동기화 - 메타데이터를 포함한 Stripe 고객을 Brevo 연락처와 동기화합니다
  • 결제 추적 - 성공한 결제, 환불, 실패한 청구를 추적합니다
  • 구독 관리 - 리텐션 캠페인을 위해 구독 라이프사이클 이벤트를 동기화합니다
  • 인보이스 데이터 - 구매 후 및 갱신 자동화를 위해 인보이스 세부 정보를 동기화합니다
  • 매출 기여도 - 고객 평생 가치와 MRR을 Brevo 속성에 매핑합니다
  • 웹훅 이벤트 - 모든 결제 활동에 대한 실시간 이벤트 알림
  • 다중 통화 지원 - 여러 통화에 걸친 결제를 처리합니다
  • 결제 세션 추적 - 이탈 결제 복구를 위해 Stripe Checkout을 추적합니다

사전 준비 사항

시작하기 전에 다음 사항이 준비되어 있어야 합니다.

  1. API 액세스가 가능한 Stripe 계정
  2. Stripe API 키 (publishable 및 secret 키)
  3. API 액세스가 가능한 Brevo 계정
  4. Tajo 계정

인증

API 키 인증

Stripe는 secret API 키를 사용한 bearer token 인증을 사용합니다.

Terminal window
curl https://api.stripe.com/v1/customers \
-u sk_live_YOUR_SECRET_KEY:

API 키 보안

secret 키를 클라이언트 측 코드에 절대 노출하지 마세요. 프론트엔드 작업에는 publishable 키를, 서버에서만 secret 키를 사용하세요.

제한된 API 키

보안 강화를 위해 특정 권한을 가진 제한된 키를 생성하세요.

  1. Stripe Dashboard > Developers > API Keys로 이동합니다
  2. “Create restricted key”를 클릭합니다
  3. Tajo가 필요로 하는 권한만 부여합니다

필수 권한

customers: read
charges: read
payment_intents: read
subscriptions: read
invoices: read
events: read
products: read
prices: read

설정

기본 설정

connectors:
stripe:
enabled: true
secret_key: "${STRIPE_SECRET_KEY}"
webhook_secret: "${STRIPE_WEBHOOK_SECRET}"
# Data sync options
sync:
customers: true
payments: true
subscriptions: true
invoices: true
products: true
# Brevo list assignment
lists:
all_customers: 20
subscribers: 21
churned: 22

필드 매핑

Stripe 고객 데이터를 Brevo 연락처 속성에 매핑합니다.

기본 매핑

Parameter Type Description
email required
string

고객 이메일 주소 (고유 식별자)

name optional
string

고객 전체 이름, FIRSTNAME/LASTNAME으로 분할됩니다

phone optional
string

WhatsApp/SMS용 SMS 속성에 매핑됩니다

currency optional
string

고객의 기본 통화

created optional
timestamp

Stripe에서의 고객 생성 날짜

metadata optional
object

Stripe의 커스텀 key-value 메타데이터

subscriptions optional
array

활성 구독 세부 정보

balance optional
integer

고객 계정 잔액 (센트 단위)

커스텀 속성 매핑

field_mapping:
# Standard fields
email: email
name: FULLNAME
phone: SMS
# Payment metrics
total_spent: TOTAL_SPENT
payment_count: PAYMENT_COUNT
last_payment_date: LAST_PAYMENT_DATE
average_order_value: AOV
# Subscription fields
subscription_status: SUB_STATUS
plan_name: PLAN_NAME
mrr: MONTHLY_REVENUE
subscription_start: SUB_START_DATE
# Custom metadata
metadata.customer_tier: VIP_TIER
metadata.referral_source: REFERRAL_SOURCE

API 엔드포인트

핵심 엔드포인트

Method엔드포인트설명
GET/v1/customers모든 고객 목록 조회
POST/v1/customers고객 생성
GET/v1/customers/{id}고객 조회
POST/v1/customers/{id}고객 업데이트
GET/v1/charges모든 청구 목록 조회
GET/v1/payment_intentspayment intents 목록 조회

구독 엔드포인트

Method엔드포인트설명
GET/v1/subscriptions구독 목록 조회
GET/v1/subscriptions/{id}구독 조회
GET/v1/invoices인보이스 목록 조회
GET/v1/invoices/upcoming예정된 인보이스 조회
GET/v1/products제품 목록 조회
GET/v1/prices가격 목록 조회

이벤트 엔드포인트

Method엔드포인트설명
GET/v1/events이벤트 목록 조회
GET/v1/events/{id}이벤트 조회

이벤트

결제 이벤트

이벤트트리거사용 사례
payment_intent.succeeded결제 완료주문 확인
payment_intent.payment_failed결제 실패복구 이메일
charge.refunded환불 처리환불 알림
charge.dispute.created지급 거절 시작분쟁 처리

구독 이벤트

이벤트트리거사용 사례
customer.subscription.created새 구독온보딩 플로우
customer.subscription.updated플랜 변경업그레이드/다운그레이드 플로우
customer.subscription.deleted구독 취소이탈 방지
customer.subscription.trial_will_end3일 후 체험 종료체험 전환 캠페인
invoice.payment_failed구독 결제 실패미수금 이메일 시퀀스

고객 이벤트

이벤트트리거사용 사례
customer.created새 고객 추가웰컴 이메일
customer.updated고객 데이터 변경속성 동기화
customer.deleted고객 삭제정리

코드 예제

커넥터 초기화

import { TajoClient } from '@tajo/sdk';
const tajo = new TajoClient({
apiKey: process.env.TAJO_API_KEY,
brevoApiKey: process.env.BREVO_API_KEY
});
// Connect Stripe
await tajo.connectors.connect('stripe', {
secretKey: process.env.STRIPE_SECRET_KEY,
webhookSecret: process.env.STRIPE_WEBHOOK_SECRET
});

고객 동기화 실행

// Full historical sync
await tajo.connectors.sync('stripe', {
type: 'full',
resources: ['customers', 'subscriptions', 'payments'],
since: '2023-01-01'
});
// Check sync status
const status = await tajo.connectors.status('stripe');
console.log(status);
// {
// connected: true,
// lastSync: '2024-01-15T10:30:00Z',
// customersSynced: 12500,
// subscriptionsSynced: 8200,
// paymentsSynced: 45000
// }

Stripe 웹훅 처리

import Stripe from 'stripe';
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY);
app.post('/webhooks/stripe', async (req, res) => {
const sig = req.headers['stripe-signature'];
let event;
try {
event = stripe.webhooks.constructEvent(
req.body,
sig,
process.env.STRIPE_WEBHOOK_SECRET
);
} catch (err) {
return res.status(400).send(`Webhook Error: ${err.message}`);
}
// Forward to Tajo for Brevo sync
await tajo.connectors.handleWebhook('stripe', {
type: event.type,
data: event.data.object
});
res.status(200).json({ received: true });
});

요청 제한

Stripe는 다음과 같은 요청 제한을 적용합니다.

유형제한세부 사항
Live mode초당 100회 읽기 요청secret 키당
Live mode초당 100회 쓰기 요청secret 키당
Test mode초당 25회 요청secret 키당
웹훅 전송일일 100,000 이벤트엔드포인트당

요청 제한 처리

Stripe는 제한을 초과하면 429 Too Many Requests 응답을 반환합니다. 지수 백오프를 구현하세요. 대량 데이터 조회에는 자동 페이지네이션이 적용된 목록 엔드포인트를 사용하세요.

문제 해결

일반적인 문제

문제원인해결 방법
401 Unauthorized유효하지 않은 API 키Stripe Dashboard에서 secret 키를 확인하세요
웹훅 서명 실패잘못된 웹훅 시크릿Dashboard에서 웹훅 서명 시크릿을 다시 복사하세요
고객이 동기화되지 않음Stripe 고객에 이메일 없음Stripe 고객 레코드에 이메일이 설정되어 있는지 확인하세요
구독 데이터 누락불충분한 권한제한된 키 권한을 업데이트하세요
중복 이벤트웹훅 재시도 전송이벤트 ID로 멱등성을 구현하세요

디버그 모드

상세 로깅 활성화:

connectors:
stripe:
debug: true
log_level: verbose
log_webhooks: true

연결 테스트

Terminal window
tajo connectors test stripe
# ✓ API connection successful
# ✓ Customers readable
# ✓ Subscriptions readable
# ✓ Payments readable
# ✓ Webhook endpoint verified

모범 사례

  1. 제한된 API 키 사용 - 최소 필요 권한을 가진 키를 생성하세요
  2. 항상 웹훅 서명 검증 - 위조된 웹훅 이벤트를 방지하세요
  3. 멱등성 처리 - Stripe 이벤트 ID를 사용해 중복 처리를 방지하세요
  4. 고객 메타데이터 동기화 - 마케팅 관련 데이터를 Stripe 메타데이터 필드에 저장하세요
  5. 웹훅 전송 모니터링 - Stripe Dashboard에서 실패한 전송을 확인하세요
  6. 먼저 test mode 사용 - Stripe test mode 및 test clocks로 통합을 검증하세요

보안

  • API 키 인증 - 제한된 키 지원을 포함한 secret 키 기반 액세스
  • 웹훅 서명 검증 - HMAC SHA-256 서명 검증
  • TLS 암호화 - 모든 API 통신은 HTTPS로 암호화됩니다
  • PCI 규정 준수 - Stripe가 결제 데이터에 대한 PCI DSS 규정 준수를 처리합니다
  • IP 화이트리스트 - API 액세스를 위한 선택적 IP 제한

관련 리소스

Subscribe to updates

developer-docs

Drop your email or phone number — we'll send you what matters next.

AI 어시스턴트

안녕하세요! 문서에 대해 무엇이든 물어보세요.

Brevo로 무료로 시작하기