구독 통합 가이드

​

사전 요구 사항

• Dodo Payments merchant account
• 대시보드의 Developer → API Keys에서 발급한 API key를 DODO_PAYMENTS_API_KEY에 저장
• Developer → Webhooks에서 발급한 webhook secret을 DODO_PAYMENTS_WEBHOOK_KEY에 저장
• Products에서 생성된 subscription product 하나 이상

​

API 통합

​

Checkout Session

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: 'pdt_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": "pdt_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: 'pdt_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"
}

​

Webhooks

​

Subscription 이벤트 유형

1. subscription.active — Subscription이 활성화됨
2. subscription.updated — Subscription의 필드가 변경됨
3. subscription.on_hold — 갱신 또는 플랜 변경 청구가 실패함
4. subscription.failed — Subscription 생성에 실패함(종료 상태이며 고객이 다시 구독해야 함)
5. subscription.renewed — 반복 청구가 성공함
6. subscription.past_due — 갱신에 실패하고 유예 기간이 시작됨. 고객은 past_due_ends_at까지 계속 액세스할 수 있음
7. subscription.plan_changed — 플랜이 업그레이드, 다운그레이드 또는 변경됨
8. subscription.cancelled — Subscription이 취소됨
9. subscription.expired — Subscription이 기간 종료에 도달함

​

결제 시나리오

1. subscription.active: mandate가 승인되고 subscription이 활성화됩니다.
2. payment.succeeded: 첫 번째 청구를 확인합니다. Checkout 후 2~10분 이내에 수신될 것으로 예상하세요.

1. trial 시작 시(Checkout): payment method가 승인되면 subscription.active가 한 번 발생합니다. 아직 반복 청구는 이루어지지 않습니다. 첫 실제 청구는 trial이 종료될 때까지 연기됩니다.
2. trial 종료 시: 반복 금액이 청구되고 payment.succeeded를 subscription.renewed와 함께 수신합니다.

• subscription.renewed: 각 billing cycle에서 갱신 결제가 차감될 때 발생하며, 항상 payment.succeeded와 함께 전송됩니다. 업데이트된 next_billing_date도 포함합니다.

1. Subscription 실패

• subscription.failed - mandate 생성 실패로 subscription 생성에 실패했습니다.
• payment.failed - 결제 실패를 나타냅니다.

2. Subscription 보류

• subscription.on_hold - 갱신 결제 또는 플랜 변경 청구 실패로 subscription이 보류됩니다. 비즈니스에 유예 기간이 있는 경우 실패한 갱신은 먼저 past_due(subscription.past_due)로 이동하고, 유예 기간이 종료될 때만 on_hold(또는 유예 기간 설정에 따라 cancelled)로 이동합니다. Subscription States를 참조하세요.
• Subscription이 보류되면 payment method가 업데이트될 때까지 자동으로 갱신되지 않습니다.

​

subscription.failed와 subscription.on_hold 비교

​

보류된 Subscription 처리

​

Subscription이 보류되는 경우

• 갱신 결제 실패: 잔액 부족, 만료된 카드 또는 은행 거절로 자동 갱신 청구에 실패
• 플랜 변경 청구 실패: 플랜 업그레이드/다운그레이드 중 즉시 청구에 실패
• Payment method 승인 실패: 반복 청구에 대해 payment method를 승인할 수 없음

​

보류된 Subscription 다시 활성화

1. 미납 잔액에 대한 청구 생성
2. 청구서 생성
3. 새 payment method를 사용하여 결제 처리
4. 결제가 성공하면 subscription을 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, {
  payment_method: { 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
}

# Update with new payment method
response = client.subscriptions.update_payment_method(
    subscription_id=subscription_id,
    payment_method={"type": "new", "return_url": "https://example.com/return"},
)

# For on_hold subscriptions, a charge is automatically created
if response.payment_id:
    print("Charge created for remaining dues:", response.payment_id)
    # Redirect customer to response.payment_link to complete payment

await client.subscriptions.updatePaymentMethod(subscriptionId, {
  payment_method: { 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.'
  });
}

​

Subscription 이벤트 payload 예시

​

Subscription 플랜 변경

​

Proration 옵션

​

1. prorated_immediately

• 남은 시간을 기준으로 비례 계산하여 현재 billing cycle의 사용하지 않은 부분을 크레딧으로 제공합니다. 크레딧에는 기본 플랜, 수량 및 add-on이 포함됩니다.
• 그런 다음 새 플랜, 수량 및 add-on으로 전체 주기를 청구합니다. 청구 자체에는 proration이 적용되지 않습니다.
• 순 즉시 청구액 = (새 주기 전체 금액) - (남은 비율 x 기존 주기 전체 금액). 크레딧이 더 큰 경우 차액은 향후 갱신에 사용할 subscription 범위의 크레딧으로 보관됩니다.
• trial 기간에는 사용자가 즉시 새 플랜으로 전환되며 고객에게 바로 청구됩니다.

​

2. full_immediately

• 이전 주기에 대한 크레딧 없이 새 플랜의 전체 subscription 금액을 고객에게 청구합니다.
• 업그레이드와 다운그레이드 모두 고객은 새 플랜 가격 전액을 처음부터 지불합니다.
• 기존 플랜에 남은 기간과 관계없이 전체 금액을 청구하려는 경우 유용합니다.

​

3. difference_immediately

• 고객은 기존 플랜 가격과 새 플랜 가격의 차액만 지불합니다.
• 금액은 주기의 어느 시점에 변경했는지에 따라 달라지지 않습니다. 1일에 변경하든 29일에 변경하든 동일한 업그레이드 비용이 적용됩니다.
• 업그레이드 시 고객에게 차액이 즉시 청구됩니다. 예: $30/month → $80/month = 즉시 $50 청구
• 다운그레이드 시 가격 차액은 subscription 범위의 크레딧으로 저장되어 향후 갱신에 자동 적용됩니다. 예: $50/month → $20/month = $30 크레딧 저장

​

4. do_not_bill

• 플랜 변경을 즉시 적용하지만 변경 시점에는 아무것도 청구하지 않습니다. 새 플랜, 수량 및 add-on을 즉시 사용할 수 있습니다.
• 지금 청구하지 않으므로 업그레이드 시 고객은 현재 주기의 남은 기간 동안 더 높은 플랜을 무료로 사용합니다. 다운그레이드는 이미 결제한 주기의 미사용 부분에 대한 크레딧 없이 즉시 적용됩니다.
• do_not_bill를 통해 제공된 add-on은 청구된 적이 없으므로 이후 플랜 변경 시 크레딧으로 처리되지 않습니다. 이후 변경에서는 새 add-on 수량 전체가 청구됩니다.
• 업데이트된 플랜(및 수량/add-on)은 다음 예정된 갱신 시 청구되며, 기존 billing date는 유지됩니다.

​

동작

• 이 API를 호출하면 Dodo Payments가 선택한 proration 옵션에 따라 즉시 청구를 시작합니다.
• prorated_immediately를 사용하면 업그레이드와 다운그레이드 모두 변경할 때마다 현재 주기의 미사용 부분에 대한 크레딧이 계산됩니다. 해당 크레딧이 새 주기 청구액을 초과하면 나머지가 subscription의 크레딧 잔액에 추가됩니다. 이 크레딧은 해당 subscription에만 적용되며 동일한 subscription의 향후 반복 결제를 상쇄하는 데만 사용됩니다.
• difference_immediately를 사용하면 순액은 항상 정확한 가격 차액입니다. 다운그레이드의 초과 금액은 prorated_immediately와 동일하게 subscription 범위의 크레딧으로 저장됩니다.
• full_immediately 옵션은 크레딧 계산을 건너뛰고 새 플랜의 전체 금액을 청구합니다.
• do_not_bill 옵션은 변경을 즉시 적용하지만 청구를 다음 갱신일로 연기하며, 기존 갱신일은 유지됩니다.

​

청구 처리

• 플랜 변경 시 시작되는 즉시 청구는 일반적으로 2분 이내에 처리가 완료됩니다.
• 어떤 이유로든 즉시 청구에 실패하면 문제가 해결될 때까지 subscription이 자동으로 보류됩니다.

​

On-Demand Subscriptions

​

Subscription Billing에 대해 알아야 할 주요 사항

​

관련 API Reference