> ## 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.
Customer Blocklist ngăn một đối tượng xấu đã được xác định mua hàng từ 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 tài khoản của họ trong [Customer Portal](/features/customer-portal) nhưng không thể thay đổi gói đăng ký. Quản lý blocklist 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
Lệnh chặn có hiệu lực ngay sau khi bạn thêm, trong từng khu vực sau:
| 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. |
| **Live subscriptions** | 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. |
| **Renewals and retries** | 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 thêm khoản phí nào ngay cả khi việc hủy vẫn đang chờ xử lý. |
| **Manual retry** | [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. Họ không thể hủy, tạm dừng hoặc tiếp tục gói đăng ký, thay đổi gói, cập nhật phương thức thanh toán hoặc chỉnh sửa địa chỉ trên hóa đơn. Họ vẫn có thể xóa phương thức thanh toán đã lưu. |
Việc chặn không hoàn tiền cho các khoản thanh toán trước đó và không ảnh hưởng đến các dispute đang mở. Thực hiện mọi khoản hoàn tiền riêng từ trang [Refunds](/features/transactions/refunds).
## Cách lệnh chặn khớp với khách hàng
Bạn có thể chặn theo **customer ID** hoặc **email**. Dù sử dụng cách nào, lệnh chặn cũng được xác định theo email của khách hàng, không phải customer record:
* **Mọi record có email đó đều được áp dụng.** Checkout có thể tạo customer record mới cho email quay lại, vì vậy lệnh chặn theo một customer ID duy nhất có thể bị обход qua. Lệnh chặn theo email thì không.
* **Các alias cũng được áp dụng.** Email được so sánh ở dạng chữ thường sau khi loại bỏ `+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.
* **Giới hạn trong doanh nghiệp của bạn.** Lệnh 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 email không khớp với khách hàng nào của mình và không thể chặn customer record không có email.
## Chặn một khách hàng
Bạn có thể chặn khách hàng từ trang Blocklist hoặc từ chính trang của khách hàng đó.
Đi tới **Settings → Blocklist** trong dashboard của bạn.
Nhấp vào **Add to Blocklist**, sau đó nhập email hoặc customer ID của khách hàng vào **Customer ID or email**. Panel sẽ hiển thị khách hàng khớp.
Nhấp vào **Add to Blocklist** trong panel. Các gói đăng ký đang hoạt động của khách hàng sẽ được hủy ngay lập tức và mục nhập sẽ xuất hiện trong bảng **Blocked entries**. Nếu một số gói đăng ký vẫn đang được hủy, dashboard sẽ hiển thị thông báo. Hãy làm mới trang sau ít phút để kiểm tra.
Đi tới **Sales → Customers** và mở khách hàng bạn muốn chặn.
Mở menu bằng biểu tượng ba dấu chấm và chọn **Block this Customer**.
Nhấp vào **Block**. Khi lệnh 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.
Dashboard không yêu cầu lý do. Để ghi lại lý do bạn chặn khách hàng, hãy thêm ghi chú trên trang của khách hàng hoặc gửi `reason` khi chặn thông qua API.
## Quản lý khách hàng bị chặn
Trang **Blocklist** liệt kê mọi lệnh chặn đang hoạt động:
* **Total Customers Blocked**: Số khách hàng hiện đang bị chặn.
* **Blocked entries**: Mỗi lệnh chặn có một dòng, cùng với **Identifier** bạn đã nhập (email hoặc customer ID), **Blocked By** và **Blocked On**. **Blocked By** hiển thị thành viên nhóm đã thêm lệnh chặn hoặc **API** đối với lệnh chặn được thêm bằng API key.
* **Search Identifier** và **Filters**: Tìm mục nhập theo email hoặc customer ID, hoặc lọc theo **Blocked By** và **Blocked Between**.
* **Action**: **See Details** mở trang của khách hàng bị chặn, còn **Unblock** xóa lệnh chặn. Thành viên nhóm có vai trò **Viewer** không thể bỏ chặn.
### Trang của khách hàng bị chặn
Mở 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 blocklist, lý do và mọi ghi chú 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. Bạn có thể chỉnh sửa ghi chú sau thông qua API.
* **Reference IDs**: Customer ID liên kết với lệnh chặn này, sẵn sàng để sao chép.
## Bỏ chặn một khách hàng
Để bỏ chặn khách hàng, nhấp vào **Unblock Customer** trên trang của khách hàng hoặc chọn **Unblock** trong cột **Action** của trang Blocklist. Sau đó xác nhận bằng **Unblock**.
* Các thay đổi đối với Checkout và Customer Portal được khôi phục ngay lập tức.
* **Các gói đăng ký đã hủy 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 dưới dạng audit record 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 không bao giờ được thông báo rằng họ đã bị chặn.
* **Tại checkout**, khoản 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` cùng mã lỗi `PAYMENT_NOT_PERMITTED`, không nêu nguyên nhân nào. Lý do thực tế chỉ được ghi vào log của Dodo Payments.
* **Trong Customer Portal**, mọi thứ đều hiển thị nhưng mọi thao tác thay đổi tài khoản đều bị từ chối. Thao tác bị từ chối trả về HTTP `403` cùng `PORTAL_ACTION_NOT_PERMITTED` và thông báo "This action is not available." Hồ sơ portal có `read_only: true`, vì vậy một custom portal integration có thể vô hiệu hóa các control của chính nó. Portal không bao giờ hiển thị mục nhập blocklist 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 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ộ lệnh chặn sẽ cho đối tượng xấu biết rằng họ nê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ụ riêng, chẳng hạn khi nhận được một 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ò nhóm: vai trò **Viewer** có thể đọc danh sách, còn vai trò **Editor** có thể thực hiện thay đổi.
Blocklist API có sáu endpoint:
| Method | Endpoint | Mục đích |
| - | - | - |
| `GET` | `/blocklist/customers` | Liệt kê khách hàng bị chặn, kèm 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ú |
Danh sách chỉ trả về các lệnh chặn đang hoạt động. Để lọc, truyền `identifier` (khớp một phần, không phân biệt chữ hoa chữ thường với email hoặc customer ID), `blocked_by_email`, `created_at_gte` hoặc `created_at_lte`. Theo mặc định, endpoint trả về 10 mục nhập mỗi trang: đặt `page_size` để trả về tối đa 100 mục và `page_number` để chuyển trang.
### Chặn một khách hàng
Gửi `customer_id` hoặc `email` ở cấp cao nhất của body. Nếu gửi cả hai, lệnh chặn sẽ sử dụng `customer_id`. `reason` là tùy chọn và sẽ hiển thị trên trang của mục nhập. Lệnh chặn mới trả về HTTP `201`.
```typescript Node.js expandable 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 expandable 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"
}'
```
Phản hồi mô tả mục nhập và các gói đăng ký mà lệnh gọi đã hủy:
```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
}
```
Các trường cần được chú ý nhất:
| Trường | Mô tả |
| - | - |
| `identifier` | Customer ID hoặc email bạn đã gửi. |
| `source` | Nguồn của lệnh chặn: `blocklist_page`, `customer_page`, `payment_page`, `dispute_page` hoặc `api`. API key luôn ghi nhận `api`, bất kể bạn gửi `source` nào. |
| `blocked_by_email` | Dashboard user đã thêm lệnh 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. Chỉ xuất hiện trong response create. |
| `remaining_subscription_ids` | Các gói đăng ký vẫn đang hoạt động vì việc hủy thất bại hoặc lệnh gọi đã đạt giới hạn 25 lần hủy. |
| `subscriptions_swept` | `false` khi vẫn còn gói đăng ký đang hoạt động hoặc khi Dodo Payments không thể liệt kê chúng. Lặp lại lệnh gọi cho đến khi trường này là `true`. Bản thân lệnh chặn đã có hiệu lực. |
Chặn một khách hàng đã bị chặn sẽ trả về HTTP `409` cùng `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 việc hủy thay vào đó và trả về HTTP `200`.
### 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ề thêm hai trường: `blocked_at`, thời điểm lệnh chặn đang hoạt động được thêm (`null` khi khách hàng không bị chặn), và `blocklist_entry_id`, mục nhập đứng sau lệnh 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 và HTTP `404` khi ID không khớp với lệnh chặn đang hoạt động nào. Việc bỏ chặn khôi phục các thao tác ghi trên checkout và portal nhưng không kích hoạt lại bất kỳ gói đăng ký nào.
## Các phương pháp hay nhất
* **Ghi lại lý do.** Một lý do ngắn trên lệnh 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 đầy đủ thông tin mà không cần rời dashboard.
* **Chặn sau chargeback.** Mở trang của khách hàng từ dispute hoặc khoản thanh toán rồi chặn tại đó, hoặc tự động hóa từ webhook `dispute.opened` bằng `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 response báo `true` để không còn gói đăng ký đang hoạt động nào bị bỏ lại.
* **Hoàn tiền riêng.** Lệnh chặn chỉ ngăn các giao dịch mua trong tương lai. Nếu bạn cần trả tiền cho khách hàng, 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 khách hàng, mở trang chi tiết của họ và quản lý các gói đăng ký.
Những gì khách hàng bị chặn có thể và không thể làm trong portal.
Xử lý chargeback và quyết định thời điểm cần chặn.
Ý nghĩa của `PAYMENT_NOT_PERMITTED` và `PORTAL_ACTION_NOT_PERMITTED`.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.