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

# v1.81.0 (06 tháng 2, 2026)

> Phân tích bên thứ ba, tùy chỉnh giao diện thanh toán, ngăn thay đổi gói khi thanh toán thất bại và API sổ cái số dư

## Tính năng mới

### 1. **Hỗ trợ Phân tích Bên thứ ba**

Theo dõi hành vi khách hàng trên Storefront, Checkout và Customer Portal bằng Google Analytics 4, Google Tag Manager và Meta Pixel. Thêm ID theo dõi của bạn trong **Settings → Analytics** để bắt đầu thu thập các sự kiện thương mại điện tử.

**Nền tảng hỗ trợ**

| Nền tảng           | Định dạng ID      |
| ------------------ | ----------------- |
| Google Analytics 4 | `G-XXXXXXXXXX`    |
| Google Tag Manager | `GTM-XXXXXXX`     |
| Meta Pixel         | Số (10-20 chữ số) |

**Sự kiện được theo dõi**

Các sự kiện như `purchase`, `add_payment_info`, `view_item` và `view_item_list` được gửi tự động đến các nền tảng phân tích khi khách hàng duyệt và hoàn tất giao dịch mua hàng.

<Check>
  Hỗ trợ trên Storefront, Checkout được lưu trữ, Checkout dạng phủ/lồng và Customer Portal.
</Check>

Tìm hiểu thêm: [Third-Party Analytics](/features/analytics)

### 2. **Tùy chỉnh Giao diện Thanh toán**

Tùy chỉnh giao diện thanh toán thông qua tham số `customization.theme_config` khi tạo phiên thanh toán. Cấu hình màu sắc, phông chữ, bán kính viền và văn bản nút cho cả chế độ sáng và tối.

**Tùy chọn cấu hình**

| Thuộc tính         | Mô tả                               |
| ------------------ | ----------------------------------- |
| `light` / `dark`   | Các hệ màu cho từng chế độ          |
| `font_primary_url` | URL phông chữ tùy chỉnh             |
| `font_size`        | `xs`, `sm`, `md`, `lg`, `xl`, `2xl` |
| `radius`           | Bán kính đường viền (ví dụ: `8px`)  |
| `pay_button_text`  | Văn bản nút tùy chỉnh               |

```typescript theme={null}
const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'prod_123', quantity: 1 }],
  customization: {
    theme_config: {
      radius: '8px',
      pay_button_text: 'Complete Purchase',
      light: { button_primary: '#0066ff', text_primary: '#1a1a1a' },
      dark: { button_primary: '#3385ff', text_primary: '#ffffff' }
    }
  },
  return_url: 'https://yoursite.com/return'
});
```

Tìm hiểu thêm: [Checkout Theme Customization](/features/checkout#checkout-theme-customization)

### 3. **Ngăn thay đổi gói khi thanh toán thất bại**

Tham số mới `on_payment_failure` cho việc thay đổi gói đăng ký điều khiển hành vi khi thanh toán thất bại.

| Chế độ           | Hành vi                                                                |
| ---------------- | ---------------------------------------------------------------------- |
| `prevent_change` | Giữ gói đăng ký hiện tại cho đến khi thanh toán thành công             |
| `apply_change`   | Áp dụng thay đổi gói ngay lập tức bất kể kết quả thanh toán (mặc định) |

```typescript theme={null}
await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_pro',
  proration_billing_mode: 'prorated_immediately',
  on_payment_failure: 'prevent_change'
});
```

<Tip>
  Sử dụng `prevent_change` cho các bản nâng cấp quan trọng nơi bạn muốn đảm bảo thanh toán trước khi cấp quyền truy cập vào các tính năng cao cấp.
</Tip>

Tìm hiểu thêm: [Handling Payment Failures](/developer-resources/subscription-upgrade-downgrade#handling-payment-failures)

## Cập nhật API

### API Sổ cái số dư

Đầu cuối mới `GET /balances/ledger` để truy xuất các mục sổ cái của tài khoản bạn với khả năng lọc và phân trang.

| Tham số                             | Mô tả                                                   |
| ----------------------------------- | ------------------------------------------------------- |
| `created_at_gte` / `created_at_lte` | Lọc theo khoảng ngày                                    |
| `event_type`                        | Lọc theo `payment`, `refund`, `dispute`, `payout`, v.v. |
| `currency`                          | Lọc theo mã tiền tệ                                     |
| `reference_object_id`               | Lọc theo ID thanh toán/hoàn tiền/tranh chấp cụ thể      |

Tìm hiểu thêm: [Balance Ledger API](/api-reference/balance-ledger/list-ledger-entries)

### Phản hồi Thanh toán: `refund_status`

Đã thêm trường `refund_status` vào phản hồi `GET /payments/{paymentId}` để nhanh chóng kiểm tra liệu một khoản thanh toán đã được hoàn tiền mà không cần truy vấn riêng đầu cuối hoàn tiền.