> ## 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 Stripe cho Ecommerce

> Hướng dẫn kết nối Stripe bằng Secret Key, kích hoạt thanh toán thẻ quốc tế Card (Stripe), quản lý đơn hàng và quy trình thanh toán trên ChatbotX Ecommerce.

Cổng thanh toán **Stripe** trên ChatbotX Ecommerce cho phép doanh nghiệp tiếp nhận trực tiếp các khoản thanh toán bằng thẻ tín dụng và thẻ ghi nợ quốc tế (Visa, Mastercard, American Express, JCB...). Doanh thu từ các đơn hàng sẽ được chuyển thẳng về tài khoản Stripe của bạn mà không qua bất kỳ khâu trung gian nào, đảm bảo tính an toàn và minh bạch tài chính tối đa.

> [card] Hỗ trợ thẻ quốc tế toàn diện
>
> Chấp nhận hầu hết các loại thẻ thanh toán phổ biến toàn cầu với chuẩn bảo mật khắt khe PCI-DSS cấp độ 1.

> [card] Doanh thu về thẳng tài khoản
>
> Tiền thanh toán của người mua được chuyển trực tiếp vào tài khoản ngân hàng liên kết với Stripe của doanh nghiệp.

> [card] Tự động cấu hình Webhook
>
> Hệ thống tự động thiết lập thông báo thanh toán và mã hóa bảo mật Secret Key ngay khi kết nối.

> [card] Cơ chế giữ đơn hàng 30 phút
>
> Đơn hàng và tồn kho được tạm giữ trong 30 phút để người mua yên tâm hoàn tất thông tin xác thực thẻ.

## Lấy khóa bí mật (Secret Key) từ Stripe Dashboard

Để liên kết tài khoản Stripe với ChatbotX, bạn cần sao chép mã khóa bí mật (**Secret Key**) từ bảng điều khiển quản trị của Stripe.

**1. Đăng nhập tài khoản Stripe**

Truy cập trang quản trị Stripe tại `dashboard.stripe.com` và đăng nhập tài khoản của bạn.

**2. Mở trang quản lý khóa API**

Tại thanh menu góc trên bên phải, chọn mục **Developers** và nhấp vào thẻ **API keys**.

**3. Sao chép Secret Key phù hợp**

Hệ thống hỗ trợ các loại khóa sau:

* **Khóa thử nghiệm (`sk_test_...`)**: Dùng khi bạn đang chạy thử nghiệm cửa hàng (Test mode) để thanh toán bằng thẻ test của Stripe mà không trừ tiền thật.
* **Khóa thực tế (`sk_live_...`)**: Dùng cho hoạt động kinh doanh chính thức để nhận tiền thật từ khách hàng.
* **Khóa giới hạn quyền (`rk_...`)**: Khóa Restricted Key có tối thiểu các quyền đọc tài khoản, tạo phiên thanh toán Checkout Sessions, xử lý hoàn tiền Refunds và đăng ký Webhook Endpoints.

Nhấn **Reveal secret key** và sao chép chuỗi mã khóa để dán vào ChatbotX.

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

**1. Mở tab Integrations trong Settings**

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

**2. Chọn cổng Stripe và nhấn Use secret key**

Cuộn danh sách xuống mục **Stripe** và nhấn nút **Use secret key** màu đỏ.

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

**3. Dán Secret Key vào hộp thoại kết nối**

Trong hộp thoại **Connect Stripe**, dán chuỗi khóa bí mật vừa sao chép từ Stripe Dashboard vào ô **Secret key**.

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

> [!NOTE]
>
> Khi bạn nhấn kết nối, ChatbotX sẽ tự động kiểm tra tính hợp lệ của khóa, tự động đăng ký các điểm nhận thông báo thanh toán (Webhook Endpoints) trên tài khoản Stripe của bạn và mã hóa lưu trữ khóa an toàn tuyệt đối.

**4. Hoàn tất kết nối**

Nhấn nút **Connect** màu xanh để kích hoạt liên kết. Sau khi kết nối thành công, mục Stripe sẽ hiển thị trạng thái hoạt động.

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

Sau khi đã tích hợp Stripe vào Workspace, bạn kích hoạt phương thức thanh toán bằng thẻ cho cửa hàng:

**1. Mở cài đặt thanh toán Ecommerce**

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

**2. Tích chọn phương thức Card (Stripe)**

Nhấp vào ô chọn tại trường **Payment methods** để mở danh sách và tích chọn **Card (Stripe)**.

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

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

**3. Lưu thiết lập**

Nhấn nút **Save** ở góc dưới bên phải để lưu lại cấu hình thanh toán mới.

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

Quy trình thanh toán bằng thẻ quốc tế qua Stripe diễn ra nhanh chóng và thuận tiện cho người mua:

**1. Lựa chọn hình thức thanh toán bằng thẻ**

Tại màn hình thanh toán Webview, sau khi nhập thông tin nhận hàng, người mua chọn mục **Card** tại phần **Payment**.

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

Hệ thống thông báo thời hạn giữ đơn hàng:

* *You will pay on the next page*: Khách hàng sẽ thực hiện nhập thông tin thẻ tại bước 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 30 phút.

**2. Nhập thông tin thẻ trên giao diện bảo mật Stripe**

Khách hàng kiểm tra tổng thanh toán và nhấn **Continue to payment**. Giao diện thanh toán bảo mật của Stripe sẽ hiển thị để người mua nhập số thẻ, ngày hết hạn và mã bảo mật CVC, hoặc lựa chọn thanh toán nhanh qua ví di động được hỗ trợ.

**3. Xác nhận đơn hàng và thanh toán thành công**

Khi ngân hàng phát hành thẻ xác nhận giao dịch trừ tiền thành công, người mua được tự động chuyển về trang biên lai đơn hàng trên Webview:

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

* Thông báo xác nhận: **Payment received. Thank you for your order!**
* Chi tiết đơn hàng hiển thị mã đơn (ví dụ: `Order #7`), danh sách sản phẩm, số lượng, phí giao hàng và số tiền đã thanh toán.
* Dòng phương thức thanh toán ghi nhận: **Card · Paid**.

## Quản lý đơn hàng Stripe tại tab Orders

Các đơn hàng thanh toán thành công qua thẻ Stripe được đồng bộ tức thì về bảng quản lý đơn hàng:

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

Trong tab **Orders**, cột **Payment** giúp bạn dễ dàng phân biệt các nguồn tiền thanh toán:

| Trạng thái và Phương thức | Ý nghĩa vận hành |
| - | - |
| **Paid** (Huy hiệu xanh lá kèm nhãn `Card (Stripe)`) | Đơn hàng đã được thanh toán đầy đủ qua thẻ quốc tế bởi Stripe. Tiền đã được chuyển vào tài khoản Stripe của bạn. Nhân viên vận hành có thể duyệt đơn (**Accept**) và chuẩn bị giao hàng ngay mà không cần thu thêm tiền. |
| **Paid** (Huy hiệu xanh lá kèm nhãn `PayPal`) | Đơn hàng đã được thanh toán trực tuyến qua cổng PayPal. |
| **Waiting for payment - until \[thời gian]** (Huy hiệu cam) | Đơn hàng trực tuyến đang trong khung thời gian 30 phút chờ người mua hoàn tất thanh toán. |
| **Pay on delivery** (Huy hiệu xám kèm nhãn `Cash on Delivery`) | Đơn hàng giao hàng thu tiền mặt tận nơi (COD). |

> [!NOTE]
>
> Sau khi thanh toán thành công, hệ thống tự động kích hoạt kịch bản thông báo xác nhận đơn hàng gửi trực tiếp vào cuộc trò chuyện Messenger của người mua kèm theo biên lai thanh toán chi tiết.


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