Plugin StripePayment

🌐 English · Tiếng Việt

Nhận thanh toán qua Stripe cho cửa hàng GP247/Shop: thẻ quốc tế, Apple Pay, Google Pay, Link và các phương thức địa phương bạn bật trên tài khoản Stripe. Khách thanh toán trên trang bảo mật của Stripe rồi quay về cửa hàng — thông tin thẻ không bao giờ đi qua website của bạn.

Tổng quan

Tính năng

• 💳 Stripe Checkout — trang thanh toán do Stripe lưu trữ, tự có 3-D Secure và ví điện tử.
• 🧾 Ghi tiền đúng vào đơn — số tiền Stripe thực thu được ghi vào sổ thanh toán của đơn, đúng một lần, kể cả khi khách đóng trình duyệt trước khi về trang cảm ơn (nhờ webhook).
• ↩️ Đồng bộ hoàn tiền — hoàn tiền một phần hoặc toàn phần trên Stripe Dashboard được ghi vào đơn.
• 🧪 Test & Live — một công tắc chuyển giữa khoá thử nghiệm và khoá thật.
• 🏬 Theo từng cửa hàng — mỗi cửa hàng có thể dùng tài khoản Stripe riêng, hoặc dùng chung tài khoản của site/sàn.
• 🔒 An toàn — webhook được xác minh chữ ký; secret key và webhook secret được mã hoá trong CSDL; chỉ chủ site/chủ sàn cấu hình được.
• 💱 Đúng đơn vị tiền tệ — VND, JPY và các loại tiền "không số lẻ" được gửi đúng quy tắc của Stripe.

Cài đặt

1. Chép thư mục StripePayment vào app/GP247/Plugins/ trên website (hoặc tải file ZIP lên ở Admin → Extensions / Plugins → Import).
2. Vào Admin → Extensions / Plugins, tìm Stripe và bấm Install.

Plugin được bật sau khi cài, nhưng chỉ nhận tiền được sau khi bạn nhập khoá Stripe (mục dưới).

Cấu hình

Mở Admin → Plugins → Stripe (hoặc bấm vào plugin trong danh sách). Màn cấu hình chia 4 khối để khoá thử nghiệm và khoá thật không bao giờ nằm lẫn nhau:

Khoá bí mật được mã hoá khi lưu và không bao giờ hiện lại trên màn hình — dưới mỗi ô chỉ có nhãn Đã lưu hoặc Chưa đặt. Để trống ô bí mật khi bấm Lưu nghĩa là giữ nguyên giá trị cũ; muốn đổi thì dán giá trị mới.

Tạo khoá Stripe

Bạn cần 2 thứ cho mỗi môi trường: một API key (để tạo phiên thanh toán) và một webhook signing secret (để xác minh thông báo Stripe gửi về). Sandbox và Live là hai bộ riêng — khoá của môi trường này không dùng được ở môi trường kia.

Nên làm trọn Sandbox trước, thử thanh toán thành công, rồi mới làm Live. Để dùng Live, tài khoản Stripe phải được kích hoạt (khai thông tin doanh nghiệp và tài khoản ngân hàng nhận tiền).

Bước 1 — Chọn đúng môi trường trên Stripe

1. Đăng nhập dashboard.stripe.com.
2. Ở bộ chọn tài khoản (góc trên bên trái), chọn Sandboxes rồi mở một sandbox (tạo mới nếu chưa có) — hoặc giữ tài khoản chính để làm Live.
3. Mọi bước dưới đây làm trong môi trường vừa chọn. Làm xong Sandbox thì quay lại bước này để làm Live.

Bước 2 — Tạo API key

Cách khuyên dùng: restricted key (chỉ cấp đúng quyền plugin cần — nếu lộ, kẻ gian cũng không làm được gì khác).

1. Mở trang API keys (dashboard.stripe.com/apikeys).
2. Bấm Create restricted key.
3. Key name: đặt tên dễ nhận, ví dụ GP247 StripePayment – ten-mien-cua-ban.
4. Để mọi quyền là None, trừ Checkout Sessions → chọn Write. Plugin chỉ tạo và đọc phiên thanh toán, không cần quyền nào khác.
5. Bấm Create key, nhập mã xác minh Stripe gửi qua email/SMS.
6. Copy khoá ngay (bấm vào giá trị khoá). Ở chế độ Live, khoá tự tạo chỉ hiện một lần — lỡ đóng mà chưa copy thì phải tạo khoá khác.
7. Dán vào ô Secret key của đúng khối: khoá rk_test_… → khối Sandbox; khoá rk_live_… → khối Live.

Cách nhanh: secret key chuẩn (sk_…, toàn quyền trên tài khoản — kém an toàn hơn): ở trang API keys, mục Standard keys, bấm Reveal ở dòng Secret key rồi copy. Trong sandbox luôn xem lại được; ở Live chỉ xem lại được khoá do Stripe tạo sẵn.

Bước 3 — Tạo webhook và lấy signing secret

Không có webhook, tiền chỉ được ghi khi khách quay về trang cảm ơn, và hoàn tiền trên Stripe không về đơn.

1. Trên màn cấu hình Stripe của GP247, copy URL webhook ở dòng mô tả của khối Chế độ, dạng https://ten-mien-cua-ban/plugin/stripe-payment/webhook.
2. Trên Stripe, mở Workbench → Webhooks (dashboard.stripe.com/webhooks) → Create an event destination.
3. Chọn nguồn sự kiện Your account; phiên bản API để mặc định.
4. Chọn đúng 6 sự kiện: checkout.session.completed, checkout.session.async_payment_succeeded, checkout.session.async_payment_failed, refund.created, refund.updated, refund.failed.
5. Chọn loại đích Webhook endpoint, dán URL ở bước 1 vào Endpoint URL, rồi tạo.
6. Trên trang của endpoint vừa tạo, bấm Reveal ở mục Signing secret và copy giá trị whsec_….
7. Dán vào ô Webhook signing secret của cùng khối với API key ở Bước 2 (Sandbox hoặc Live), rồi bấm Lưu.

Webhook cần địa chỉ HTTPS công khai. Khi thử trên máy cá nhân (chưa có HTTPS), dùng Stripe CLI: stripe listen --forward-to http://localhost/plugin/stripe-payment/webhook — lệnh in ra một secret whsec_…, dán secret đó vào khối Sandbox.

Tự kiểm tra trước khi lưu

• Khối Sandbox chỉ chứa khoá có chữ _test_; khối Live chỉ chứa khoá có chữ _live_.
• API key và webhook secret trong cùng khối phải lấy từ cùng môi trường Stripe.
• Công tắc Chế độ thử nghiệm khớp với khối bạn muốn dùng (nhãn Đang dùng hiện ở khối đó sau khi Lưu).

Giữ khoá an toàn

• Không gửi khoá qua email, chat hay ảnh chụp màn hình. Chỉ dán thẳng vào màn cấu hình.
• Nghi ngờ khoá bị lộ: trên Stripe, trang API keys → nút ⋯ của khoá → Rotate key, rồi dán khoá mới vào GP247. Webhook secret cũng có thể Roll secret tương tự trên trang endpoint.

Nhiều cửa hàng / sàn

• Multi-store: chọn cửa hàng ở đầu màn cấu hình rồi nhập khoá Stripe riêng. Mỗi tên miền khai báo một endpoint webhook riêng và mỗi endpoint có signing secret riêng — nhập secret đó ở đúng cửa hàng, kể cả khi các cửa hàng dùng chung một tài khoản Stripe.
• Sàn (marketplace): nhập khoá ở mức chung; cửa hàng con để trống sẽ dùng tài khoản của sàn.
• Bật/tắt Stripe cho từng cửa hàng ở màn Quản lý Plugin.
• Quản trị viên cửa hàng con và vendor không mở được màn cấu hình này.

Thử thanh toán

Bật Chế độ thử nghiệm, đặt hàng và chọn Stripe, dùng thẻ thử 4242 4242 4242 4242, ngày hết hạn bất kỳ trong tương lai, CVC bất kỳ. Xem thêm thẻ thử tại tài liệu Stripe (Testing).

Lưu ý

• Tiền tệ: tiền tệ của đơn phải được tài khoản Stripe hỗ trợ và đạt mức tối thiểu của Stripe (ví dụ 0.50 USD, 50 JPY). Nếu Stripe từ chối, đơn được huỷ, hàng trả về kho và khách được mời chọn cách thanh toán khác.
• Stripe hiển thị một dòng "Đơn hàng #…" bằng đúng tổng đơn (danh sách sản phẩm nằm trong phần mô tả), để số tiền luôn khớp với đơn kể cả khi có giảm giá, thuế, phí vận chuyển.
• Hoàn tiền làm trên Stripe Dashboard. Nếu Stripe báo hoàn tiền thất bại, đơn được ghi chú để bạn xử lý tay.
• Gỡ plugin chỉ xoá cấu hình của plugin; các khoản thu/hoàn đã ghi vào đơn vẫn giữ nguyên.

Lịch sử phiên bản

• 1.0.0 — Phát hành đầu tiên: Stripe Checkout, webhook có chữ ký, đồng bộ hoàn tiền, cấu hình theo cửa hàng, mã hoá khoá bí mật.