Giới thiệu
🎯 Mô-đun này làm gì?
Mô-đun Payments cho phép bạn quản lý quy trình thanh toán và giao dịch cho cửa hàng thương mại điện tử của bạn. Làm việc với thanh toán và giao dịch là một phần quan trọng của bất kỳ dự án thương mại điện tử nào. Nó tích hợp với các cổng thanh toán như Stripe để xử lý các phiên thanh toán, theo dõi giao dịch và quản lý trạng thái thanh toán.
Hãy coi nó như hệ thống quản lý thanh toán của bạn - bạn cấu hình các tài khoản thanh toán trong bảng điều khiển quản trị OneEntry (Payments > Accounts), tạo nhiều tài khoản cho các loại thanh toán khác nhau như kết nối hệ thống thanh toán hoặc thêm thanh toán bằng tiền mặt, và mô-đun này xử lý việc tạo phiên thanh toán, theo dõi trạng thái và quản lý giao dịch.
📖 Giải thích đơn giản
Mỗi ứng dụng thương mại điện tử cần quy trình thanh toán an toàn:
- 💳 Chấp nhận thanh toán - Thẻ tín dụng, thẻ ghi nợ, ví điện tử
- 🔒 Xử lý an toàn - Xử lý thanh toán tuân thủ PCI
- 🔄 Trạng thái thanh toán - Theo dõi đang chờ, đã hoàn thành, thất bại, hoàn tiền
- 💰 Hoàn tiền - Xử lý hoàn tiền toàn bộ hoặc một phần
- 📊 Lịch sử thanh toán - Xem tất cả giao dịch
- 🔗 Tích hợp cổng - Stripe, PayPal, cổng tùy chỉnh
Vấn đề với việc xử lý thanh toán thủ công:
Vấn đề:
- 🔒 Rủi ro bảo mật - Lưu trữ dữ liệu thẻ nhạy cảm
- 📋 Tuân thủ PCI - Cần chứng nhận tốn kém
- 💸 Không theo dõi hoàn tiền - Quản lý hoàn tiền thủ công
- 🔄 Không có lịch sử thanh toán - Khó theo dõi giao dịch
Giải pháp Payments:
Lợi ích:
- 🔒 Tuân thủ PCI - Thanh toán an toàn được mã hóa
- 📊 Theo dõi thanh toán - Lịch sử giao dịch đầy đủ
- 🔄 Hoàn tiền tự động - Xử lý hoàn tiền dễ dàng
- 💸 Nhiều cổng - Stripe, PayPal, tùy chỉnh
✨ Khái niệm chính
Thanh toán là gì?
Một Thanh toán là một bản ghi giao dịch tài chính chứa:
- Phương thức thanh toán - Thẻ, PayPal, chuyển khoản ngân hàng
- Số tiền - Số tiền giao dịch và loại tiền tệ
- Tham chiếu đơn hàng - ID đơn hàng liên quan
- Trạng thái thanh toán - Đang chờ, đã hoàn thành, thất bại, hoàn tiền
- Chi tiết cổng - ID giao dịch Stripe, tham chiếu PayPal
- Thông tin khách hàng - Chi tiết thanh toán
- Thời gian - Ngày tạo, xử lý, hoàn thành
Các loại tài khoản có sẵn
| Loại | Khi nào sử dụng | Cấu hình cần thiết |
|---|---|---|
| Stripe | Kết nối hệ thống thanh toán Stripe với dự án của bạn | Tài khoản Stripe, URL |
| Tùy chỉnh | Hệ thống thanh toán thay thế hoặc thanh toán bằng tiền mặt | Cấu hình tùy chỉnh |
Vòng đời thanh toán
1. Tạo tài khoản thanh toán trong bảng điều khiển quản trị
(Cấu hình tài khoản Stripe hoặc tùy chỉnh)
↓
2. Khách hàng đặt hàng
(Đơn hàng được tạo trong mô-đun Orders)
↓
3. Tạo phiên thanh toán
(Payments.createSession(orderId, type))
↓
4. Khách hàng được chuyển hư ớng đến URL thanh toán
(Trang thanh toán Stripe hoặc trang thanh toán tùy chỉnh)
↓
5. Khách hàng hoàn tất thanh toán
(Thanh toán được xử lý bởi cổng)
↓
6. Trạng thái thanh toán được cập nhật
(đang chờ → đang xử lý → đã thanh toán/đã hủy/đã hết hạn)
↓
7. Thông báo được nhận
↓
8. Trạng thái đơn hàng được đồng bộ
(Trạng thái thanh toán liên kết với trạng thái đơn hàng)
Trạng thái thanh toán
Hệ thống bao gồm bốn trạng thái thanh toán được thiết lập sẵn cho biết trạng thái của giao dịch đang được xử lý:
| Trạng thái | Ý nghĩa | Khi nào xảy ra |
|---|---|---|
| Đang chờ | Trạng thái giao dịch ban đầu | Phiên thanh toán vừa được tạo |
| Đã thanh toán | Giao dịch đã hoàn thành thành công | Thanh toán được xác nhận bởi cổng |
| Đã hủy | Giao dịch đã bị hủy | Khách hàng đã hủy thanh toán |
| Đã hết hạn | Thời gian hiệu lực của giao dịch đã kết thúc | Thời gian phiên đã vượt quá |
Quan trọng: Trong cài đặt thanh toán, bạn không thể tạo hoặc sửa đổi trạng thái. Tuy nhiên, bạn có thể liên kết các trạng thái thanh toán được thiết lập sẵn này với các trạng thái lưu trữ đơn hàng để cho phép đồng bộ hóa tự động giữa hệ thống thanh toán và đơn hàng.
Phương thức thanh toán
| Phương thức | Mô tả | Hỗ trợ cổng |
|---|---|---|
| credit_card | Visa, Mastercard, Amex | Stripe, PayPal |
| debit_card | Thẻ ghi nợ | Stripe, PayPal |
| paypal | Tài khoản PayPal | PayPal |
| bank_transfer | Chuyển khoản, ACH | Tùy chỉnh |
| apple_pay | Ví Apple Pay | Stripe |
| google_pay | Ví Google Pay | Stripe |
| cash_on_delivery | Thanh toán khi giao hàng | N/A |
Tại sao sử dụng mô-đun Payments?
| Lợi ích | Mô tả |
|---|---|
| Tuân thủ PCI | Xử lý thanh toán an toàn được mã hóa |
| Tích hợp cổng | Tích hợp sẵn Stripe, PayPal |
| Theo dõi thanh toán | Lịch sử giao dịch đầy đủ |
| Quản lý hoàn tiền | Hoàn tiền toàn bộ/một phần dễ dàng |
| Bảo vệ gian lận | Phát hiện gian lận tích hợp |
| 3D Secure | Hỗ trợ xác thực SCA |
| Đa tiền tệ | Hỗ trợ nhiều loại tiền tệ |
📋 Những điều bạn cần biết
Tài khoản thanh toán được tạo trong bảng điều khiển quản trị
Bạn không thể tạo tài khoản thanh toán qua SDK - chúng được tạo trong bảng điều khiển quản trị OneEntry:
Bảng điều khiển quản trị OneEntry → Payments → Accounts → Tạo tài khoản → Điền biểu mẫu → Nhấp "Thêm"
Quy trình tạo:
- Điền vào biểu mẫu với ba trường bắt buộc:
- Tên - Chuỗi định danh không duy nhất
- Loại - Chọn từ danh sách: "Stripe" hoặc "Tùy chỉnh"
- Mã thông báo - Chuỗi định danh duy nhất
- Nhấp "Thêm" để tạo tài khoản
Quản lý tài khoản:
- Chỉnh sửa - Chọn tài khoản, nhấp vào biểu tượng chỉnh sửa, sửa đổi tên/loại/mã thông báo/tham số Stripe
- Ẩn - Nhấp vào biểu tượng mắt để ẩn tài khoản khỏi các lựa chọn thiết lập lưu trữ đơn hàng
- Xóa - Chọn tài khoản, nhấp vào biểu tượng xóa, xác nhận xóa
SDK được sử dụng để lấy tài khoản thanh toán và tạo phiên thanh toán, không phải để quản lý tài khoản.
Các loại tài khoản thanh toán
Có hai loại tài khoản thanh toán có sẵn:
| Loại | Mô tả |
|---|---|
| Stripe | Chọn loại này để kết nối hệ thống thanh toán Stripe |
| Tùy chỉnh | Dành cho các hệ thống thanh toán thay thế hoặc thanh toán bằng tiền mặt |
Cấu hình cụ thể cho Stripe:
- URL thành công - URL chuyển hướng sau khi thanh toán thành công
- URL hủy - URL chuyển hướng nếu thanh toán bị hủy
- Thời gian phiên - Thời gian hết hạn phiên tính bằng phút
Đồng bộ hóa trạng thái thanh toán
Các trạng thái thanh toán có thể được liên kết với các trạng thái lưu trữ đơn hàng:
Bảng điều khiển quản trị OneEntry → Payments → Statuses → Chọn lưu trữ đơn hàng → Liên kết trạng thái → Lưu
Quy trình ánh xạ trạng thái:
- Điều hướng đến phần Trạng thái trong Payments
- Chọn hệ thống lưu trữ đơn hàng mong muốn
- Liên kết mỗi trạng thái thanh toán được thiết lập sẵn với giá trị trạng thái lưu trữ đơn hàng tương ứng
- Xác minh tất cả các ánh xạ là chính xác
- Nhấp Lưu để áp dụng thay đổi
Điều này cho phép cập nhật trạng thái tự động trong các bản ghi đơn hàng khi trạng thái thanh toán thay đổi.
Không bao giờ lưu trữ dữ liệu thẻ thô
QUAN TRỌNG: Không bao giờ lưu trữ số thẻ tín dụng, CVV hoặc ngày hết hạn đầy đủ.
Tại sao?
- Tuân thủ PCI DSS yêu cầu xử lý an toàn
- Lưu trữ dữ liệu thẻ khiến bạn phải chịu trách nhiệm
- OneEntry không bao giờ lưu trữ chi tiết thẻ thô
💡 Ghi chú quan trọng
Tài khoản thanh toán được tạo trong bảng điều khiển quản trị
Nhớ: SDK được sử dụng để lấy tài khoản thanh toán và tạo phiên, không phải để tạo tài khoản.
Để tạo/sửa đổi tài khoản thanh toán: Sử dụng Bảng điều khiển quản trị OneEntry.
Quản lý tài khoản thanh toán
Tạo tài khoản trong bảng điều khiển quản trị:
- Điều hướng đến Payments > Accounts
- Điền vào biểu mẫu với Tên, Loại và Mã thông báo
- Đối với tài khoản Stripe, cấu hình URL thành công, URL hủy và Thời gian phiên
- Nhấp "Thêm" để tạo
Quản lý tài khoản:
- Chỉnh sửa - Sửa đổi tên, loại, mã thông báo hoặc tham số cụ thể cho Stripe
- Ẩn - Nhấp vào biểu tượng mắt để ẩn khỏi thiết lập lưu trữ đơn hàng (không xóa)
- Xóa - Xóa hoàn toàn các tài khoản không sử dụng
Quan trọng: Chỉ các tài khoản không sử dụng mới có thể bị xóa.
Cấu hình trạng thái thanh toán
Quan trọng: Bạn không thể tạo hoặc sửa đổi trạng thái thanh toán trong bảng điều khiển quản trị. Hệ thống có bốn trạng thái được thiết lập sẵn: Đang chờ, Đã thanh toán, Đã hủy, Đã hết hạn.
Quy trình đồng bộ hóa trạng thái:
- Điều hướng đến Payments > Statuses
- Chọn hệ thống lưu trữ đơn hàng
- Liên kết các trạng thái thanh toán được thiết lập sẵn với các trạng thái lưu trữ đơn hàng
- Nhấp Lưu để áp dụng thay đổi
Điều này cho phép cập nhật trạng thái đơn hàng tự động khi trạng thái thanh toán thay đổi.
Các loại phiên
Có hai loại phiên có sẵn:
| Loại | Mô tả |
|---|---|
| session | Tạo một trang thanh toán Stripe Checkout với liên kết thanh toán |
| intent | Tạo một ý định thanh toán cho quy trình thanh toán trực tiếp |
An ninh trước tiên
🔒 Quy tắc bảo mật quan trọng:
- Không bao giờ lưu trữ dữ liệu thẻ thô - Sử dụng mã hóa
- Chỉ sử dụng HTTPS - Tất cả các trang thanh toán phải có SSL
- Xác thực trên máy chủ - Không bao giờ tin tưởng dữ liệu phía khách hàng
- Ghi lại giao dịch - Giữ lại dấu vết kiểm toán
- Xử lý PII cẩn thận - Bảo vệ dữ liệu khách hàng
Tuân thủ PCI
✅ OneEntry xử lý tuân thủ PCI cho bạn:
- Xử lý thanh toán được mã hóa
- Tích hợp cổng an toàn
- Không lưu trữ dữ liệu thẻ thô
- Truyền tải được mã hóa
Trách nhiệm của bạn:
- Sử dụng HTTPS trên các trang thanh toán
- Không ghi lại dữ liệu nhạy cảm
- Tuân theo các thực tiễn bảo mật tốt nhất
Kiểm tra trạng thái thanh toán
Đối với các thanh toán bất đồng bộ, kiểm tra các cập nhật trạng thái:
Giới hạn hoàn tiền
Quy tắc hoàn tiền quan trọng:
- Chỉ có thể hoàn tiền cho các thanh toán đã hoàn thành
- Hoàn tiền một phần không được vượt quá số tiền gốc
- Một số cổng có giới hạn thời gian (ví dụ: 180 ngày)
- Hoàn tiền là bất đồng bộ (có thể mất vài ngày)
📊 Bảng tham khảo nhanh
| Phương thức | Mô tả | Trường hợp sử dụng |
|---|---|---|
| getAccounts() | Lấy tất cả tài khoản thanh toán | Liệt kê các phương thức thanh toán có sẵn |
| getAccountById() | Lấy tài khoản thanh toán theo ID | Lấy chi tiết tài khoản cụ thể |
| createSession() 🔐 | Tạo phiên thanh toán | Tạo liên kết thanh toán cho đơn hàng |
| getSessions() 🔐 | Lấy tất cả các phiên thanh toán (theo trang) | Xem lịch sử phiên thanh toán |
| getSessionById() 🔐 | Lấy phiên thanh toán theo ID | Kiểm tra trạng thái phiên cụ thể |
| getSessionByOrderId() 🔐 | Lấy phiên thanh toán theo ID đơn hàng | Tìm thanh toán cho đơn hàng cụ thể |
🔐 = Cần có quyền xác thực
❓ Câu hỏi thường gặp (FAQ)
Làm thế nào để tôi thiết lập thanh toán Stripe?
Tạo một tài khoản thanh toán trong bảng điều khiển quản trị với loại "Stripe", sau đó cấu hình URL thành công, URL hủy và Thời gian phiên. Sử dụng createSession() để tạo các liên kết thanh toán chuyển hướng khách hàng đến Stripe Checkout.
Sự khác biệt giữa các loại thanh toán session và intent là gì?
Một session tạo một trang thanh toán Stripe Checkout với một URL chuyển hướng, lý tưởng cho các trang thanh toán được lưu trữ. Một intent tạo một ý định thanh toán cho việc tích hợp biểu mẫu thanh toán tùy chỉnh trực tiếp trong ứng dụng của bạn.
Tôi có thể hỗ trợ nhiều phương thức thanh toán không?
Có! Tạo nhiều tài khoản thanh toán (Stripe, tùy chỉnh, thanh toán khi giao hàng) trong bảng điều khiển quản trị. Mỗi đơn hàng có thể sử dụng một tài khoản thanh toán khác nhau dựa trên lựa chọn của khách hàng.
Làm thế nào để tôi liên kết trạng thái thanh toán với trạng thái đơn hàng?
Trong bảng điều khiển quản trị, đi đến Payments > Statuses, chọn lưu trữ đơn hàng của bạn và ánh xạ bốn trạng thái thanh toán được thiết lập sẵn (Đang chờ, Đã thanh toán, Đã hủy, Đã hết hạn) với các trạng thái đơn hàng tương ứng. Điều này cho phép đồng bộ hóa tự động.
Điều gì xảy ra nếu một phiên thanh toán hết hạn?
Các phiên thanh toán có thời gian sống có thể cấu hình (được thiết lập trong cài đặt tài khoản). Nếu khách hàng không hoàn tất thanh toán trong thời gian này, trạng thái phiên sẽ chuyển sang "Đã hết hạn" và họ sẽ cần tạo một phiên thanh toán mới.
🎓 Thực hành tốt nhất
- Sử dụng mã hóa - Luôn mã hóa thẻ với Stripe.js
- Xác thực số tiền - Kiểm tra tổng số trên máy chủ, không chỉ trên khách hàng
- Xử lý lỗi một cách duyên dáng - Cung cấp thông điệp lỗi rõ ràng cho người dùng
- Ghi lại giao dịch - Giữ lại dấu vết kiểm toán cho tất cả các khoản thanh toán
- Sử dụng webhooks - Lắng nghe các cập nhật trạng thái thanh toán
- Kiểm tra với khóa thử nghiệm - Sử dụng chế độ thử nghiệm của Stripe trước khi sản xuất
- Xử lý 3D Secure - Triển khai quy trình xác thực SCA
- Lưu trữ ID giao dịch - Giữ lại các tham chiếu cổng cho các tranh chấp
Thêm thông tin về thanh toán trong bảng điều khiển quản trị OneEntry: https://doc.oneentry.cloudhttps://doc.oneentry.cloud/docs/category/payments
Định nghĩa của mô-đun Payments
Mô-đun Payments quản lý quy trình thanh toán và giao dịch. Nó cung cấp các công cụ để làm việc với các tài khoản thanh toán, tạo các phiên thanh toán và theo dõi trạng thái thanh toán.
const { Payments } = defineOneEntry( "your-project-url", { "token": "your-app-token" });
🔗 Tài liệu liên quan
- Bảng điều khiển quản trị OneEntry - Payments - Tài liệu chính thức của bảng điều khiển quản trị
- Bảng điều khiển quản trị OneEntry - Tài khoản thanh toán - Cấu hình tài khoản thanh toán
- Bảng điều khiển quản trị OneEntry - Trạng thái thanh toán - Đồng bộ hóa trạng thái
- Bảng điều khiển quản trị OneEntry - Tích hợp Stripe - Kết nối Stripe
- Mô-đun Orders - Quản lý đơn hàng và thanh toán
- Mô-đun AuthProvider - Cần thiết cho xác thực phiên
- Mô-đun Products - Các sản phẩm có sẵn để mua
- Tài liệu Stripe - Tích hợp cổng thanh toán