Chuyển đến nội dung chính

Giới thiệu

Tạo các phiên thanh toán và theo dõi giao dịch thông qua các cổng thanh toán được cấu hình trong dự án của bạn.

Thông tin thêm về thanh toán trong bảng điều khiển quản trị OneEntry: https://doc.oneentry.cloud/docs/category/payments

🎯 Mô-đun này làm gì?​

Mô-đun Payments cho phép bạn tạo các phiên thanh toán và theo dõi giao dịch cho cửa hàng 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ị (Payments > Accounts) — Stripe hoặc tùy chỉnh — và mô-đun này tạo một phiên thanh toán cho một đơn hàng, trả về liên kết thanh toán của cổng và cho phép bạn đọc lịch sử và trạng thái phiên.

SDK lấy các tài khoản thanh toán và tạo các phiên thanh toán; các tài khoản và trạng thái được cấu hình trong bảng điều khiển quản trị.

🚀 Khởi động nhanh​

Khởi tạo mô-đun từ defineOneEntry:


const { Payments } = defineOneEntry(
  "your-project-url", {
    "token": "your-app-token"
  }
);

Tạo một phiên thanh toán cho một đơn hàng và chuyển hướng khách hàng đến cổng (cần xác thực):

// Create a Stripe Checkout session for order #179.
const session = await Payments.createSession(179, "session");

console.log(session.id, session.status, session.paymentUrl);

// Send the customer to the gateway checkout page.
window.location.href = session.paymentUrl;

✨ Khái niệm chính​

Phiên thanh toán là gì?​

Một Phiên thanh toán (ISessionEntity) là một bản ghi chứa:

  • type — 'session' hoặc 'intent'
  • status — chuỗi trạng thái thanh toán tự do (ví dụ: "waiting", "completed")
  • paymentAccountId — tài khoản đã cấu hình được sử dụng
  • orderId — đơn hàng liên quan
  • paymentUrl — liên kết thanh toán của cổng (hoặc null)
  • createdDate / updatedDate — dấu thời gian

Các loại phiên​

LoạiMô tả
sessionTạo một trang Stripe Checkout với liên kết thanh toán chuyển hướng
intentTạo một ý định thanh toán cho xử lý thanh toán trực tiếp/tùy chỉnh

Các loại tài khoản​

LoạiKhi nào sử dụngCấu hình cần thiết
StripeKết nối hệ thống thanh toán StripeTài khoản Stripe, URL
CustomHệ thống thanh toán thay thế hoặc thanh toán bằng tiền mặtCấu hình tùy chỉnh

Trạng thái thanh toán​

Trạng thái status của một phiên là một chuỗi tự do được thiết lập từ kết quả của cổng, không phải là một enum cố định. Các giá trị phổ biến:

Trạng tháiÝ nghĩa
waitingPhiên đã được tạo, đang chờ thanh toán
completedThanh toán đã được xác nhận bởi cổ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ị. Tuy nhiên, bạn có thể ** ánh xạ** trạng thái thanh toán với trạng thái lưu trữ đơn hàng để trạng thái đơn hàng tự động cập nhật khi trạng thái thanh toán thay đổi.

Vòng đời thanh toán​

1. Configure a payment account in the admin panel (Stripe or custom)
   ↓
2. Customer places an order (Orders module)
   ↓
3. Create a payment session  →  Payments.createSession(orderId, type)
   ↓
4. Redirect the customer to session.paymentUrl
   ↓
5. Customer completes payment at the gateway
   ↓
6. Session status reflects the gateway result (e.g. "waiting" → "completed")
   ↓
7. Mapped order status is updated automatically

📋 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 — hãy tạo và chỉnh sửa chúng trong bảng điều khiển quản trị OneEntry (Payments > Accounts), cung cấp Tên, Loại (Stripe hoặc Tùy chỉnh), và Token. Đối với tài khoản Stripe, bạn cũng cấu hình Success URL, Cancel URL, và Thời gian sống của phiên. SDK chỉ dùng để lấy tài khoản và tạo phiên.

Đồng bộ hóa trạng thái​

Trạng thái thanh toán được ánh xạ với trạng thái lưu trữ đơn hàng trong bảng điều khiển quản trị (Payments > Statuses → chọn lưu trữ đơn hàng → ánh xạ trạng thái → lưu). Điều này cho phép tự động cập nhật trạng thái đơ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ô​

Không bao giờ lưu trữ số thẻ tín dụng, CVV, hoặc ngày hết hạn đầy đủ. Thanh toán được xử lý bởi cổng (Stripe), điều này giúp bạn không phải lưu trữ dữ liệu thẻ; OneEntry không bao giờ lưu trữ chi tiết thẻ thô.

Hoàn tiền nằm trong mô-đun Đơn hàng​

Mô-đun Payments không có phương thức hoàn tiền. Hoàn tiền được xử lý bởi mô-đun Đơn hàng thông qua createRefundRequest(), cancelRefundRequest(), và getRefunds().

📊 Bảng tham khảo nhanh​

Phương thứcMô tảTrường hợp sử dụng
getAccounts() 🔐Lấy tất cả tài khoản thanh toánLiệt kê các tài khoản thanh toán đã cấu hình
getAccountById() 🔐Lấy tài khoản thanh toán theo IDLấy chi tiết tài khoản cụ thể
createSession() 🔐Tạo phiên thanh toánTạ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 (phân trang)Xem lịch sử phiên thanh toán
getSessionById() 🔐Lấy phiên thanh toán theo IDKiểm tra trạng thái phiên cụ thể
getSessionByOrderId() 🔐Lấy phiên thanh toán theo ID đơn hàngTìm thanh toán cho đơn hàng cụ thể

🔐 = Cầ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 Success URL, Cancel URL, và Session lifetime. Sử dụng createSession() với loại "session" để tạo một liên kết 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 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 tài khoản thanh toán không?​

Có. Tạo nhiều tài khoản thanh toán (Stripe hoặc tùy chỉnh) 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 khác nhau thông qua paymentAccountIdentifier của nó.

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ạ trạng thái thanh toán với trạng thái đơn hàng. Điều này cho phép đồng bộ hóa tự động.

Làm thế nào để tôi phát hành hoàn tiền?​

Hoàn tiền không phải là một phần của mô-đun Payments. Sử dụng mô-đun Đơn hàng: createRefundRequest() để yêu cầu hoàn tiền, cancelRefundRequest() để hủy yêu cầu, và getRefunds() để liệt kê chúng.

🎓 Thực hành tốt nhất​

  • Xác thực trước — mỗi phương thức Payments yêu cầu một người dùng đã được ủy quyền (xem AuthProvider).
  • Chuyển hướng đến paymentUrl sau khi tạo một phiên, và xử lý các URL trả về của cổng trong ứng dụng của bạn.
  • Đọc trạng thái từ phiên, không phải từ khách hàng — kiểm tra status của phiên (hoặc getSessionByOrderId()) để xác nhận thanh toán.
  • Ánh xạ trạng thái thanh toán với trạng thái đơn hàng để trạng thái đơn hàng tự động đồng bộ.
  • Kiểm tra với các khóa thử nghiệm của Stripe trước khi đưa vào sản xuất.

🔗 Tài liệu liên quan​