> ## 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.
# Danh sách chặn khách hàng
> Chặn một khách hàng để ngăn các lần thanh toán sau này, hủy các gói đăng ký đang hoạt động của họ và chuyển Customer Portal sang chế độ chỉ đọc. Quản lý danh sách chặn từ Settings hoặc API.
Danh sách chặn khách hàng ngăn một đối tượng xấu đã được xác định mua hàng của bạn lần nữa. Khách hàng bị chặn không thể thanh toán, mất các gói đăng ký đang hoạt động và có thể xem nhưng không thể thay đổi bất kỳ điều gì trong [Customer Portal](/features/customer-portal). Quản lý danh sách này từ **Settings → Blocklist** hoặc thông qua Blocklist API.
## Điều gì xảy ra khi bạn chặn một khách hàng
| Khu vực | Tác động |
| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Checkout** | Mọi lần thanh toán từ email bị chặn đều bị từ chối: payment links, checkout sessions và các khoản thanh toán hoặc gói đăng ký được tạo thông qua API. |
| **Gói đăng ký đang hoạt động** | Các gói đăng ký ở trạng thái `pending`, `active`, `on_hold` hoặc `paused` sẽ bị hủy với lý do `cancelled_by_merchant`. Webhook `subscription.cancelled` thông thường sẽ được kích hoạt cho từng gói. |
| **Gia hạn và thử lại** | Các lần gia hạn tự động và [payment retries](/features/recovery/payment-retries) sẽ bỏ qua khách hàng bị chặn, vì vậy không phát sinh khoản phí nào nữa ngay cả khi việc hủy vẫn đang chờ xử lý. |
| **Thử lại thủ công** | [Manual retry](/features/recovery/manual-retry) cho khoản thanh toán của khách hàng bị chặn sẽ bị từ chối. |
| **Customer Portal** | Khách hàng vẫn có thể đăng nhập và xem hóa đơn, gói đăng ký và license keys, nhưng không thể hủy, tạm dừng hoặc tiếp tục gói đăng ký, thay đổi gói hay cập nhật phương thức thanh toán. Việc xóa phương thức thanh toán đã lưu vẫn được phép. |
Việc chặn không hoàn tiền cho các khoản thanh toán trước đây và không ảnh hưởng đến các tranh chấp đang mở. Thực hiện mọi khoản hoàn tiền riêng biệt từ trang [Refunds](/features/transactions/refunds).
## Cách việc chặn khớp với khách hàng
Bạn có thể chặn theo **customer ID** hoặc **email**. Trong cả hai trường hợp, việc chặn được xác định theo email của khách hàng, không phải bản ghi khách hàng:
* **Mọi bản ghi có email đó đều bị áp dụng.** Checkout có thể tạo bản ghi khách hàng mới cho email quay lại, vì vậy việc chặn một customer ID duy nhất có thể bị vượt qua. Việc chặn theo email thì không.
* **Các bí danh cũng được áp dụng.** Email được so sánh ở dạng chữ thường sau khi xóa `+alias`, vì vậy `buyer+promo@example.com` và `Buyer@example.com` được xem là cùng một khách hàng. Dấu chấm trong địa chỉ được giữ nguyên.
* **Chỉ áp dụng cho doanh nghiệp của bạn.** Việc chặn chỉ áp dụng cho doanh nghiệp của bạn. Cùng một email vẫn có thể mua hàng từ các doanh nghiệp khác trên Dodo Payments.
* **Email phải thuộc về một khách hàng hiện có.** Bạn không thể chặn một email chưa từng thanh toán với bạn, và không thể chặn bản ghi khách hàng không có email.
## Chặn một khách hàng
Truy cập **Settings → Blocklist** trong dashboard.
Nhấp vào **Add to Blocklist**, sau đó nhập email hoặc customer ID của khách hàng. Thêm lý do để nhóm của bạn có thể biết sau này tại sao việc chặn được thêm vào.
Xác nhận việc chặn. Các gói đăng ký đang hoạt động của khách hàng sẽ bị hủy ngay lập tức và mục nhập sẽ xuất hiện trong bảng **Blocked entries**.
Truy cập **Sales → Customers** và mở khách hàng bạn muốn chặn.
Nhấp vào **Block Customer**. Khi việc chặn có hiệu lực, trang sẽ hiển thị huy hiệu **Blocked** bên cạnh tên khách hàng.
## Quản lý khách hàng bị chặn
Trang **Blocklist** liệt kê mọi lượt chặn đang hoạt động:
* **Total Customers Blocked**: Số lượng khách hàng hiện đang bị chặn.
* **Blocked entries**: Mỗi lượt chặn chiếm một hàng, với **Identifier** bạn đã nhập (email hoặc customer ID), **Blocked By** (thành viên nhóm đã thêm lượt chặn) và **Blocked On**.
* **Search Identifier** và **Filters**: Tìm một mục nhập theo email hoặc customer ID, hoặc lọc theo người đã chặn và thời điểm chặn.
* **Action**: Quản lý mục nhập, bao gồm bỏ chặn khách hàng.
### Trang của khách hàng bị chặn
Mở một khách hàng bị chặn từ **Sales → Customers** hoặc từ trang Blocklist để xem:
* Huy hiệu **Blocked** bên cạnh tên khách hàng và nút **Unblock Customer**.
* **Activity Log**: Thời điểm khách hàng được thêm vào danh sách chặn, lý do và mọi ghi chú mà nhóm của bạn đã thêm sau đó. Nhấp vào **Add Note** để ghi lại thông tin mới, chẳng hạn như kết quả của một chargeback. Ghi chú có thể được chỉnh sửa sau.
* **Reference IDs**: Customer ID liên kết với lượt chặn này, sẵn sàng để sao chép.
## Bỏ chặn một khách hàng
Nhấp vào **Unblock Customer** trên trang của khách hàng hoặc sử dụng menu hành động trên trang Blocklist.
* Các thay đổi trong Checkout và Customer Portal được khôi phục ngay lập tức.
* **Các gói đăng ký đã hủy sẽ không được kích hoạt lại.** Khách hàng phải mua lại.
* Mục nhập được giữ lại như một bản ghi kiểm tra cùng với các ghi chú, nhưng không còn xuất hiện trong danh sách đang hoạt động.
* Bạn có thể chặn lại cùng một khách hàng sau này. Thao tác đó sẽ tạo một mục nhập mới.
## Những gì khách hàng nhìn thấy
Khách hàng bị chặn sẽ không bao giờ được thông báo rằng họ đã bị chặn.
* **Tại checkout**, thanh toán thất bại với thông báo từ chối chung: "This payment cannot be processed." API trả về HTTP `403` với mã lỗi `PAYMENT_NOT_PERMITTED`, không nêu nguyên nhân. Lý do thực sự chỉ được ghi vào log của Dodo Payments.
* **Trong Customer Portal**, mọi thứ đều hiển thị nhưng mọi hành động đều bị vô hiệu hóa. Một thao tác ghi bị chặn trả về `PORTAL_ACTION_NOT_PERMITTED` với thông báo "This action is not available." Hồ sơ portal chứa `read_only: true` để một custom portal integration có thể vô hiệu hóa các nút điều khiển của chính nó. Portal không bao giờ hiển thị mục nhập trong danh sách chặn hoặc các ghi chú của mục nhập.
Nếu bạn hiển thị lỗi checkout hoặc portal trong sản phẩm của riêng mình, hãy giữ nguyên hành vi này. Hiển thị thông báo chung cho `PAYMENT_NOT_PERMITTED` và `PORTAL_ACTION_NOT_PERMITTED`. Việc tiết lộ rằng khách hàng bị chặn sẽ cho đối tượng xấu biết cần thử một email khác.
## Sử dụng API
Blocklist API cho phép bạn chặn từ các công cụ của riêng mình, chẳng hạn khi nhận được chargeback. API yêu cầu [API key](/api-reference/introduction) bí mật của bạn. Mọi key đều có thể liệt kê các mục nhập và đọc ghi chú. Key được bật **write access** có thể chặn, bỏ chặn và quản lý ghi chú. Dashboard áp dụng cùng cách phân quyền cho các vai trò trong nhóm: vai trò **Viewer** có thể đọc danh sách và vai trò **Editor** có thể thực hiện thay đổi.
| Phương thức | Endpoint | Mục đích |
| ----------- | ------------------------------------------------- | ---------------------------------------------------------- |
| `GET` | `/blocklist/customers` | Liệt kê khách hàng bị chặn, với bộ lọc và số lượng `total` |
| `POST` | `/blocklist/customers` | Chặn khách hàng theo customer ID hoặc email |
| `GET` | `/blocklist/customers/{entry_id}` | Lấy một mục nhập cùng với các ghi chú của mục nhập |
| `DELETE` | `/blocklist/customers/{entry_id}` | Bỏ chặn khách hàng |
| `POST` | `/blocklist/customers/{entry_id}/notes` | Thêm ghi chú |
| `PATCH` | `/blocklist/customers/{entry_id}/notes/{note_id}` | Cập nhật ghi chú |
### Chặn một khách hàng
Gửi `customer_id` hoặc `email` ở cấp cao nhất của body. `reason` là tùy chọn và sẽ hiển thị trên trang của mục nhập.
```typescript Node.js theme={null}
import DodoPayments from 'dodopayments';
const client = new DodoPayments({
bearerToken: process.env.DODO_PAYMENTS_API_KEY,
});
// Block by customer ID
const entry = await client.blocklist.customers.create({
customer_id: 'cus_0NmichXWP8JYBB9Dw1Unj',
reason: 'Chargeback on pay_0NmichXuYoNoapmr',
});
// Or block by email
const byEmail = await client.blocklist.customers.create({
email: 'buyer@example.com',
reason: 'Repeated refund abuse',
});
console.log(entry.id, entry.cancelled_subscription_ids);
```
```python Python theme={null}
import os
from dodopayments import DodoPayments
client = DodoPayments(bearer_token=os.environ["DODO_PAYMENTS_API_KEY"])
# Block by customer ID
entry = client.blocklist.customers.create(
customer_id="cus_0NmichXWP8JYBB9Dw1Unj",
reason="Chargeback on pay_0NmichXuYoNoapmr",
)
# Or block by email
by_email = client.blocklist.customers.create(
email="buyer@example.com",
reason="Repeated refund abuse",
)
print(entry.id, entry.cancelled_subscription_ids)
```
```bash cURL theme={null}
curl -X POST https://live.dodopayments.com/blocklist/customers \
-H "Authorization: Bearer $DODO_PAYMENTS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"customer_id": "cus_0NmichXWP8JYBB9Dw1Unj",
"reason": "Chargeback on pay_0NmichXuYoNoapmr"
}'
```
```json Response theme={null}
{
"id": "bcu_7Hq2mV9kRt4LxYw3Pz",
"customer_id": "cus_0NmichXWP8JYBB9Dw1Unj",
"customer_name": "wow guy",
"customer_email": "wowguy@example.com",
"identifier": "cus_0NmichXWP8JYBB9Dw1Unj",
"reason": "Chargeback on pay_0NmichXuYoNoapmr",
"source": "api",
"blocked_by_email": null,
"created_at": "2026-09-02T12:09:41Z",
"unblocked_at": null,
"cancelled_subscription_ids": ["sub_3Fk8pW2nQs6MzXc1"],
"subscriptions_swept": true
}
```
| Trường | Mô tả |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `identifier` | Customer ID hoặc email bạn đã gửi. |
| `source` | Nguồn của lượt chặn: `blocklist_page`, `customer_page`, `payment_page`, `dispute_page` hoặc `api`. API key luôn ghi nhận `api`. |
| `blocked_by_email` | Người dùng dashboard đã thêm lượt chặn. `null` đối với API key. |
| `cancelled_subscription_ids` | Các gói đăng ký mà lệnh gọi này đã hủy. |
| `remaining_subscription_ids` | Các gói đăng ký vẫn đang hoạt động vì việc hủy không thành công hoặc lệnh gọi đã đạt giới hạn 25 lượt hủy. |
| `subscriptions_swept` | `false` khi vẫn còn gói đăng ký đang hoạt động. Lặp lại lệnh gọi cho đến khi giá trị là `true`. Bản thân việc chặn đã có hiệu lực. |
Chặn một khách hàng đã bị chặn sẽ trả về HTTP `409` với `CUSTOMER_ALREADY_BLOCKED`, trừ khi vẫn còn các gói đăng ký đang chờ hủy. Trong trường hợp đó, lệnh gọi sẽ tiếp tục quá trình hủy.
### Kiểm tra khách hàng có bị chặn hay không
[Get Customer Detail](/api-reference/customers/get-customers-1) trả về hai trường bổ sung: `blocked_at`, thời điểm lượt chặn đang hoạt động được thêm vào (`null` khi khách hàng không bị chặn), và `blocklist_entry_id`, mục nhập đứng sau lượt chặn đó. Endpoint [List Customers](/api-reference/customers/get-customers) để trống cả hai trường.
### Bỏ chặn một khách hàng
```typescript Node.js theme={null}
await client.blocklist.customers.delete('bcu_7Hq2mV9kRt4LxYw3Pz');
```
```python Python theme={null}
client.blocklist.customers.delete("bcu_7Hq2mV9kRt4LxYw3Pz")
```
```bash cURL theme={null}
curl -X DELETE https://live.dodopayments.com/blocklist/customers/bcu_7Hq2mV9kRt4LxYw3Pz \
-H "Authorization: Bearer $DODO_PAYMENTS_API_KEY"
```
Endpoint trả về HTTP `204` khi thành công. Bỏ chặn sẽ khôi phục các thao tác ghi trong checkout và portal, nhưng không kích hoạt lại bất kỳ gói đăng ký nào.
## Thực tiễn tốt nhất
* **Ghi lại lý do.** Một lý do ngắn trên lượt chặn, cùng với các ghi chú cho những việc xảy ra sau đó, giúp nhóm hỗ trợ của bạn nắm được toàn bộ diễn biến mà không cần rời dashboard.
* **Chặn sau chargeback.** Mở khách hàng từ tranh chấp hoặc khoản thanh toán rồi chặn ngay tại đó, hoặc tự động hóa từ webhook `dispute.opened` với `POST /blocklist/customers`. Xem [Disputes](/features/transactions/disputes).
* **Kiểm tra `subscriptions_swept`.** Khi chặn thông qua API, lặp lại lệnh gọi cho đến khi phản hồi báo `true`, để không còn gói đăng ký đang hoạt động nào bị bỏ sót.
* **Hoàn tiền riêng biệt.** Việc chặn chỉ ngăn các giao dịch mua trong tương lai. Nếu bạn nợ khách hàng tiền, hãy hoàn tiền như thường lệ.
* **Xem lại danh sách.** Bỏ chặn những khách hàng đã giải quyết xong vấn đề. Việc bỏ chặn có hiệu lực ngay lập tức và vẫn giữ lại lịch sử.
## Liên quan
Tìm một khách hàng, mở trang chi tiết của họ và quản lý các gói đăng ký của họ.
Những gì khách hàng bị chặn có thể và không thể làm trong portal.
Phản hồi chargeback và quyết định khi nào cần chặn.
Ý nghĩa của `PAYMENT_NOT_PERMITTED` và `PORTAL_ACTION_NOT_PERMITTED`.