> ## Documentation Index
> Fetch the complete documentation index at: https://chatbotx.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Tích hợp cổng thanh toán PayPal cho Ecommerce

> Hướng dẫn kết nối tài khoản PayPal, kích hoạt phương thức thanh toán, quản lý đơn hàng và trải nghiệm thanh toán trực tuyến trên ChatbotX Ecommerce.

Cổng thanh toán **PayPal** trên ChatbotX Ecommerce cho phép doanh nghiệp tiếp nhận các giao dịch thanh toán trực tuyến toàn cầu từ khách hàng thông qua số dư tài khoản PayPal hoặc thẻ thanh toán quốc tế liên kết. Tính năng giúp mở rộng phạm vi bán hàng xuyên biên giới, tăng tỷ lệ hoàn tất đơn hàng và tự động hóa toàn diện quy trình xác nhận thanh toán ngay trên giao diện Webview.

> [card] Thanh toán quốc tế tin cậy
>
> Tiếp nhận tiền thanh toán từ hàng trăm quốc gia với ví điện tử PayPal và thẻ tín dụng hoặc ghi nợ quốc tế.

> [card] Tự động đối soát và khớp đơn
>
> Đơn hàng tự động cập nhật sang trạng thái đã thanh toán ngay sau khi giao dịch trên PayPal hoàn tất.

> [card] Cơ chế giữ đơn thông minh
>
> Tự động giữ hàng trong 30 phút để người mua hoàn tất giao dịch thanh toán trên cổng PayPal an toàn.

> [card] Nhận diện môi trường linh hoạt
>
> Hệ thống tự động phân biệt và chuyển đổi giữa môi trường thử nghiệm (Sandbox) và thực tế (Live) theo khóa API.

## Chuẩn bị tài khoản và khóa API PayPal Developer

Trước khi thiết lập kết nối trên ChatbotX, bạn cần tạo một ứng dụng REST API trên cổng nhà phát triển của PayPal để lấy hai thông số xác thực: **Client ID** và **Secret Key**.

**1. Đăng nhập cổng PayPal Developer**

Truy cập cổng nhà phát triển PayPal tại địa chỉ `developer.paypal.com` và đăng nhập bằng tài khoản doanh nghiệp (PayPal Business) của bạn.

**2. Tạo ứng dụng REST API**

Vào mục **Dashboard** > **Apps & Credentials**. Tại đây, bạn chọn môi trường làm việc:

* **Sandbox**: Dùng để thử nghiệm luồng đặt hàng và thanh toán mà không phát sinh giao dịch tiền thực.
* **Live**: Dùng cho hoạt động kinh doanh thực tế để thu tiền từ người mua.

Nhấn nút **Create App**, đặt tên cho ứng dụng (ví dụ: *ChatbotX Store*) và xác nhận tạo.

**3. Sao chép Client ID và Secret Key**

Trong trang chi tiết của ứng dụng vừa tạo, sao chép chuỗi ký tự tại mục **Client ID** và nhấn **Show** tại mục **Secret** để lấy mã khóa bí mật. Bạn sẽ dán hai giá trị này vào ChatbotX ở bước tiếp theo.

## Kết nối tài khoản PayPal với Workspace

**1. Mở khu vực Integrations trong Settings**

Từ menu điều hướng bên trái của ChatbotX, chọn mục **Settings** (biểu tượng bánh răng ở góc dưới) và chuyển sang tab **Integrations** ở thanh trên cùng.

**2. Chọn cổng PayPal và nhấn Connect**

Cuộn danh sách tích hợp xuống mục **PayPal** và nhấn vào nút **Connect** màu đỏ.

![Ecommerce Paypal Integration Connect](https://mintcdn.com/chatbotx/LqFZOV_WJ0Vv-4Z9/images/ecommerce_paypal_integration_connect.png?fit=max\&auto=format\&n=LqFZOV_WJ0Vv-4Z9\&q=85\&s=7794145552e3dd3966443c4dbf325f47)

**3. Nhập Client ID và Secret**

Hộp thoại **Connect PayPal** hiển thị yêu cầu thông tin xác thực từ PayPal Developer:

* **Client ID**: Dán chuỗi Client ID vừa sao chép từ ứng dụng PayPal.
* **Secret**: Dán mã khóa Secret bí mật tương ứng.

![Ecommerce Paypal Connect Modal](https://mintcdn.com/chatbotx/LqFZOV_WJ0Vv-4Z9/images/ecommerce_paypal_connect_modal.png?fit=max\&auto=format\&n=LqFZOV_WJ0Vv-4Z9\&q=85\&s=be093569331db5e6427b69300a2321f8)

> [!NOTE]
>
> ChatbotX tự động nhận diện khóa thuộc môi trường kiểm thử (Sandbox) hay môi trường thực tế (Live) dựa vào tiền tố và định dạng của cặp khóa. Bạn không cần cấu hình thủ công loại môi trường.

**4. Xác nhận kết nối**

Nhấn nút **Connect** màu xanh để hoàn tất liên kết tài khoản. Khi kết nối thành công, nút trạng thái tại mục PayPal sẽ chuyển sang chế độ đã kết nối.

## Kích hoạt phương thức thanh toán PayPal trong Ecommerce

Sau khi hoàn tất kết nối tại mục Integrations, bạn kích hoạt phương thức thanh toán này cho cửa hàng:

**1. Truy cập cài đặt thanh toán cửa hàng**

Từ menu bên trái, chọn **Tools** > **Ecommerce**, chuyển sang tab **Settings** và chọn mục **Payments** ở thanh thực đơn bên trái.

**2. Tích chọn phương thức PayPal**

Nhấp vào ô lựa chọn tại trường **Payment methods** để mở menu các phương thức thanh toán và tích chọn **PayPal**.

![Ecommerce Paypal Settings Payment Methods](https://mintcdn.com/chatbotx/LqFZOV_WJ0Vv-4Z9/images/ecommerce_paypal_settings_payment_methods.png?fit=max\&auto=format\&n=LqFZOV_WJ0Vv-4Z9\&q=85\&s=3cdf430ab832f15ebe648fda57667448)

> [!NOTE]
>
> Phương thức thanh toán nằm đầu tiên trong danh sách chọn sẽ là phương thức được hệ thống tự động chọn mặc định khi người mua mở màn hình thanh toán. Bạn có thể sắp xếp hoặc bật đồng thời nhiều hình thức thanh toán như **Cash on Delivery**, **Card (Stripe)** và **PayPal**.

**3. Kiểm tra đơn vị tiền tệ phù hợp**

Đảm bảo đơn vị tiền tệ tại trường **Currency** được PayPal hỗ trợ thanh toán quốc tế (như `USD`, `EUR`, `AUD`, `CAD`, `GBP` hoặc `SGD`).

**4. Lưu cấu hình**

Nhấn nút **Save** ở góc dưới bên phải để áp dụng phương thức thanh toán mới cho toàn bộ gian hàng.

## Trải nghiệm thanh toán PayPal của khách hàng trên Webview

Khi khách hàng duyệt sản phẩm và tiến hành đặt hàng, hành trình thanh toán qua PayPal diễn ra theo trình tự sau:

**1. Lựa chọn phương thức thanh toán PayPal**

Tại trang thanh toán Webview, sau khi điền thông tin người nhận và địa chỉ giao hàng, người mua cuộn xuống phần **Payment** và chọn mục **PayPal**.

![Ecommerce Paypal Checkout Webview](https://mintcdn.com/chatbotx/LqFZOV_WJ0Vv-4Z9/images/ecommerce_paypal_checkout_webview.png?fit=max\&auto=format\&n=LqFZOV_WJ0Vv-4Z9\&q=85\&s=43371bd560c9be14107726217f56a889)

Hệ thống hiển thị dòng thông báo rõ ràng cho người mua:

* *You will pay on the next page*: Người mua sẽ thực hiện thanh toán trên trang tiếp theo.
* *Your order is held for 30 minutes*: Đơn hàng và số lượng tồn kho được tạm giữ trong vòng 30 phút để người mua hoàn tất giao dịch.

**2. Chuyển hướng sang cổng thanh toán bảo mật PayPal**

Khách hàng kiểm tra tổng số tiền thanh toán cuối cùng và nhấn nút **Continue to payment**. Hệ thống tự động chuyển hướng khách hàng sang giao diện đăng nhập ví PayPal hoặc trang nhập thẻ quốc tế được bảo vệ bởi PayPal.

**3. Xác nhận thanh toán thành công**

Ngay sau khi giao dịch trừ tiền thành công, khách hàng được tự động chuyển về trang biên lai đơn hàng trên Webview:

![Ecommerce Paypal Order Success](https://mintcdn.com/chatbotx/LqFZOV_WJ0Vv-4Z9/images/ecommerce_paypal_order_success.png?fit=max\&auto=format\&n=LqFZOV_WJ0Vv-4Z9\&q=85\&s=ecdf662a5f9f0f3af6f38c5a6703d816)

* Khung thông báo màu xanh hiển thị: **Payment received. Thank you for your order!**
* Chi tiết đơn hàng hiển thị mã số đơn (ví dụ: `Order #6`), bảng kê sản phẩm, tiền hàng, phí giao hàng và tổng tiền đã thanh toán.
* Dòng trạng thái phương thức thanh toán ghi nhận: **PayPal · Paid**.

## Quản lý và theo dõi đơn hàng PayPal tại tab Orders

Toàn bộ các đơn hàng thanh toán qua PayPal được đồng bộ theo thời gian thực về tab **Orders** trong công cụ **Ecommerce**:

![Ecommerce Paypal Orders Management](https://mintcdn.com/chatbotx/LqFZOV_WJ0Vv-4Z9/images/ecommerce_paypal_orders_management.png?fit=max\&auto=format\&n=LqFZOV_WJ0Vv-4Z9\&q=85\&s=a756d9bf7f44fbf478435ee76605deaf)

Cột **Payment** trong bảng quản lý đơn hàng hiển thị rõ các trạng thái:

| Trạng thái hiển thị | Ý nghĩa và hành động vận hành |
| - | - |
| **Paid** (Huy hiệu xanh lá kèm biểu tượng ví PayPal) | Khách hàng đã thanh toán thành công qua PayPal. Nhân viên vận hành có thể duyệt đơn (**Accept**) và chuẩn bị hàng đóng gói ngay. |
| **Waiting for payment - until \[thời gian]** (Huy hiệu màu cam kèm đồng hồ đếm lùi) | Khách hàng đã nhấn đặt hàng và chọn thanh toán PayPal nhưng chưa hoàn tất trừ tiền. Đơn hàng được hệ thống tạm giữ trong vòng 30 phút. Nếu quá thời hạn trên mà khách không thanh toán, hệ thống sẽ tự động hủy đơn và hoàn trả tồn kho. |
| **Pay on delivery** (Huy hiệu xám) | Đơn hàng áp dụng hình thức thanh toán khi nhận hàng (COD). |

> [!NOTE]
>
> Khi khách hàng hoàn tất thanh toán thành công, ChatbotX cũng đồng thời gửi tin nhắn xác nhận kèm biên lai thanh toán vào cuộc trò chuyện Messenger của khách hàng theo cấu hình kịch bản xác nhận đơn hàng của bạn.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.