Thanh toán dựa trên tín dụng - Dodo Payments Documentation

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

Sự kiện Số dư Thấp (credit.balance_low)

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

{
  "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"
  }
}

customer_id

string

Khách hàng có số dư tín dụng kích hoạt cảnh báo.

subscription_id

string

Đăng ký liên kết với quyền lợi tín dụng này.

credit_entitlement_id

string

Quyền lợi tín dụng đang có số dư thấp.

credit_entitlement_name

string

Tên hiển thị của quyền lợi tín dụng.

available_balance

string

Số dư tín dụng hiện tại tại thời điểm cảnh báo.

subscription_credits_amount

string

Tổng tín dụng được cấp mỗi chu kỳ thanh toán cho đăng ký này.

threshold_percent

integer

Tỷ lệ phần trăm ngưỡng số dư thấp đã cấu hình.

threshold_amount

string

Lượng tín dụng tuyệt đối tương ứng với ngưỡng.

Sử dụng `credit.balance_low` để 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:

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

Đăng ký nhận sự kiện credit.balance_low để cảnh báo chủ động 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 mô hình tiêu thụ theo thời gian thực.

Get Customer Balance

Kiểm tra số dư hiện tại của khách hàng qua API.

Create Ledger Entry

Ghi có hoặc ghi nợ thủ công vào số dư của khách hàng.

Sơ đồ Payload Webhook

Response for a ledger entry

amount

string

bắt buộc

balance_after

string

bắt buộc

balance_before

string

bắt buộc

business_id

string

bắt buộc

created_at

string<date-time>

bắt buộc

credit_entitlement_id

string

bắt buộc

customer_id

string

bắt buộc

string

bắt buộc

is_credit

boolean

bắt buộc

overage_after

string

bắt buộc

overage_before

string

bắt buộc

transaction_type

enum<string>

bắt buộc

Tùy chọn có sẵn:

credit_added,

credit_deducted,

credit_expired,

credit_rolled_over,

rollover_forfeited,

overage_charged,

overage_reset,

auto_top_up,

manual_adjustment,

refund

description

string | null

grant_id

string | null

reference_id

string | null

reference_type

string | null

Documentation Index

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

​Sự kiện Sổ cái

​Sự kiện Số dư Thấp (credit.balance_low)

​Sử dụng credit.balance_low để cảnh báo chủ động

Get Customer Balance

Create Ledger Entry

​Sơ đồ Payload Webhook

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

Sự kiện Sổ cái

Sự kiện Số dư Thấp (credit.balance_low)

Sử dụng `credit.balance_low` để cảnh báo chủ động

Sơ đồ Payload Webhook