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

{
  "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 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 số tín dụng phát hành mỗi chu kỳ thanh toán cho đăng ký này.

threshold_percent

integer

Phần trăm ngưỡng số dư thấp đã được cấu hình.

threshold_amount

string

Số lượng tín dụng tuyệt đối mà ngưỡng này tương ứng.

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:

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

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ợ số dư của khách hàng theo cách thủ cô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

brand_id

string

bắt buộc

Brand id this credit ledger entry belongs to

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

metadata

object

bắt buộc

Metadata associated with the credit grant's source (the subscription or payment created at checkout). Empty when the grant has no resolvable source (e.g. credits granted directly via the API).

Show child attributes

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

​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 cho 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` cho Cảnh Báo Chủ Động

Sơ đồ Payload Webhook