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: '[email protected]',
      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": "[email protected]",
        "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: '[email protected]',
      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 (xảy ra khi có bất kỳ thay đổi nào về trường).
3. subscription.on_hold - Đăng ký bị tạm hoãn do gia hạn không thành công.
4. subscription.failed - Tạo đăng ký không thành công trong quá trình tạo ủy quyền.
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 - Chỉ ra việc kích hoạt đăng ký
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 thử nghiệm): Mong đợi trong vòng 2-10 phút
   • Đối với các ngày thử nghiệm: bất cứ khi nào nó kết thúc
3. subscription.renewed - Chỉ ra việc 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 khoản thanh toán được khấu trừ cho các sản phẩm đăng ký, 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ý không thành công do không thể tạo ủy quyền.
• payment.failed - Chỉ ra thanh toán thất bại.

2. Đăng Ký Bị Tạm Hoãn

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

​

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 các khoản nợ còn lại
2. Tạo một 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 sau 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 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í cho 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ẽ ngay lập tức chuyển người dùng sang kế hoạch mới, tính phí cho 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ý cho kế hoạch mới
• Bỏ qua bất kỳ thời gian còn lại hoặc tín dụng nào 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ố tiền bất kể phân bổ

​

3. difference_immediately

• Khi nâng cấp, khách hàng sẽ ngay lập tức bị tính phí sự khác biệt giữa hai số tiền 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 chưa sử dụng từ kế hoạch hiện tại sẽ đượ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ý 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ố tiền còn lại 30 đô la sẽ được tín dụng 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 động một khoản phí dựa trên tùy chọn phân bổ mà bạn đã chọn
• Nếu việc thay đổi kế hoạch là một sự hạ cấp và bạn sử dụng prorated_immediately, các 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 đăng ký. Những tín dụng này là cụ thể cho đăng ký đó và sẽ chỉ được sử dụng để bù đắp cho 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 sẽ bỏ qua việc tính toán tín dụng và tính phí toàn bộ số tiền cho kế hoạch 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