Stripe Connect 통합 방법: 개발자를 위한 완전 가이드

Stripe Connect는 마켓플레이스(Marketplace) 및 플랫폼 비즈니스를 구축하는 개발자들에게 가장 강력하면서도 한편으로는 위협적인 API 중 하나입니다. 플랫폼과 여러 사용자(크리에이터, 판매자, 프리랜서 등) 간에 자금이 이동해야 하는 애플리케이션을 구축하고 있다면 Stripe Connect가 필요합니다.

하지만 문서는 방대하고, 구현은 복잡하게 느껴집니다. 또한 여기서 발생하는 실수는 금전적 손실로 이어집니다.
이 가이드는 Stripe Connect를 이해하기 쉬운 단위로 나누어 귀하의 플랫폼에 정확히 어떻게 통합할 수 있는지 보여줍니다.

Stripe Connect란 무엇인가?

Stripe Connect는 플랫폼 결제 시스템입니다. 이를 통해 다음과 같은 작업이 가능합니다: 고객으로부터 결제를 받고, 플랫폼과 연결된 판매자 간에 결제 금액을 자동으로 분할하며, 여러 판매자에게 정산(Payouts)을 처리하고, 고객 관계를 직접 소유하지 않고도 마켓플레이스의 역학 관계를 관리할 수 있습니다.
DoorDash, Etsy 또는 Airbnb와 같은 앱 뒤에 있는 결제 인프라라고 생각하면 됩니다.
핵심 구성 요소: Accounts API (연결된 계정 생성 및 관리), Transfers API (계정 간 자금 이동), Payouts API (연결된 계정으로 수익 분배), 그리고 OAuth (사용자가 자신의 Stripe 계정을 연결할 수 있도록 허용).

1단계: 세 가지 계정 모델 이해하기

Stripe Connect는 세 가지 계정 유형을 제공합니다. 잘못 선택하면 나중에 코드를 리팩터링(Refactor)해야 할 수도 있습니다.

Standard Accounts (OAuth)

사용자가 자신의 Stripe 계정을 직접 생성합니다. 귀하는 OAuth를 통해 권한을 요청합니다. 귀하 측에서 수행해야 할 KYC(Know Your Customer, 고객 확인 절차)는 최소화됩니다 (Stripe가 처리합니다). 가장 적합한 경우: 판매자가 이미 확립된 비즈니스인 마켓플레이스.
const stripeAuthUrl = https://connect.stripe.com/oauth/authorize?client_id=${STRIPE_CLIENT_ID}&state=${state}&scope=read_write;

Express Accounts (완전 관리형 온보딩)

계정 생성이 간소화되어 있습니다. Stripe가 사전에 최소한의 정보만 수집하며, 나중에 추가 정보를 요청할 수 있습니다. 추천 대상: 단순한 판매자 요구 사항을 가진 플랫폼.

const account = await stripe.accounts.create({
  type: 'express',
  country: 'US',
  email: 'vendor@example.com',
  capabilities: {
    card_payments: { requested: true },
    transfers: { requested: true }
  }
});

Custom Accounts (최대 제어 권한)

모든 KYC (Know Your Customer, 고객 확인 제도) 및 인증 절차를 직접 처리해야 합니다. 결제 세부 정보를 수집하는 경우 PCI 준수 (PCI compliance)가 필요합니다. 플랫폼의 책임이 가장 큽니다. 추천 대상: 맞춤형 요구 사항이 있는 엔터프라이즈 마켓플레이스. 대부분의 개발자에게는 Express 계정이 가장 적절한 선택지입니다. 단순함과 기능성 사이의 균형이 잘 잡혀 있기 때문입니다.

Step 2: Express 계정 온보딩 설정하기

판매자가 플랫폼에 가입할 때 Express 계정을 생성합니다:

const stripe = require('stripe')(process.env.STRIPE_SECRET_KEY);

async function createConnectedAccount(vendorData) {
  const account = await stripe.accounts.create({
    type: 'express',
    country: 'US',
    email: vendorData.email,
    capabilities: {
      card_payments: { requested: true },
      transfers: { requested: true }
    },
    business_profile: {
      url: vendorData.website,
      support_email: vendorData.supportEmail
    }
  });
  await saveConnectedAccountId(vendorData.userId, account.id);
  return account.id;
}

Step 3: 온보딩을 위한 Account Link 생성하기

계정을 생성한 후, Account Link를 생성합니다. 이 링크는 판매자를 Stripe의 온보딩 흐름으로 리다이렉트합니다:

async function generateOnboardingLink(accountId, refreshUrl) {
  const accountLink = await stripe.accountLinks.create({
    account: accountId,
    type: 'account_onboarding',
    return_url: refreshUrl,
    refresh_url: refreshUrl
  });
  return accountLink.url;
}

판매자가 이 링크를 클릭하여 Stripe의 온보딩을 완료하면 다시 귀하의 앱으로 돌아오게 됩니다.

Step 4: Charge-on-Behalf를 통한 결제 처리

고객이 귀하의 플랫폼을 통해 결제할 때, charge-on-behalf를 사용하여 결제 금액을 자동으로 분할하십시오:

async function createPaymentWithSplit(amount, vendorAccountId, platformFee) {
  const charge = await stripe.charges.create({
    amount: amount,
    currency: 'usd',
    source: 'tok_visa',
    on_behalf_of: vendorAccountId,
    application_fee_amount: platformFee,
    description: 'Order payment'
  });
  return charge;
}

중요: 항상 on_behalf_of 파라미터를 사용하십시오. 이 파라미터는 Stripe가 귀하의 애플리케이션 수수료 (application fee)를 차감하면서, 해당 결제를 연결된 계정 (connected account)을 통해 처리하도록 지시합니다.

Step 5: 판매자에게 자금 이체하기 (Transferring Funds to Vendors)

고객에게 비용을 청구한 후, 판매자의 수익을 해당 계정으로 이체하십시오:

const vendorEarnings = amount * 0.8;
const platformFee = amount * 0.2;
await transferFundsToVendor(accountId, vendorEarnings, 'Order #12345 payout');

Step 6: 지급 처리하기 (Handling Payouts)

판매자가 자금을 자동으로 받는 것은 아닙니다. 판매자가 직접 지급 (payouts)을 요청하거나, 귀하가 자동 지급을 활성화할 수 있습니다:

async function enableAutomaticPayouts(accountId) {
  await stripe.accounts.update(accountId, {
    settings: {
      payouts: {
        statement_descriptor: 'Your Platform Payout',
        schedule: {
          interval: 'daily'
        }
      }
    }
  });
}

Step 7: 웹훅 구현하기 (Implementing Webhooks)

Stripe는 결제 (charges), 이체 (transfers), 계정 변경 (account changes)에 관한 이벤트를 전송합니다. 중요한 이벤트들을 수신하십시오:

app.post('/webhook', (req, res) => {
  const event = stripe.webhooks.constructEvent(
    req.body,
    req.headers['stripe-signature'],
    process.env.STRIPE_WEBHOOK_SECRET
  );

  switch(event.type) {
    case 'charge.succeeded':
      await logPayment(event.data.object);
      break;
    case 'account.updated':
      await updateVendorStatus(event.data.object.id);
      break;
  }
  res.json({received: true});
});

Stripe Connect 통합을 위한 모범 사례 (Best Practices for Stripe Connect Integration)

1. 항상 계정 ID를 저장하세요 (Always Store Account IDs): 연결된 계정 ID (connected account IDs)를 절대 다시 생성하지 마세요. 생성 직후 데이터베이스에 즉시 저장해야 합니다.
2. 멱등성 키를 구현하세요 (Implement Idempotency Keys): 요청이 실패하고 재시도될 경우 중복 결제를 방지합니다.

3. 분쟁을 처리하세요 (Handle Disputes): 연결된 계정에서 결제 분쟁 (payment disputes)이 발생할 수 있습니다. charge.dispute.created 웹훅 (webhook)을 수신하여 처리하세요.
4. 계정 상태를 검증하세요 (Validate Account Status): 결제를 처리하기 전에 charges_enabled 및 payouts_enabled 상태를 확인하세요.
5. 적절한 에러 핸들링을 구현하세요 (Implement Proper Error Handling): account_not_ready 에러와 인프라 문제 (infrastructure issues)를 구분하여 처리하세요.

실제 사례: 마켓플레이스 결제 흐름 (Real-World Scenario: Marketplace Payment Flow)

핀테크 앱 개발 (Fintech app Development) 팀이 전체 결제 흐름을 구현하는 방식은 다음과 같습니다: 고객이 주문을 넣음 → 플랫폼이 고객에게 결제 및 수수료 차감 → 웹훅 (webhook)이 결제 확인 → 플랫폼이 판매자의 수익을 이체 → 판매자가 대시보드에서 잔액 확인 → 판매자의 은행 계좌로 매일 또는 매주 자동 지급 (automatic payout) → 분쟁 처리 및 판매자에게 알림.

흔한 통합 실수 (Common Integration Mistakes)

실수 1: on_behalf_of 파라미터를 누락하는 경우. 이 파라미터가 없으면 결제 금액이 판매자가 아닌 귀하의 계정으로 들어갑니다.

실수 2: charges_enabled: false 상태를 처리하지 않는 경우. 일부 판매자는 온보딩 (onboarding)을 완료하지 않을 수 있습니다.

실수 3: 결제 직후 즉시 이체하는 경우. 웹훅 (webhook)을 사용하여 결제가 정산 (settle)될 때까지 기다리세요.

실수 4: Stripe 계정 ID를 저장하지 않는 경우. 나중에 이를 쉽게 다시 조회할 수 없습니다.

결론 (Conclusion)

Stripe Connect는 복잡하지만, 그 패턴은 일관적입니다. Express 계정을 생성하고, 판매자를 대신하여 결제하며, 수익을 자동으로 이체하고, 상태 업데이트를 위해 웹훅 (Webhooks)을 처리하며, 자동 지급 (Automatic payouts)을 활성화하는 것입니다.

한번 흐름을 이해하고 나면, 통합 (Integration)은 간단해집니다. Express 계정으로 시작하여, 적절한 에러 처리 (Error handling)를 구현하고, 웹훅 (Webhooks)을 모니터링하세요. 그러면 여러분의 마켓플레이스는 엔터프라이즈급 결제 인프라를 갖추게 될 것입니다.

가장 어려운 부분은 Stripe가 아닙니다. 구축하기 전에 플랫폼의 결제 로직을 철저히 생각하는 것입니다. 그 부분을 제대로 설정한다면, 나머지 작업은 Stripe Connect가 처리해 줄 것입니다.