구독 통합 가이드

​

전제 조건

• Dodo Payments 상인 계정
• 대시보드에서 API 자격 증명 (API 키 및 웹훅 비밀 키)

​

API 통합

​

체크아웃 세션

import DodoPayments from 'dodopayments';

const client = new DodoPayments({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'test_mode', // defaults to 'live_mode'
});

async function main() {
  const session = await client.checkoutSessions.create({
    product_cart: [
      { product_id: 'prod_subscription_monthly', quantity: 1 }
    ],
    // Optional: configure trials for subscription products
    subscription_data: { trial_period_days: 14 },
    customer: {
      email: 'subscriber@example.com',
      name: 'Jane Doe',
    },
    return_url: 'https://example.com/success',
  });

  console.log(session.checkout_url);
}

main();

import os
from dodopayments import DodoPayments

client = DodoPayments(
    bearer_token=os.environ.get("DODO_PAYMENTS_API_KEY"),
    environment="test_mode",  # defaults to "live_mode"
)

session = client.checkout_sessions.create(
    product_cart=[
        {"product_id": "prod_subscription_monthly", "quantity": 1}
    ],
    subscription_data={"trial_period_days": 14},  # optional
    customer={
        "email": "subscriber@example.com",
        "name": "Jane Doe",
    },
    return_url="https://example.com/success",
)

print(session.checkout_url)

const response = await fetch('https://test.dodopayments.com/checkouts', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${process.env.DODO_PAYMENTS_API_KEY}`
  },
  body: JSON.stringify({
    product_cart: [
      { product_id: 'prod_subscription_monthly', quantity: 1 }
    ],
    subscription_data: { trial_period_days: 14 }, // optional
    customer: {
      email: 'subscriber@example.com',
      name: 'Jane Doe'
    },
    return_url: 'https://example.com/success'
  })
});

if (!response.ok) {
  throw new Error(`HTTP error! status: ${response.status}`);
}

const session = await response.json();
console.log(session.checkout_url);

​

API 응답

{
  "session_id": "cks_Gi6KGJ2zFJo9rq9Ukifwa",
  "checkout_url": "https://test.checkout.dodopayments.com/session/cks_Gi6KGJ2zFJo9rq9Ukifwa"
}

​

웹훅

​

구독 이벤트 유형

1. subscription.active - 구독이 성공적으로 활성화되었습니다.
2. subscription.updated - 구독 개체가 업데이트되었습니다 (필드가 변경될 때마다 발생합니다).
3. subscription.on_hold - 갱신 실패로 인해 구독이 보류 상태로 전환됩니다.
4. subscription.failed - mandate 생성 실패로 인해 구독 생성에 실패했습니다.
5. subscription.renewed - 다음 청구 기간을 위해 구독이 갱신되었습니다.

​

결제 시나리오

1. subscription.active - 구독 활성화를 나타냅니다
2. payment.succeeded - 최초 결제를 확인합니다:
   • 즉시 청구(무료 체험 0일)의 경우: 2~10분 이내에 예상됩니다
   • 무료 체험 기간이 있는 경우: 해당 기간이 끝날 때
3. subscription.renewed - 다음 주기의 결제 차감 및 갱신을 나타냅니다. (기본적으로 구독 상품에 대한 결제가 이루어질 때마다 subscription.renewed 웹훅과 함께 payment.succeeded 웹훅이 전송됩니다)

1. 구독 실패

• subscription.failed - mandate 생성 실패로 인해 구독 생성이 실패했습니다.
• payment.failed - 결제 실패를 나타냅니다.

2. 구독 보류

• subscription.on_hold - 갱신 결제 또는 요금제 변경 요금 실패로 인해 구독이 보류 상태가 됩니다.
• 구독이 보류 상태가 되면 결제 수단이 업데이트될 때까지 자동 갱신되지 않습니다.

​

구독 보류 처리

​

구독이 보류 상태가 되는 경우

• 갱신 결제 실패: 자동 갱신 요금이 자금 부족, 카드 만료 또는 은행 거부로 인해 실패합니다.
• 요금 변경 실패: 요금 업그레이드/다운그레이드 중 즉시 요금이 실패합니다.
• 결제 방법 승인 실패: 결제 방법이 반복 청구를 위해 승인될 수 없습니다.

​

보류 상태에서 구독 재활성화

1. 남은 금액에 대한 청구를 생성합니다
2. 해당 청구에 대한 인보이스를 생성합니다
3. 새 결제 수단으로 결제를 처리합니다
4. 결제가 성공하면 구독을 active 상태로 다시 활성화합니다

// Webhook handler
app.post('/webhooks/dodo', async (req, res) => {
  const event = req.body;
  
  if (event.type === 'subscription.on_hold') {
    const subscription = event.data;
    
    // Update subscription status in your database
    await updateSubscriptionStatus(subscription.subscription_id, 'on_hold');
    
    // Notify customer to update payment method
    await sendEmailToCustomer(subscription.customer_id, {
      subject: 'Payment Required - Subscription On Hold',
      message: 'Your subscription is on hold. Please update your payment method to continue service.'
    });
  }
  
  res.json({ received: true });
});

// Update with new payment method
const response = await client.subscriptions.updatePaymentMethod(subscriptionId, {
  type: 'new',
  return_url: 'https://example.com/return'
});

// For on_hold subscriptions, a charge is automatically created
if (response.payment_id) {
  console.log('Charge created for remaining dues:', response.payment_id);
  // Redirect customer to response.payment_link to complete payment
}

await client.subscriptions.updatePaymentMethod(subscriptionId, {
  type: 'existing',
  payment_method_id: 'pm_abc123'
});

if (event.type === 'payment.succeeded') {
  const payment = event.data;
  
  // Check if this payment is for an on_hold subscription
  if (payment.subscription_id) {
    // Wait for subscription.active webhook to confirm reactivation
  }
}

if (event.type === 'subscription.active') {
  const subscription = event.data;
  
  // Update subscription status in your database
  await updateSubscriptionStatus(subscription.subscription_id, 'active');
  
  // Restore customer access
  await restoreCustomerAccess(subscription.customer_id);
  
  // Notify customer of successful reactivation
  await sendEmailToCustomer(subscription.customer_id, {
    subject: 'Subscription Reactivated',
    message: 'Your subscription has been reactivated successfully.'
  });
}

​

샘플 구독 이벤트 페이로드

​

구독 요금 변경

​

비례 배분 옵션

​

1. prorated_immediately

• 현재 청구 주기에 남은 시간을 기준으로 일할 계산액을 산정합니다
• 이전 요금제와 새 요금제의 차액만 고객에게 청구합니다
• 체험 기간에는 사용자를 즉시 새 요금제로 전환하고 고객에게 바로 요금을 청구합니다

​

2. full_immediately

• 새 요금제에 대해 전체 구독 요금을 청구합니다
• 이전 요금제의 남은 시간이나 크레딧을 무시합니다
• 청구 주기를 재설정하거나 일할 계산과 관계없이 전체 금액을 청구하려는 경우 유용합니다

​

3. difference_immediately

• 업그레이드할 때 고객은 두 요금제 금액의 차액을 즉시 청구받습니다.
• 예를 들어 현재 요금제가 30달러이고 고객이 80달러로 업그레이드하면 즉시 $50이 청구됩니다.
• 다운그레이드할 때 현재 요금제에서 사용되지 않은 금액은 내부 크레딧으로 추가되어 향후 구독 갱신에 자동 적용됩니다.
• 예를 들어 현재 요금제가 50달러이고 고객이 20달러 요금제로 전환하면 남은 $30이 크레딧으로 적립되어 다음 청구 주기에 사용됩니다.

​

동작

• 이 API를 호출하면 Dodo Payments가 선택한 일할 계산 옵션에 따라 즉시 청구를 시작합니다
• 요금제 변경이 다운그레이드이고 prorated_immediately를 사용하는 경우 크레딧이 자동으로 계산되어 구독의 크레딧 잔액에 추가됩니다. 이 크레딧은 해당 구독에만 적용되며 동일한 구독의 향후 반복 결제를 상쇄하는 용도로만 사용됩니다
• full_immediately 옵션은 크레딧 계산을 건너뛰고 새로운 요금제 금액 전체를 청구합니다

​

청구 처리

• 요금 변경 시 즉시 시작된 청구는 보통 2분 이내에 처리됩니다.
• 이 즉시 청구가 어떤 이유로든 실패하면 구독은 문제가 해결될 때까지 자동으로 보류 상태로 전환됩니다.

​

주문형 구독

​

관련 API 참고 문서