Billing & credits — nền tảng Gommo (preview)

Sắp có trên nền tảng Gommo

Portal credits và /vi/billing/* trên site xem trước UX nạp thống nhất cho Gommo. Billing chính thức sẽ ship trên Gommo — không phải yêu cầu self-host vĩnh viễn.

→ Roadmap nền tảng Gommo

Nạp credit end-user qua Gommo (create_payment + chuyển khoản) — tách khỏi API generation /gateway.

Luồng mặc định proxy Gommo subscriptions. Credit được cộng bởi Gommo upstream sau chuyển khoản; client poll payment_sync.

Portal UI: /vi/app/credits/ — KPI số dư, gói nạp, modal checkout, lịch sử nạp. Link sang Activity Billing và tài liệu billing.

Tổng quan

User app ──► POST /billing/payment/create (Bearer user)
                └── chuyển khoản Gommo + mã đơn (SP…)
                        └── poll payment_sync ──► paid: true → Gommo cộng credit

PayOS legacy + sendBalances (POST /billing/topup/create) vẫn giữ khi cấu hình PAYOS_*.

Điều kiện

Yêu cầu	Env / ghi chú
Domain Gommo	GOMMO_API_DOMAIN (xem .env.example)
Session user	Bearer từ /vi/ai/login
Device fields	device_id, device_name, device_info (portal tự gửi)
PayOS legacy (tùy chọn)	PAYOS_* + GOMMO_ACCESS_TOKEN cho /vi/billing/topup/create

GET /billing/status

Trả billingMode: "gommo", gommoPayment: true.

Gói nạp

GET /billing/packages

Tạo thanh toán (Gommo)

POST /billing/payment/create
Authorization: Bearer {user_access_token}
Content-Type: application/json

{
  "username": "gommo_username_từ_/ai/me",
  "packageId": "basic-member",
  "invoiceBuyer": {
    "type": "consumer",
    "name": "Bán cho người tiêu dùng",
    "email": ""
  },
  "promoCode": "TÙY_CHỌN",
  "referralCode": "TÙY_CHỌN"
}

Response gồm QR chuyển khoản, thông tin ngân hàng, VAT và orderCode. Gateway lưu đơn local (TOPUP_ORDERS_FILE).

Poll trạng thái

POST /billing/payment/sync
Authorization: Bearer {user_access_token}
Content-Type: application/json

{ "orderCode": "SP..." }

Poll ~3.5s cho đến data.paid === true.

Lịch sử nạp

GET /billing/topup/orders?username={}&limit=20
Authorization: Bearer {user_access_token}

So với /gateway

Path	Mục đích
/gateway/*	Tiêu credit
/vi/billing/*	Cộng credit (Gommo hoặc PayOS legacy)

Reference đầy đủ

→ Billing API reference
→ Cookbook: nạp credit Gommo

Tiếp theo

→ FAQ · Authentication