Hướng Dẫn Tích Hợp Đăng Ký

​

Điều Kiện Tiên Quyết

• Một tài khoản thương nhân Dodo Payments
• Thông tin xác thực API (khóa API và khóa bí mật webhook) từ bảng điều khiển

​

Tích Hợp API

​

Phiên Thanh Toán

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);

​

Phản Hồi API

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

​

Webhooks

​

Các Loại Sự Kiện Thuê Bao

1. subscription.active - Thuê bao được kích hoạt thành công.
2. subscription.updated - Đối tượng thuê bao đã được cập nhật (khởi động khi có bất kỳ thay đổi nào).
3. subscription.on_hold - Thuê bao bị tạm dừng do gia hạn thất bại.
4. subscription.failed - Tạo thuê bao thất bại trong quá trình tạo ủy quyền.
5. subscription.renewed - Thuê bao được gia hạn cho chu kỳ thanh toán tiếp theo.

​

Kịch Bản Thanh Toán

1. subscription.active - Chỉ định kích hoạt thuê bao
2. payment.succeeded - Xác nhận thanh toán ban đầu:
   • Đối với thanh toán tức thì (không có ngày dùng thử): Mong đợi trong vòng 2-10 phút
   • Đối với thử nghiệm: bất cứ khi nào kết thúc
3. subscription.renewed - Chỉ định khấu trừ thanh toán và gia hạn cho chu kỳ tiếp theo. (Về cơ bản, bất cứ khi nào thanh toán được khấu trừ cho các sản phẩm thuê bao, bạn sẽ nhận được webhook subscription.renewed cùng với payment.succeeded)

1. Thất Bại Thuê Bao

• subscription.failed - Tạo thuê bao thất bại do không thể tạo ủy quyền.
• payment.failed - Chỉ ra thanh toán thất bại.

2. Thuê Bao Bị Tạm Dừng

• subscription.on_hold - Thuê bao bị tạm giữ do gia hạn thất bại hoặc thay đổi kế hoạch thất bại.
• Khi một thuê bao bị tạm dừng, nó sẽ không tự động gia hạn cho đến khi phương thức thanh toán được cập nhật.

​

subscription.failed vs. subscription.on_hold

​

Xử Lý Thuê Bao Bị Tạm Dừng

​

Khi Nào Thuê Bao Bị Tạm Dừng

• Gia hạn thanh toán thất bại: Thanh toán tự động thất bại do thiếu tiền, thẻ hết hạn, hoặc bị ngân hàng từ chối
• Thay đổi kế hoạch thất bại: Thanh toán tức thì trong quá trình nâng cấp/giảm cấp kế hoạch thất bại
• Ủy quyền phương thức thanh toán thất bại: Không thể ủy quyền phương thức thanh toán cho các khoản phí định kỳ

​

Kích Hoạt Lại Thuê Bao Từ Trạng Thái Tạm Dừng

1. Tạo một phí cho các khoản ủng hộ còn lại
2. Tạo hóa đơn cho khoản phí
3. Xử lý thanh toán bằng phương thức thanh toán mới
4. Kích hoạt lại thuê bao về trạng thái active khi thanh toán thành công

// 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
}

# Update with new payment method
response = client.subscriptions.update_payment_method(
    subscription_id=subscription_id,
    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, {
  type: 'existing',
  payment_method_id: 'pm_abc123'
});

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.'
  });
}

​

Mẫu Payload sự kiện Thuê Bao

​

Thay Đổi Kế Hoạch Thuê Bao

​

Tùy Chọn Phân Bổ Chi Phí

​

1. prorated_immediately

• Tính toán số tiền phân bổ dựa trên thời gian còn lại trong chu kỳ thanh toán hiện tại
• Tính phí khách hàng chỉ cho sự khác biệt giữa kế hoạch cũ và mới
• Trong thời gian thử nghiệm, điều này sẽ chuyển người dùng ngay lập tức sang kế hoạch mới, tính phí khách hàng ngay lập tức

​

2. full_immediately

• Tính phí khách hàng toàn bộ số tiền thuê bao cho kế hoạch mới
• Bỏ qua thời gian còn lại hoặc các khoản tín dụng từ kế hoạch trước đó
• Hữu ích khi bạn muốn đặt lại chu kỳ thanh toán hoặc tính phí toàn bộ số lượng bất kể phân bổ

​

3. difference_immediately

• Khi nâng cấp, khách hàng ngay lập tức bị tính phí số tiền chênh lệch giữa hai kế hoạch.
• Ví dụ, nếu kế hoạch hiện tại là 30 Đô la và khách hàng nâng cấp lên 80 Đô la, họ sẽ bị tính phí 50 đô la ngay lập tức.
• Khi hạ cấp, số tiền còn lại không sử dụng từ kế hoạch hiện tại được thêm vào dưới dạng tín dụng nội bộ và tự động áp dụng cho các lần gia hạn thuê bao trong tương lai.
• Ví dụ, nếu kế hoạch hiện tại là 50 Đô la và khách hàng chuyển sang kế hoạch 20 Đô la, số còn lại 30 đô la sẽ được ghi nhận và sử dụng cho chu kỳ thanh toán tiếp theo.

​

Hành Vi

• Khi bạn gọi API này, Dodo Payments sẽ ngay lập tức khởi tạo một khoản phí dựa trên tùy chọn phân bổ mà bạn đã chọn
• Nếu thay đổi kế hoạch là hạ cấp và bạn sử dụng prorated_immediately, các khoản tín dụng sẽ được tự động tính toán và thêm vào số dư tín dụng của thuê bao. Các khoản tín dụng này sẽ chỉ được sử dụng để giảm các khoản thanh toán định kỳ trong tương lai của cùng một thuê bao
• Tùy chọn full_immediately sẽ bỏ qua các tính toán tín dụng và tính phí toàn bộ số lượng kế hoạch mới

​

Xử Lý Thanh Toán

• Phí tức thì khởi tạo khi thay đổi kế hoạch thường sẽ hoàn tất xử lý trong vòng chưa đến 2 phút
• Nếu phí tức thì này thất bại vì bất kỳ lý do nào, thuê bao sẽ tự động bị tạm dừng cho đến khi vấn đề được giải quyết

​

Thuê Bao Theo Nhu Cầu

​

Tham Khảo API Liên Quan