Stripe 커넥터
Stripe 커넥터
Stripe 계정을 Tajo를 통해 Brevo에 연결하여 완전한 결제 데이터 동기화, 구독 라이프사이클 관리, 매출 기반 마케팅 자동화를 구현하세요.
개요
| 속성 | 값 |
|---|---|
| 플랫폼 | Stripe |
| 카테고리 | 이커머스 |
| 설정 난이도 | 쉬움 |
| 공식 통합 | 예 |
| 동기화되는 데이터 | 고객, 결제, 구독, 인보이스, 이벤트 |
| API 기본 URL | https://api.stripe.com/v1 |
주요 기능
- 고객 동기화 - 메타데이터를 포함한 Stripe 고객을 Brevo 연락처와 동기화합니다
- 결제 추적 - 성공한 결제, 환불, 실패한 청구를 추적합니다
- 구독 관리 - 리텐션 캠페인을 위해 구독 라이프사이클 이벤트를 동기화합니다
- 인보이스 데이터 - 구매 후 및 갱신 자동화를 위해 인보이스 세부 정보를 동기화합니다
- 매출 기여도 - 고객 평생 가치와 MRR을 Brevo 속성에 매핑합니다
- 웹훅 이벤트 - 모든 결제 활동에 대한 실시간 이벤트 알림
- 다중 통화 지원 - 여러 통화에 걸친 결제를 처리합니다
- 결제 세션 추적 - 이탈 결제 복구를 위해 Stripe Checkout을 추적합니다
사전 준비 사항
시작하기 전에 다음 사항이 준비되어 있어야 합니다.
- API 액세스가 가능한 Stripe 계정
- Stripe API 키 (publishable 및 secret 키)
- API 액세스가 가능한 Brevo 계정
- Tajo 계정
인증
API 키 인증
Stripe는 secret API 키를 사용한 bearer token 인증을 사용합니다.
curl https://api.stripe.com/v1/customers \ -u sk_live_YOUR_SECRET_KEY:API 키 보안
secret 키를 클라이언트 측 코드에 절대 노출하지 마세요. 프론트엔드 작업에는 publishable 키를, 서버에서만 secret 키를 사용하세요.
제한된 API 키
보안 강화를 위해 특정 권한을 가진 제한된 키를 생성하세요.
- Stripe Dashboard > Developers > API Keys로 이동합니다
- “Create restricted key”를 클릭합니다
- Tajo가 필요로 하는 권한만 부여합니다
필수 권한
customers: readcharges: readpayment_intents: readsubscriptions: readinvoices: readevents: readproducts: readprices: 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_SOURCEAPI 엔드포인트
핵심 엔드포인트
| Method | 엔드포인트 | 설명 |
|---|---|---|
GET | /v1/customers | 모든 고객 목록 조회 |
POST | /v1/customers | 고객 생성 |
GET | /v1/customers/{id} | 고객 조회 |
POST | /v1/customers/{id} | 고객 업데이트 |
GET | /v1/charges | 모든 청구 목록 조회 |
GET | /v1/payment_intents | payment 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_end | 3일 후 체험 종료 | 체험 전환 캠페인 |
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 Stripeawait tajo.connectors.connect('stripe', { secretKey: process.env.STRIPE_SECRET_KEY, webhookSecret: process.env.STRIPE_WEBHOOK_SECRET});고객 동기화 실행
// Full historical syncawait tajo.connectors.sync('stripe', { type: 'full', resources: ['customers', 'subscriptions', 'payments'], since: '2023-01-01'});
// Check sync statusconst 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연결 테스트
tajo connectors test stripe# ✓ API connection successful# ✓ Customers readable# ✓ Subscriptions readable# ✓ Payments readable# ✓ Webhook endpoint verified모범 사례
- 제한된 API 키 사용 - 최소 필요 권한을 가진 키를 생성하세요
- 항상 웹훅 서명 검증 - 위조된 웹훅 이벤트를 방지하세요
- 멱등성 처리 - Stripe 이벤트 ID를 사용해 중복 처리를 방지하세요
- 고객 메타데이터 동기화 - 마케팅 관련 데이터를 Stripe 메타데이터 필드에 저장하세요
- 웹훅 전송 모니터링 - Stripe Dashboard에서 실패한 전송을 확인하세요
- 먼저 test mode 사용 - Stripe test mode 및 test clocks로 통합을 검증하세요
보안
- API 키 인증 - 제한된 키 지원을 포함한 secret 키 기반 액세스
- 웹훅 서명 검증 - HMAC SHA-256 서명 검증
- TLS 암호화 - 모든 API 통신은 HTTPS로 암호화됩니다
- PCI 규정 준수 - Stripe가 결제 데이터에 대한 PCI DSS 규정 준수를 처리합니다
- IP 화이트리스트 - API 액세스를 위한 선택적 IP 제한