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 Đăng Ký

1. subscription.active - Đăng ký được kích hoạt thành công.
2. subscription.updated - Đối tượng đăng ký đã được cập nhật (kích hoạt khi bất kỳ trường nào thay đổi).
3. subscription.on_hold - Đăng ký bị tạm giữ do gia hạn thất bại.
4. subscription.failed - Tạo đăng ký thất bại trong quá trình tạo ủy nhiệm.
5. subscription.renewed - Đăng ký được gia hạn cho kỳ thanh toán tiếp theo.

​

Các Kịch Bản Thanh Toán

1. subscription.active - Cho biết đăng ký đã được kích hoạt
2. payment.succeeded - Xác nhận khoản thanh toán ban đầu:
   • Đối với thanh toán ngay lập tức (0 ngày dùng thử): Dự kiến trong vòng 2-10 phút
   • Đối với ngày dùng thử: ngay khi kết thúc
3. subscription.renewed - Cho biết khoản thanh toán được trừ và gia hạn cho chu kỳ tiếp theo. (Về cơ bản, bất cứ khi nào khoản thanh toán cho sản phẩm đăng ký được trừ, bạn sẽ nhận được webhook subscription.renewed cùng với payment.succeeded)

1. Thất bại Đăng ký

• subscription.failed - Tạo đăng ký thất bại do không thể tạo ủy nhiệm.
• payment.failed - Cho biết thanh toán thất bại.

2. Đăng ký bị tạm giữ

• subscription.on_hold - Đăng ký bị tạm giữ do thanh toán gia hạn thất bại hoặc phí thay đổi gói thất bại.
• Khi đăng ký bị tạm giữ, nó sẽ không tự động gia hạn cho đến khi cập nhật phương thức thanh toán.

​

Xử Lý Đăng Ký Bị Tạm Hoãn

​

Khi Nào Đăng Ký Bị Tạm Hoãn

• Thanh toán gia hạn không thành công: Phí gia hạn tự động không thành công do không đủ tiền, thẻ hết hạn hoặc ngân hàng từ chối
• Phí thay đổi kế hoạch không thành công: Một khoản phí ngay lập tức trong quá trình nâng cấp/hạ cấp kế hoạch không thành công
• Ủy quyền phương thức thanh toán không thành công: Phương thức thanh toán không thể được ủy quyền cho các khoản phí định kỳ

​

Kích Hoạt Lại Đăng Ký Từ Trạng Thái Bị Tạm Hoãn

1. Tạo một khoản phí cho số tiền còn nợ
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 đăng ký 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
}

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

​

Ví Dụ Về Payload Sự Kiện Đăng Ký

​

Thay Đổi Kế Hoạch Đăng Ký

​

Tùy Chọn Phân Bổ

​

1. prorated_immediately

• Tính toán số tiền được điều chỉnh theo tỷ lệ dựa trên thời gian còn lại trong chu kỳ thanh toán hiện tại
• Chỉ tính phí khách hàng khoản chênh lệch giữa gói cũ và mới
• Trong thời gian dùng thử, điều này sẽ chuyển người dùng sang gói mới ngay lập tức và tính phí khách hàng ngay lập tức

​

2. full_immediately

• Tính phí cho khách hàng toàn bộ số tiền đăng ký của gói mới
• Bỏ qua mọi thời gian còn lại hoặc tín dụng từ gói trước đó
• Hữu ích khi bạn muốn thiết lập lại chu kỳ thanh toán hoặc tính toàn bộ số tiền bất kể điều chỉnh theo tỷ lệ

​

3. difference_immediately

• Khi nâng cấp, khách hàng được tính ngay khoản chênh lệch giữa hai gói.
• Ví dụ, nếu gói hiện tại là 30 Dollars và khách hàng nâng cấp lên gói 80 Dollars, họ sẽ bị tính $50 ngay lập tức.
• Khi hạ cấp, số tiền chưa sử dụng từ gói hiện tại được thêm vào tín dụng nội bộ và tự động áp dụng cho các lần gia hạn đăng ký sau.
• Ví dụ, nếu gói hiện tại là 50 Dollars và khách hàng chuyển sang gói 20 Dollars, $30 còn lại sẽ được ghi có 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 lập tức bắt đầu một khoản phí dựa trên tùy chọn điều chỉnh tỷ lệ mà bạn đã chọn
• Nếu việc thay đổi gói là hạ cấp và bạn sử dụng prorated_immediately, các khoản tín dụng sẽ được tính toán và thêm vào số dư tín dụng của đăng ký. Những tín dụng này dành riêng cho đăng ký đó và chỉ được dùng để bù đắp các khoản thanh toán định kỳ trong tương lai của cùng một đăng ký
• Tùy chọn full_immediately bỏ qua việc tính toán tín dụng và tính toàn bộ số tiền của gói mới

​

Xử Lý Khoản Phí

• Khoản phí ngay lập tức được khởi động khi thay đổi kế hoạch thường hoàn tất xử lý trong chưa đầy 2 phút
• Nếu khoản phí ngay lập tức này không thành công vì bất kỳ lý do gì, đăng ký sẽ tự động bị tạm hoãn cho đến khi vấn đề được giải quyết

​

Đăng Ký Theo Yêu Cầu