> ## 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.

# Thanh toán dựa trên tín dụng

> Phần payload được gửi đến điểm cuối webhook của bạn khi có sự kiện thanh toán dựa trên tín dụng diễn ra — tín dụng ảo (lần gọi API, token, giờ tính toán) được cấp, tiêu thụ, hết hạn, chuyển tiếp, hoặc cảnh báo số dư. Những webhook này không liên quan đến [Ví Khách hàng](/features/customer-wallet) (số dư tiền tệ).

## Sự kiện Webhook thanh toán dựa trên tín dụng

Các sự kiện webhook sau đây có sẵn để theo dõi các thay đổi vòng đời thanh toán dựa trên tín dụng. Những sự kiện này áp dụng cho quyền lợi tín dụng ảo (lần gọi API, token, giờ tính toán), không áp dụng cho [Ví Khách hàng](/features/customer-wallet) (số dư tiền tệ).

| Sự kiện                     | Mô tả                                                                                  |
| --------------------------- | -------------------------------------------------------------------------------------- |
| `credit.added`              | Tín dụng được cấp cho khách hàng (qua đăng ký, mua một lần, tiện ích bổ sung hoặc API) |
| `credit.deducted`           | Tín dụng bị tiêu thụ qua sử dụng hoặc ghi nợ thủ công                                  |
| `credit.expired`            | Tín dụng chưa sử dụng hết hạn sau thời gian hết hạn đã cấu hình                        |
| `credit.rolled_over`        | Tín dụng chưa dùng được chuyển tiếp sang khoản cấp mới khi chu kỳ kết thúc             |
| `credit.rollover_forfeited` | Tín dụng bị tịch thu vì đã đạt số lượt chuyển tiếp tối đa                              |
| `credit.overage_charged`    | Tính phí vượt mức khi sử dụng tiếp tục vượt quá số dư bằng không                       |
| `credit.manual_adjustment`  | Điều chỉnh tín dụng hoặc ghi nợ thủ công qua bảng điều khiển hoặc API                  |
| `credit.balance_low`        | Số dư tín dụng giảm xuống dưới ngưỡng số dư thấp đã cấu hình                           |

### Sự kiện Sổ cái

Tất cả các sự kiện sổ cái (`credit.added` đến `credit.manual_adjustment`) dùng chung payload `CreditLedgerEntryResponse` được mô tả trong sơ đồ dưới đây.

Payload bao gồm một trường `metadata` được giải quyết từ **nguồn** của khoản tín dụng — đăng ký hoặc thanh toán được tạo khi thanh toán. Điều này cho phép bạn khóa tín dụng ví của mình khi thanh toán `metadata` (ví dụ, một `orgId`) thay vì `customer_id` do Dodo phát hành: các khoản tín dụng có nguồn từ đăng ký hiển thị `metadata` của đăng ký và các khoản tín dụng có nguồn từ thanh toán hiển thị `metadata` của thanh toán. Trường này trống khi khoản tín dụng không có nguồn có thể giải quyết (ví dụ, tín dụng cấp trực tiếp qua API).

### Sự kiện Số dư Thấp (credit.balance\_low)

Sự kiện `credit.balance_low` sử dụng payload khác (`CreditBalanceLowPayload`) tập trung vào cảnh báo ngưỡng:

```json theme={null}
{
  "business_id": "bus_H4ekzPSlcg",
  "type": "credit.balance_low",
  "timestamp": "2025-08-04T06:15:00.000000Z",
  "data": {
    "payload_type": "CreditBalanceLow",
    "customer_id": "cus_8VbC6JDZzPEqfBPUdpj0K",
    "subscription_id": "sub_7EeHq2ewQuadropD2ra",
    "credit_entitlement_id": "cent_9xY2bKwQn5MjRpL8d",
    "credit_entitlement_name": "API Credits",
    "available_balance": "15",
    "subscription_credits_amount": "100",
    "threshold_percent": 20,
    "threshold_amount": "20"
  }
}
```

<ParamField body="customer_id" type="string">
  Khách hàng có số dư tín dụng đã kích hoạt cảnh báo.
</ParamField>

<ParamField body="subscription_id" type="string">
  Đăng ký liên kết với quyền lợi tín dụng này.
</ParamField>

<ParamField body="credit_entitlement_id" type="string">
  Quyền lợi tín dụng có số dư thấp.
</ParamField>

<ParamField body="credit_entitlement_name" type="string">
  Tên hiển thị của quyền lợi tín dụng.
</ParamField>

<ParamField body="available_balance" type="string">
  Số dư tín dụng hiện tại tại thời điểm cảnh báo.
</ParamField>

<ParamField body="subscription_credits_amount" type="string">
  Tổng số tín dụng phát hành mỗi chu kỳ thanh toán cho đăng ký này.
</ParamField>

<ParamField body="threshold_percent" type="integer">
  Phần trăm ngưỡng số dư thấp đã được cấu hình.
</ParamField>

<ParamField body="threshold_amount" type="string">
  Số lượng tín dụng tuyệt đối mà ngưỡng này tương ứng.
</ParamField>

### Sử dụng `credit.balance_low` cho Cảnh Báo Chủ Động

Sử dụng webhook `credit.balance_low` để thông báo cho khách hàng trước khi họ hết tín dụng:

```javascript theme={null}
app.post('/webhooks/dodo', async (req, res) => {
  const event = req.body;
  
  if (event.type === 'credit.balance_low') {
    const data = event.data;
    
    // Notify the customer their credits are running low
    await sendEmail(data.customer_id, {
      subject: `Your ${data.credit_entitlement_name} balance is running low`,
      body: `You have ${data.available_balance} credits remaining ` +
            `(${data.threshold_percent}% threshold reached). ` +
            `Consider upgrading your plan or purchasing additional credits.`
    });
    
    console.log(`Low balance alert for customer ${data.customer_id}`);
  }
  
  res.json({ received: true });
});
```

<Tip>
  Đăng ký `credit.balance_low` để chủ động cảnh báo khách hàng trước khi họ sử dụng hết tín dụng. Kết hợp với `credit.deducted` để theo dõi các kiểu tiêu thụ theo thời gian thực.
</Tip>

<CardGroup cols={2}>
  <Card title="Get Customer Balance" icon="wallet" href="/api-reference/credit-entitlements/get-customer-balance">
    Kiểm tra số dư hiện tại của khách hàng qua API.
  </Card>

  <Card title="Create Ledger Entry" icon="plus" href="/api-reference/credit-entitlements/create-ledger-entry">
    Ghi có hoặc ghi nợ số dư của khách hàng theo cách thủ công.
  </Card>
</CardGroup>

## Sơ đồ Payload Webhook