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: mandate được ủy quyền và gói đăng ký được kích hoạt.
2. payment.succeeded: xác nhận khoản phí đầu tiên. Dự kiến nhận được sự kiện này trong vòng 2–10 phút sau khi thanh toán.

1. Khi bắt đầu dùng thử (thanh toán): subscription.active được kích hoạt sau khi phương thức thanh toán được ủy quyền. Chưa thu khoản phí định kỳ nào. Khoản phí thực tế đầu tiên được trì hoãn cho đến khi thời gian dùng thử kết thúc.
2. Khi thời gian dùng thử kết thúc: số tiền định kỳ được thu và bạn nhận được payment.succeeded cùng với subscription.renewed.

• subscription.renewed: được kích hoạt trong mỗi chu kỳ thanh toán khi khoản phí gia hạn được khấu trừ, luôn cùng với payment.succeeded. Sự kiện này cũng chứa next_billing_date đã được cập nhật.

1. Gói đăng ký thất bại

• subscription.failed - Không thể tạo gói đăng ký do không thể tạo mandate.
• payment.failed - Cho biết thanh toán thất bại.

2. Gói đăng ký bị tạm giữ

• subscription.on_hold - Gói đăng ký bị tạm giữ do khoản thanh toán gia hạn hoặc khoản phí thay đổi gói thất bại.
• Khi gói đăng ký bị tạm giữ, gói 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 và subscription.on_hold

​

Xử lý gói đăng ký bị tạm giữ

​

Khi gói đăng ký bị tạm giữ

• Thanh toán gia hạn thất bại: Khoản phí gia hạn tự động thất bại do không đủ tiền, thẻ hết hạn hoặc ngân hàng từ chối
• Khoản phí thay đổi gói thất bại: Khoản phí phát sinh ngay lập tức trong quá trình nâng cấp/hạ cấp gói 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 gói đăng ký đang bị tạm giữ

1. Tạo khoản phí cho các khoả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 gó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
}

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

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

​

Payload sự kiện gói đăng ký mẫu

​

Thay đổi gói đăng ký

​

Tùy chọn proration

​

1. prorated_immediately

• Tính số tiền được phân bổ 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 cho phần chênh lệch giữa gói cũ và gói mới
• Trong thời gian dùng thử, tùy chọn 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

​

2. full_immediately

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

​

3. difference_immediately

• Khi nâng cấp, khách hàng sẽ bị tính ngay phần chênh lệch giữa số tiền củ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 phí $50 ngay lập tức.
• Khi hạ cấp, số tiền chưa sử dụng của gói 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 gói đăng ký trong tương lai.
• 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, khoản $30 còn lại được ghi có và dùng cho chu kỳ thanh toán tiếp theo.

​

4. do_not_bill

• Áp dụng thay đổi gói ngay lập tức nhưng không tính phí tại thời điểm thay đổi.
• Gói đã cập nhật (cùng số lượng/add-on) được tính phí vào lần gia hạn theo lịch tiếp theo, và ngày thanh toán ban đầu được giữ nguyên.

​

Hành vi

• Khi gọi API này, Dodo Payments ngay lập tức bắt đầu tính phí dựa trên tùy chọn proration đã chọn
• Nếu 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ự động tính toán và thêm vào số dư tín dụng của gói đăng ký. Các khoản tín dụng này chỉ thuộc về gói đăng ký đó và chỉ được dùng để bù trừ cho các khoản thanh toán định kỳ trong tương lai của cùng gói đăng ký
• Tùy chọn full_immediately bỏ qua việc tính 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 bắt đầu khi thay đổi gói thường hoàn tất xử lý trong chưa đến 2 phút
• Nếu khoản phí ngay lập tức này thất bại vì bất kỳ lý do nào, gói đăng ký sẽ tự động bị tạm giữ cho đến khi vấn đề được giải quyết

​

Gói đăng ký theo yêu cầu

​

Những điều quan trọng cần biết về thanh toán gói đăng ký

​

Tài liệu tham khảo API liên quan