---
title: "Tích hợp ban đầu với Paddle"
description: "Tích hợp Paddle với Adapty để xử lý thanh toán gói đăng ký liền mạch."
---

Adapty hỗ trợ flow web2app bằng cách theo dõi các giao dịch thanh toán và gói đăng ký được thực hiện qua [Paddle](https://www.paddle.com/).

Tích hợp này bao gồm các giao dịch mua bắt đầu từ web và đồng bộ chúng với quyền truy cập ứng dụng di động và analytics, song song với in-app purchase từ các cửa hàng ứng dụng.

Tích hợp này hữu ích trong các trường hợp sau:

- Thu thập dữ liệu gói đăng ký từ cả in-app purchase lẫn giao dịch mua trên website vào một hệ thống duy nhất
- Cấp quyền truy cập các tính năng trả phí trong ứng dụng di động cho người dùng đã mua trên website
- Xem analytics và dữ liệu gói đăng ký từ tất cả kênh bán hàng trên một dashboard

:::note
Apple hiện cho phép các ứng dụng trên US App Store đặt liên kết đến các hệ thống thanh toán bên ngoài, dù các ứng dụng vẫn có thể cần cung cấp in-app purchase song song với các tùy chọn bên ngoài. Hãy kiểm tra các nguyên tắc App Store hiện hành cho khu vực và danh mục ứng dụng của bạn.
:::

:::note
Tích hợp này tập trung vào việc theo dõi và đồng bộ giao dịch mua Paddle từ web. Nếu bạn cần chuyển hướng người dùng từ ứng dụng sang trang thanh toán web, hãy sử dụng [web paywalls](web-paywall) của Adapty.
:::

Để thiết lập tích hợp Paddle, hãy làm theo các bước sau:

## 1\. Kết nối Paddle với Adapty \{#1-connect-paddle-to-adapty\}

Tích hợp sử dụng webhook để gửi dữ liệu gói đăng ký từ Paddle sang Adapty. Để kết nối tài khoản Adapty và Paddle, bạn cần:

1. Cung cấp API key của Paddle.
2. Thêm URL webhook của Adapty vào Paddle.

:::note
Các bước dưới đây áp dụng cho cả môi trường Production lẫn Test. Bạn có thể cấu hình cả hai cùng lúc. Các liên kết được cung cấp dành cho môi trường Production — để lấy liên kết môi trường Test, chỉ cần thêm `sandbox-` vào đầu mỗi URL. Ví dụ: dùng `https://sandbox-vendors.paddle.com/authentication-v2` thay vì `https://vendors.paddle.com/authentication-v2`.
:::

### 1.1. Lấy và thêm API key của Paddle \{#11-get-and-add-paddle-api-keys\}

1. Trong Paddle, vào [Developer Tools → Authentication](https://vendors.paddle.com/authentication-v2) và nhấp **New API key**.

  <img src="/assets/shared/img/paddle-new-key.webp"
  style={{
    border: 'none', /* border width and color */
    width: '700px', /* image width */
    display: 'block', /* for alignment */
    margin: '0 auto' /* center alignment */
  }}
/>

2. Đặt tên cho key và thiết lập ngày hết hạn. Để API key hoạt động với Adapty, bạn cần cấp quyền **Read** cho tất cả các đối tượng. Nhấp **Save**.

  <img src="/assets/shared/img/paddle-key.webp"
  style={{
    border: 'none', /* border width and color */
    width: '300px', /* image width */
    display: 'block', /* for alignment */
    margin: '0 auto' /* center alignment */
  }}
/>

3. Nhấp **Copy key**.

  <img src="/assets/shared/img/copy-paddle-key.webp"
  style={{
    border: 'none', /* border width and color */
    width: '700px', /* image width */
    display: 'block', /* for alignment */
    margin: '0 auto' /* center alignment */
  }}
/>

4. Trong Adapty, vào [App Settings → Paddle](https://app.adapty.io/settings/paddle) và dán key vào phần **Paddle API key**.

:::warning
Nếu bạn đặt ngày hết hạn cho Paddle API key, bạn phải tự tạo key mới và cập nhật trong Adapty trước khi key hết hạn. Tích hợp sẽ ngừng hoạt động mà không có cảnh báo khi key hết hạn, và người dùng sẽ không thể thực hiện giao dịch mua.
:::

  <img src="/assets/shared/img/paddle-api-keys-adapty.webp"
  style={{
    border: 'none', /* border width and color */
    width: '700px', /* image width */
    display: 'block', /* for alignment */
    margin: '0 auto' /* center alignment */
  }}
/>

### 1.2. Thêm các sự kiện sẽ được gửi đến Adapty \{#12-add-events-that-will-be-sent-to-adapty\}

1. Sao chép **Webhook URL** từ trang **Paddle** tương ứng trong Adapty.
2. Trong Paddle, vào [**Developer Tools → Notifications**](https://vendors.paddle.com/notifications-v2) và nhấp **New destination** để thêm webhook.

  <img src="/assets/shared/img/paddle-webhook.webp"
  style={{
    border: '1px solid #727272', /* border width and color */
    width: '700px', /* image width */
    display: 'block', /* for alignment */
    margin: '0 auto' /* center alignment */
  }}
/>

3. Nhập tên mô tả cho webhook. Chúng tôi khuyến nghị đặt tên có chứa "Adapty" để dễ tìm khi cần.

4. Dán **Webhook URL** từ Adapty vào trường **URL**. Đảm bảo bạn đang dùng webhook đúng với môi trường.

5. Đặt **Notification type** thành **Webhook**.

  <img src="/assets/shared/img/paddle-create-webhook.webp"
  style={{
    border: 'none', /* border width and color */
    width: '700px', /* image width */
    display: 'block', /* for alignment */
    margin: '0 auto' /* center alignment */
  }}
/>

6. Chọn các sự kiện sau:

   - `subscription.created`

   - `subscription.updated`

   - `transaction.created`

   - `transaction.updated`

   - `adjustment.created`

   - `adjustment.updated`

  <img src="/assets/shared/img/paddle_events.png"
  style={{
    border: 'none', /* border width and color */
    width: '700px', /* image width */
    display: 'block', /* for alignment */
    margin: '0 auto' /* center alignment */
  }}
/>

7. Nhấp **Save destination** để hoàn tất thiết lập webhook.

### 1.3. Lấy và thêm secret key của webhook \{#13-retrieve-and-add-the-webhook-secret-key\}

1. Trong cửa sổ **Notifications**, nhấp vào ba dấu chấm bên cạnh webhook vừa tạo và chọn **Edit destination**.
2. Một trường mới tên **Secret key** sẽ xuất hiện trong bảng **Edit destination**. Sao chép nó.

  <img src="/assets/shared/img/paddle-webhook-secret-key-copy.webp"
  style={{
    border: 'none', /* border width and color */
    width: '700px', /* image width */
    display: 'block', /* for alignment */
    margin: '0 auto' /* center alignment */
  }}
/>

3. Trong Adapty, vào [App Settings → Paddle](https://app.adapty.io/settings/paddle) và dán key vào trường **Notification secret key**. Key này được dùng để xác minh dữ liệu webhook trong Adapty.

  <img src="/assets/shared/img/paddle-webhook-secret-key.webp"
  style={{
    border: 'none', /* border width and color */
    width: '700px', /* image width */
    display: 'block', /* for alignment */
    margin: '0 auto' /* center alignment */
  }}
/>

### 1.4. Liên kết khách hàng Paddle với hồ sơ người dùng Adapty \{#14-match-paddle-customers-with-adapty-profiles\}

Adapty cần liên kết mỗi giao dịch mua với một [hồ sơ người dùng](profiles-crm) để có thể sử dụng trong ứng dụng. Theo mặc định, hồ sơ người dùng được tạo tự động khi Adapty nhận webhook từ Paddle. Bạn có thể chọn giá trị nào sẽ được dùng làm `customer_user_id` trong Adapty:

1. **Mặc định và khuyến nghị:** `customer_user_id` bạn truyền vào trường `custom_data` (xem [tài liệu Paddle](https://developer.paddle.com/build/transactions/custom-data))
2. `email` từ đối tượng Paddle Customer (xem [tài liệu Paddle](https://developer.paddle.com/paddle-js/methods/paddle-checkout-open/#parameters))
3. Paddle Customer ID theo định dạng `ctm-...` (xem [tài liệu Paddle](https://developer.paddle.com/paddle-js/methods/paddle-checkout-open/#parameters))
4. Không tạo hồ sơ người dùng. Chọn tùy chọn này nếu bạn muốn kiểm soát hồ sơ người dùng nhiều hơn và tự xử lý.

Bạn có thể cấu hình giá trị nào sẽ được sử dụng trong trường **Profile creation behavior** tại [App Settings → Paddle](https://app.adapty.io/settings/paddle).

  <img src="/assets/shared/img/paddle-users.webp"
  style={{
    border: 'none', /* border width and color */
    width: '700px', /* image width */
    display: 'block', /* for alignment */
    margin: '0 auto' /* center alignment */
  }}
/>

## 2. Thêm sản phẩm Paddle vào Adapty \{#2-add-paddle-products-to-adapty\}

:::warning

Hãy nhớ thêm sản phẩm Paddle của bạn vào Adapty Dashboard hoặc thêm Paddle product ID vào các sản phẩm hiện có. Adapty chỉ theo dõi sự kiện cho các giao dịch gắn với những sản phẩm này. Nếu bỏ qua bước này, sự kiện giao dịch sẽ không được tạo.

:::

Paddle hoạt động trong Adapty giống như App Store và Google Play — đây là một nền tảng khác để bạn bán sản phẩm kỹ thuật số. Để cấu hình, hãy thêm các giá trị `product_id` và `price_id` tương ứng từ Paddle trong phần [Products](https://app.adapty.io/products) trong Adapty.

  <img src="/assets/shared/img/paddle-create-product.webp"
  style={{
    border: 'none', /* border width and color */
    width: '700px', /* image width */
    display: 'block', /* for alignment */
    margin: '0 auto' /* center alignment */
  }}
/>

Trong Paddle, product ID có dạng `pro_...` và price ID có dạng `pri_...`. Bạn có thể tìm thấy chúng trong [danh mục sản phẩm Paddle](https://vendors.paddle.com/products-v2) khi mở một sản phẩm cụ thể:

  <img src="/assets/shared/img/paddle-product-price.webp"
  style={{
    border: 'none', /* border width and color */
    width: '700px', /* image width */
    display: 'block', /* for alignment */
    margin: '0 auto' /* center alignment */
  }}
/>

Sau khi đã thêm sản phẩm, bước tiếp theo là đảm bảo Adapty có thể liên kết giao dịch mua với đúng người dùng.

## 3\. Cấp quyền truy cập cho người dùng trên thiết bị di động \{#3-provide-access-to-users-on-the-mobile\}

Để đảm bảo người dùng mua hàng trên web có thể truy cập trên thiết bị di động, hãy gọi `Adapty.activate()` hoặc `Adapty.identify()` với cùng `customer_user_id` mà bạn đã truyền khi thực hiện giao dịch mua. Xem [Identifying users](identifying-users) để biết thêm chi tiết.

## 4\. Kiểm tra tích hợp \{#4-test-your-integration\}

Sau khi thiết lập xong, bạn có thể kiểm tra tích hợp. Các giao dịch thực hiện trong môi trường Test của Paddle sẽ xuất hiện dưới dạng **Test** trong Adapty. Các giao dịch từ môi trường Production sẽ xuất hiện dưới dạng **Production**.

Tích hợp của bạn đã hoàn tất. Người dùng có thể mua gói đăng ký trên website và tự động truy cập các tính năng cao cấp trong ứng dụng di động, trong khi bạn theo dõi toàn bộ analytics gói đăng ký từ Adapty Dashboard thống nhất.

## Những lưu ý quan trọng \{#important-considerations\}

- Trong analytics của Adapty, số tiền giao dịch bao gồm thuế và phí Paddle, khác với dashboard của Paddle nơi số tiền được hiển thị sau khi trừ thuế và phí. Điều này có nghĩa là các con số bạn thấy trong Adapty sẽ cao hơn so với dashboard Paddle của bạn.
- Không giống các cửa hàng khác, hoàn tiền trong Paddle chỉ ảnh hưởng đến giao dịch cụ thể được hoàn tiền và không tự động hủy gói đăng ký. Gói đăng ký sẽ tiếp tục hoạt động trừ khi được hủy rõ ràng.
- Bạn cũng có thể thêm `variation_id` vào trường `custom_data` để quy kết giao dịch mua cho các phiên bản paywall cụ thể. Adapty sẽ xử lý dữ liệu này từ webhook và đưa vào analytics.

### Dùng thử có tính phí \{#paid-trials\}

Khi làm việc với dùng thử có tính phí trong Paddle, bạn cần tạo hai sản phẩm trong Adapty:

1. Tạo một sản phẩm mua một lần và liên kết với price Paddle tính phí cho giai đoạn dùng thử.
2. Sau đó tạo một sản phẩm gói đăng ký (Hàng tháng/Hàng tuần/v.v.) và liên kết với price Paddle có thành phần dùng thử miễn phí.

Từ góc độ Paddle, đây là một sản phẩm với hai price trong một giao dịch — một price cho khoản phí dùng thử (ví dụ: $0,99) và một price cho giai đoạn dùng thử miễn phí ($0,00).

Từ góc độ Adapty, điều này tạo ra hai sự kiện riêng biệt: một giao dịch mua một lần cho khoản thanh toán dùng thử và một sự kiện bắt đầu dùng thử cho sản phẩm gói đăng ký.

Ví dụ: khi người dùng bắt đầu dùng thử có tính phí $0,99 cho gói đăng ký $9,99/tháng, Paddle tạo một giao dịch với cả hai price, trong khi Adapty xử lý đây là một giao dịch mua một lần $0,99 (thanh toán ngay) và một sự kiện bắt đầu dùng thử $0,00 (gói đăng ký trong tương lai $9,99/tháng).

:::note
Khi người dùng hủy dùng thử có tính phí, bạn nhận được các sự kiện **Trial expired** và **Trial renewal canceled**.
:::

## Khai thác tối đa dữ liệu Paddle \{#get-more-from-your-paddle-data\}

:::important
Để các sự kiện Paddle hoạt động với các tích hợp, người dùng của bạn phải đăng nhập vào ứng dụng bằng tài khoản App Store/Google Play ít nhất một lần.
:::

Sau khi tích hợp với Paddle, Adapty sẵn sàng cung cấp thông tin phân tích ngay lập tức. Để tận dụng tối đa dữ liệu Paddle, bạn có thể thiết lập thêm các tích hợp Adapty để chuyển tiếp sự kiện Paddle — tập hợp toàn bộ analytics gói đăng ký vào một Adapty Dashboard duy nhất.

Các tích hợp bạn có thể dùng để chuyển tiếp và phân tích sự kiện Paddle:
- [AppsFlyer](appsflyer)
- [Webhook](webhook)
- [Posthog](posthog)

## Các hạn chế hiện tại \{#current-limitations\}

- **Hủy gói đăng ký**: Paddle có hai tùy chọn hủy gói đăng ký:

  1. Hủy ngay lập tức: Gói đăng ký bị hủy ngay.

  2. Hủy vào cuối kỳ: Gói đăng ký hủy vào cuối chu kỳ thanh toán hiện tại (tương tự gói đăng ký trong ứng dụng trên các cửa hàng ứng dụng).

- **Hoàn tiền**: Adapty theo dõi hoàn tiền toàn phần và một phần.

- **Thời gian ân hạn**: Theo mặc định, Paddle áp dụng thời gian ân hạn cố định 30 ngày cho các sự cố thanh toán, trong thời gian đó gói đăng ký vẫn còn hoạt động. Bạn có thể [tùy chỉnh thời gian ân hạn và hành động sau khi kết thúc (tạm dừng hoặc hủy gói đăng ký)](https://developer.paddle.com/build/retain/configure-payment-recovery-dunning#prerequisites).

  **Dùng thử**: Nếu việc thu tiền thất bại sau khi dùng thử kết thúc, trạng thái gói đăng ký sẽ chuyển sang `past_due`. Trong môi trường production, Retain của Paddle áp dụng cửa sổ dunning để thử lại thanh toán trước khi hủy hoặc tạm dừng gói đăng ký. Trong sandbox, Retain không khả dụng, do đó không có lần thử lại thanh toán nào được thực hiện và gói đăng ký sẽ ở trạng thái `past_due` vô thời hạn.

---

**Xem thêm:**

- [Xác thực giao dịch mua trong Paddle, lấy mức độ truy cập và import lịch sử giao dịch từ Paddle bằng server-side API](api-adapty/operations/validatePaddlePurchase)