> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.

# v1.97.6 (7 Tháng 5, 2026)

> Ra mắt Entitlements với năm tích hợp fulfilment mới (Discord, GitHub, Telegram, Framer, Notion), lý do hủy đăng ký trong cổng khách hàng, cấu hình sàn INR e-mandate, cài đặt phí tiền tệ thích ứng, ứng dụng Dodo Payments Desktop cho macOS/Windows/Linux, thanh toán stablecoin (USDC/USDP/USDG), nhập khóa giấy phép hiện có, yêu cầu_số_điện_thoại cho phiên thanh toán, và sửa lỗi

## Tính Năng Mới

### 1. **Entitlements**

Dodo Payments hiện có **Entitlements** hợp nhất — một lớp duy nhất thực hiện tự động cung cấp cho mọi tích hợp fulfilment. Một sản phẩm có thể cung cấp nhiều entitlements trên mỗi giao dịch mua thành công hoặc đăng ký hoạt động.

**Năm tích hợp nền tảng mới**

Cho đến nay, Dodo Payments đã tự động cung cấp **khóa giấy phép** và **tệp kỹ thuật số** khi mua. Với Entitlements, phạm vi này mở rộng đến năm nền tảng khác — cho phép người mua trả tiền truy cập cộng đồng, mã nguồn, hoặc nội dung của bạn ngay khi thanh toán thành công, không cần bàn giao thủ công từ phía bạn:

| Tích hợp     | Giao dịch                                                                                            | Hành vi thu hồi                                     |
| ------------ | ---------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
| **Discord**  | Gán vai trò đã chọn trong máy chủ Discord của bạn sau khi khách hàng hoàn tất OAuth                  | Vai trò bị xóa khi hủy hoàn/tiền lại                |
| **GitHub**   | Thêm khách hàng làm cộng sự vào kho lưu trữ riêng ở cấp độ quyền mà bạn chọn                         | Cộng sự bị xóa khi hủy hoàn/tiền lại                |
| **Telegram** | Cung cấp liên kết mời tham gia một lần cho trò chuyện riêng hoặc kênh thông qua bot Telegram của bạn | Khách bị đuổi khỏi trò chuyện khi hủy hoàn/tiền lại |
| **Framer**   | Mở khóa liên kết remix mẫu Framer bị chặn bằng mã truy cập                                           | Mã truy cập bị vô hiệu khi hủy hoàn/tiền lại        |
| **Notion**   | Sao chép một trang mẫu Notion vào không gian làm việc của khách hàng sau khi họ ủy quyền qua OAuth   | Trang đã giao được lưu trữ khi hủy hoàn/tiền lại    |

Những dòng này gia nhập các tích hợp **Khóa Giấy Phép** (khóa duy nhất với giới hạn kích hoạt và hết hạn) và **Tệp Kỹ Thuật Số** (URL tải xuống đã ký trước cho sách điện tử, mẫu, tài liệu), tất cả đều được quản lý qua cùng một vòng đời cấp phát.

**Lợi ích ngay lập tức**

| Khả năng                                 | Mô tả                                                                                                                                                                                                                      |
| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Mẫu dùng lại**                         | Xác định một entitlement một lần (giới hạn kích hoạt, gói tệp, vai trò Discord, quyền repo, v.v.) và đính kèm vào bất kỳ sản phẩm nào                                                                                      |
| **Cấp phát tự động**                     | Cấp phát khi `payment.succeeded` và `subscription.active`, đồng nhất qua các lần gia hạn và kích hoạt lại                                                                                                                  |
| **Thu hồi theo vòng đời**                | Thu hồi khi `subscription.cancelled`, `subscription.on_hold`, `subscription.expired`, `refund.succeeded`, `subscription.plan_changed`, hoặc thu hồi thủ công qua API/bảng điều khiển — với `revocation_reason` đã điền sẵn |
| **Luồng OAuth + gọi trực tiếp nền tảng** | OAuth cho sự đồng ý người đăng ký Discord, GitHub, và Notion; gọi trực tiếp nền tảng cho Telegram, Framer, và Tệp Kỹ Thuật Số                                                                                              |
| **Phát hiện trôi**                       | Phát hiện khi vai trò Discord, cộng sự GitHub, hoặc trang Notion mất đồng bộ ở cấp độ nền tảng và thu hồi với `revocation_reason: platform_external`                                                                       |
| **Mã hóa lưu trữ**                       | Tất cả token nền tảng (OAuth, bot, cài đặt ứng dụng) được lưu trữ bằng AES-256-GCM                                                                                                                                         |

**Webhooks**

Bốn sự kiện vòng đời mới được kích hoạt cho mỗi cấp phát:

| Sự kiện                       | Kích hoạt khi                                                            |
| ----------------------------- | ------------------------------------------------------------------------ |
| `entitlement_grant.created`   | Một cấp phát mới được tạo ra cho một khách hàng                          |
| `entitlement_grant.delivered` | Quyền truy cập của khách hàng được cung cấp                              |
| `entitlement_grant.failed`    | Giao hàng không thể hoàn thành; kiểm tra `error_code` và `error_message` |
| `entitlement_grant.revoked`   | Quyền truy cập bị thu hồi; kiểm tra `revocation_reason`                  |

Tìm hiểu thêm: [Entitlements](/features/entitlements/introduction) | [Entitlement Grant Webhooks](/developer-resources/webhooks/intents/entitlement-grant)

### 2. **Lý Do Hủy Đăng Ký Trong Cổng Khách Hàng**

Khi khách hàng hủy đăng ký từ Cổng Khách Hàng, họ sẽ được nhắc chia sẻ **lý do họ hủy** trước khi xác nhận. Lý do được lưu trữ trên đăng ký dưới dạng `cancellation_feedback`, xuất hiện trong API và payload webhook, và có sẵn trong bảng điều khiển để bạn có thể dễ dàng nhận biết mẫu từ bỏ.

**Tùy chọn lý do**

| Giá trị            | Nhãn đối diện khách hàng |
| ------------------ | ------------------------ |
| `too_expensive`    | Quá đắt                  |
| `missing_features` | Thiếu tính năng          |
| `switched_service` | Chuyển sang dịch vụ khác |
| `unused`           | Không sử dụng đủ         |
| `customer_service` | Dịch vụ khách hàng kém   |
| `low_quality`      | Chất lượng kém           |
| `too_complex`      | Quá phức tạp             |
| `other`            | Khác                     |

**Vị trí xuất hiện**

* **Đối tượng Subscription**: Trường `cancellation_feedback` mới (một trong các giá trị ở trên) và `cancellation_comment` (văn bản tự do tùy chọn), được điền khi khách hàng hủy
* **Webhook `subscription.cancelled`**: Cả hai trường đều được bao gồm trong payload
* **API**: Truyền `cancellation_feedback` và `cancellation_comment` vào `PATCH /subscriptions/{subscription_id}` khi lên lịch hoặc thực thi việc hủy theo cách lập trình

```typescript theme={null}
// Reading the captured feedback
const subscription = await client.subscriptions.retrieve('sub_123');
console.log(subscription.cancellation_feedback); // e.g., "too_expensive"
console.log(subscription.cancellation_comment);  // e.g., "Switching to a competitor"
```

Tìm hiểu thêm: [Cổng Khách Hàng](/features/customer-portal#cancelling-a-subscription) | [Subscription Webhooks](/developer-resources/webhooks/intents/subscription)

### 3. **Số Tiền Tối Thiểu Cấu Hình Cho Ủy Quyền INR E-Mandates**

Giờ đây bạn có thể cấu hình **sàn ủy quyền** cho các ủy quyền INR e-mandates trên các đăng ký thẻ Ấn Độ định kỳ. Trước đây, mọi đăng ký thẻ Ấn Độ dưới ₹15,000 sử dụng một ủy quyền on-demand cố định ₹15,000. Giờ đây bạn có thể ghi đè sàn này ở mức độ thương nhân — và từng phiên thanh toán hoặc đăng ký nếu cần.

Số tiền ủy quyền được đăng ký với ngân hàng của khách hàng là `max(mandate_min_amount_inr_paise, billing_amount)`, do đó giá trị này đóng vai trò là **trần ủy quyền** đối diện khách hàng mỗi khi thanh toán thấp hơn sàn.

```typescript theme={null}
// Per-subscription override
const subscription = await client.subscriptions.create({
  product_id: 'pdt_inr_monthly',
  customer: { email: 'customer@example.in' },
  billing: { country: 'IN' /* ... */ },
  mandate_min_amount_inr_paise: 2_000_000 // ₹20,000 ceiling for this subscription
});

// Or via a checkout session
const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_inr_monthly', quantity: 1 }],
  mandate_min_amount_inr_paise: 2_000_000,
  return_url: 'https://yoursite.com/return'
});
```

**Độ ưu tiên giải pháp**

1. Ghi đè theo yêu cầu (`mandate_min_amount_inr_paise` trên phiên thanh toán, thanh toán, hoặc đăng ký)
2. Cài đặt mức độ thương nhân trong cài đặt doanh nghiệp
3. Mặc định của hệ thống là **₹15,000** (1,500,000 paise)

| Trường                         | Loại                  | Phạm vi | Áp dụng cho                                                 |
| ------------------------------ | --------------------- | ------- | ----------------------------------------------------------- |
| `mandate_min_amount_inr_paise` | `integer` (INR paise) | `>= 1`  | Đăng ký INR thẻ Ấn Độ trên các kết nối không phải Airwallex |

Tìm hiểu thêm: [Phương thức Thanh Toán Ấn Độ](/features/payment-methods/india#mandate-types) | [Đăng Ký Với Ủy Quyền RBI](/features/subscription#subscriptions-with-rbi-compliant-mandates)

### 4. **Cấu Hình Phí Tiền Tệ Thích Ứng Bao Gồm**

Tiền Tệ Thích Ứng là tính năng cho phép bạn thu phí khách hàng theo đơn vị tiền tệ địa phương. Theo mặc định, **phí 2–4% cho tiền tệ thích ứng** sẽ do khách hàng chi trả và được thêm vào giá hiển thị của bạn. Với cài đặt **Phí Bao Gồm** mới, bạn có thể thay đổi điều này: giữ nguyên giá hiển thị cho khách hàng và tự chịu phí.

**Nơi cấu hình**

Đi tới **Cài đặt → Doanh nghiệp**, đảm bảo **Định Giá Thích Ứng** đã được kích hoạt và bật **Phí Bao Gồm** trong phần Tiền Tệ Thích Ứng.

**Ghi đè theo yêu cầu**

Bạn cũng có thể ghi đè giá trị mặc định của merchant cho từng khoản thanh toán, các khoản phí subscription on-demand và các thay đổi plan bằng boolean `adaptive_currency_fees_inclusive`:

```typescript theme={null}
const payment = await client.payments.create({
  product_cart: [{ product_id: 'pdt_abc', quantity: 1 }],
  customer: { customer_id: 'cus_123' },
  billing: { country: 'US' },
  adaptive_currency_fees_inclusive: true, // override business default
  return_url: 'https://yoursite.com/return'
});
```

| Chế độ               | Khách hàng thấy                     | Thương nhân giải quyết     |
| -------------------- | ----------------------------------- | -------------------------- |
| Độc quyền (mặc định) | Giá địa phương + phí 2–4% trên cùng | Giá cơ bản đầy đủ          |
| Bao gồm              | Giá địa phương (không đổi)          | Giá cơ bản trừ đi phí 2–4% |

Tìm hiểu thêm: [Tiền Tệ Thích Ứng](/features/adaptive-currency)

### 5. **Ứng Dụng Dodo Payments Desktop**

Ứng dụng chính thức **Dodo Payments Desktop** hiện có sẵn rộng rãi cho **macOS, Windows, và Linux**. Chạy bảng điều khiển thanh toán của bạn như một ứng dụng gốc nhanh, không cần tab trình duyệt.

| Nền tảng                      | Tải về                                                |
| ----------------------------- | ----------------------------------------------------- |
| macOS (Apple Silicon)         | `Dodo.Payments_<version>_aarch64.dmg`                 |
| macOS (Intel)                 | `Dodo.Payments_<version>_x64.dmg`                     |
| Windows                       | `Dodo.Payments_<version>_x64-setup.exe` (hoặc `.msi`) |
| Linux (Debian/Ubuntu)         | `Dodo.Payments_<version>_amd64.deb`                   |
| Linux (Fedora/RHEL)           | `Dodo.Payments-<version>-1.x86_64.rpm`                |
| Linux (AppImage, tự cập nhật) | `Dodo.Payments_<version>_amd64.AppImage`              |

**Bên trong có gì**

* **Tệp nhị phân gốc nhỏ** — được xây dựng với Tauri trên webview gốc của hệ thống, tổng cộng khoảng 5 MB (không gói sẵn Chromium)
* **Được ký và chứng thực** — các bản dựng macOS được ký với ID Nhà Phát triển Apple và chứng thực, vì vậy không có cảnh báo Gatekeeper
* **Tự động cập nhật** — kiểm tra mỗi 4 giờ và áp dụng cập nhật đã ký tự động từ GitHub Releases (hoạt động trên macOS, Windows, và Linux AppImage)
* **Khay hệ thống + thanh menu** — ẩn vào khay trên macOS, đầy đủ menu Tệp/Sửa/Xem/Trợ giúp với phím tắt (`⌘⇧H` đi đến bảng điều khiển, `⌘L` sao chép URL hiện tại, `⌘⌥I` công cụ phát triển)
* **Hỗ trợ liên kết sâu** — liên kết xác thực magic-link mở thẳng trong ứng dụng
* **Nhiều cửa sổ** — mở nhiều bảng điều khiển cạnh nhau

### 6. **Thanh Toán Stablecoin (USDC, USDP, USDG)**

Chấp nhận **thanh toán stablecoin toàn cầu** với thanh toán bằng USD. Khách hàng thanh toán từ ví stablecoin ưa thích của họ trên mạng lưới họ chọn; bạn nhận được USD fiat mà không có rủi ro biến động tiền điện tử, không có chiết khấu và không cần cơ sở hạ tầng ngân hàng từ phía khách hàng.

**Tiền tệ và mạng lưới hỗ trợ**

| Stablecoin | Mạng lưới                       |
| ---------- | ------------------------------- |
| **USDC**   | Ethereum, Solana, Polygon, Base |
| **USDP**   | Ethereum, Solana                |
| **USDG**   | Ethereum                        |

**Phạm vi**

| Chi tiết           | Giá trị                               |
| ------------------ | ------------------------------------- |
| Tiền tệ thanh toán | USD                                   |
| Quốc gia hỗ trợ    | Toàn cầu (trừ Ấn Độ)                  |
| Đăng ký            | Không hỗ trợ (chỉ thanh toán một lần) |
| Số tiền tối thiểu  | \$0.50                                |
| Thanh toán         | USD                                   |

**Cấu hình**

Truyền `crypto_currency` trong `allowed_payment_method_types` khi tạo phiên thanh toán:

```javascript theme={null}
const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_123', quantity: 1 }],
  allowed_payment_method_types: ['crypto_currency', 'credit', 'debit'],
  return_url: 'https://example.com/success'
});
```

Khách hàng sẽ thấy một địa chỉ ví và mã QR với số tiền stablecoin được tính toán theo tỷ giá hối đoái thực tế; khi blockchain xác nhận giao dịch, webhook `payment.succeeded` của bạn kích hoạt và khách hàng được chuyển hướng đến trang thành công của bạn.

Tìm hiểu thêm: [Thanh Toán Stablecoin](/features/payment-methods/stablecoins)

### 7. **Nhập Khóa Giấy Phép Hiện Có**

Giờ đây, bạn có thể **nhập khóa giấy phép từ hệ thống khác** vào Dodo Payments sử dụng [Create License Key API](/api-reference/licenses/create-license-key). Điều này mở khóa di chuyển không gián đoạn từ bất kỳ nhà cung cấp khóa giấy phép bên ngoài nào, cho phép khách hàng hiện tại của bạn tiếp tục kích hoạt, xác minh, và hủy kích hoạt các khóa của họ với Dodo Payments mà không cần cấp lại.

```typescript theme={null}
const licenseKey = await client.licenseKeys.create({
  customer_id: 'cus_abc123',
  product_id: 'pdt_456',
  key: 'YOUR-EXISTING-LICENSE-KEY',
  activations_limit: 5,
  expires_at: '2026-12-31T23:59:59Z',
});
```

Các khóa nhập vào được gắn thẻ `source: "import"` (so với `source: "auto"` cho các khóa được tạo tự động khi thanh toán), vì vậy bạn có thể phân biệt hàng nhập di chuyển từ các khóa cấp phát theo cách tự nhiên khi truy vấn `GET /license_keys`. Mã `payment_id` trên các khóa nhập vào là `null` vì chúng không được liên kết với giao dịch Dodo Payments.

Tìm hiểu thêm: [Khóa Giấy Phép](/features/license-keys#import-existing-license-keys-via-api) | [Create License Key API](/api-reference/licenses/create-license-key)

### 8. **`require_phone_number` cho Phiên Thanh Toán**

Buộc khách hàng cung cấp số điện thoại trong quá trình thanh toán bằng cách đặt `feature_flags.require_phone_number: true` khi tạo một phiên thanh toán. Số điện thoại trở thành trường bắt buộc trên biểu mẫu thanh toán, với dạng xác thực biểu mẫu hiển thị "Cần có số điện thoại" nếu khách hàng để trống.

```typescript theme={null}
const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_abc', quantity: 1 }],
  feature_flags: {
    allow_phone_number_collection: true,
    require_phone_number: true
  },
  return_url: 'https://yoursite.com/return'
});
```

| Cờ                              | Mặc định | Hành vi                                         |
| ------------------------------- | -------- | ----------------------------------------------- |
| `allow_phone_number_collection` | `true`   | Hiển thị trường số điện thoại trên thanh toán   |
| `require_phone_number`          | `false`  | Làm cho trường số điện thoại trở thành bắt buộc |

Tìm hiểu thêm: [Tính Năng Thanh Toán](/features/checkout) | [Create Checkout Session API](/api-reference/checkout-sessions/create)

## Sửa Lỗi & Cải Tiến

* Sửa lỗi nhỏ và cải tiến tính ổn định trên toàn bộ nền tảng