Billing & Subscription

Tài liệu cho phần thanh toán thật của Data Explorer: gói Pro, flow checkout, trạng thái subscription, MoMo/ZaloPay, webhook xác nhận, và các lưu ý deploy cho môi trường thật.

Gói Free và Pro

Billing hiện không còn là mock. Người dùng có thể giữ trạng thái Free hoặc mua Pro theo kỳ hạn rõ ràng, với thời gian hiệu lực được phản ánh lại lên hồ sơ.

Checkout thật qua provider

MoMo và ZaloPay không chỉ là nút UI. Mỗi lần checkout tạo payment flow thật, trả về provider session, rồi chờ webhook xác nhận trước khi cấp Pro.

Kích hoạt sau webhook

App không nên bật Pro chỉ vì người dùng vừa bấm thanh toán. Quyền truy cập được nâng cấp sau khi backend nhận và xác thực tín hiệu hoàn tất từ provider.

Người dùng sẽ thấy gì trong UI?

Trong profile dialog, người dùng thấy gói hiện tại, trạng thái subscription, ngày hết hạn nếu đang active, và các lựa chọn checkout theo kỳ. Bản copy hiện tại hiển thị VND là giá thực tế, còn USD chỉ là tham chiếu để người đọc quốc tế dễ hiểu hơn.

Current plan card

Card này cho người dùng biết họ đang Free hay Pro, còn active hay chưa, và mốc thời gian nào là lần kiểm tra quan trọng tiếp theo.

Refresh billing state

Nút refresh cho phép người dùng kéo lại trạng thái billing sau khi vừa thanh toán hoặc vừa quay từ provider về, thay vì phải đăng xuất/đăng nhập lại.

Checkout lifecycle từ lúc bấm mua đến lúc có Pro

1. Chọn gói và provider

Người dùng chọn kỳ hạn Pro và một provider như MoMo hoặc ZaloPay. App tạo checkout request với plan code và provider rõ ràng.

2. Backend tạo payment session

Backend dùng provider adapter tương ứng để tạo request chuẩn theo từng cổng thanh toán, rồi trả thông tin redirect/session về client.

3. Provider xử lý thanh toán

Người dùng đi qua flow của MoMo hoặc ZaloPay. Đây là nơi xác thực ví, quét mã, hoặc xác nhận giao dịch thật sự diễn ra.

4. Webhook xác nhận và app nâng quyền

Chỉ sau khi backend nhận webhook hợp lệ hoặc kiểm tra trạng thái thành công thì tài khoản mới được chuyển sang Pro active. Đây là khác biệt quan trọng giữa billing thật và billing demo.

Billing return page và trạng thái sau thanh toán

Client có một billing return page để đón người dùng sau khi provider trả họ về app. Trang này không nên tự ý tuyên bố “đã thành công” nếu webhook hoặc lần kiểm tra trạng thái cuối chưa xác nhận xong.

Vì sao bước này quan trọng?

Trong billing thật, người dùng có thể quay lại app trước khi hệ thống hậu trường xử lý xong. Return page là lớp UX để nối lại trải nghiệm, nhưng nguồn chân lý cuối cùng vẫn phải là backend và trạng thái giao dịch đã xác thực.

Biến môi trường cần cho billing thật

Billing provider envs

# MoMo

MOMO_PARTNER_CODE=...

MOMO_ACCESS_KEY=...

MOMO_SECRET_KEY=...

MOMO_CREATE_URL=https://test-payment.momo.vn/v2/gateway/api/create

# ZaloPay

ZALOPAY_APP_ID=...

ZALOPAY_KEY1=...

ZALOPAY_KEY2=...

ZALOPAY_CREATE_URL=https://sb-openapi.zalopay.vn/v2/create

# Public return / webhook context

FRONTEND_URL=http://localhost:5173

API_PUBLIC_URL=http://localhost:3001/api

Nếu bạn test billing ở môi trường public, đừng chỉ kiểm tra “nút bấm có mở được provider không”. Hãy test đủ cả vòng: tạo checkout, redirect về app, webhook xác nhận, refresh trạng thái user, và hiển thị ngày hết hạn sau khi Pro active.

Billing trong Data Explorer không phải một module tách rời khỏi auth. Quyền truy cập Pro cuối cùng vẫn đi về user profile, nên auth, billing, webhook, và profile refresh luôn là một chuỗi liên thông.

Trước đóXác thực & onboarding Tiếp theo Kiến trúc hệ thống

Sẵn sàng khám phá dữ liệu?

Tham gia cộng đồng trên GitHub để đóng góp cho IDE cơ sở dữ liệu địa phương thông minh nhất.

Mở Ứng dụng