Billing & credits — Gommo platform (preview)

Coming to Gommo platform

Portal credits and /billing/* on this site preview unified topup UX for Gommo. Official billing will ship on Gommo — not as a permanent self-host requirement.

→ Gommo platform roadmap

End-user credit topup via Gommo (create_payment + bank transfer) — separate from /gateway generation APIs.

The default path proxies Gommo subscriptions APIs. Credits are fulfilled by Gommo upstream after bank transfer; the gateway polls payment_sync from the client.

Portal UI: /app/credits/ — balance KPIs, credit package grid, checkout modal, and top-up history. Links to Activity Billing and billing docs.

Overview

User app ──► POST /billing/payment/create (Bearer user)
                └── Gommo payment QR + order code (SP…)
                        └── poll payment_sync ──► paid: true → Gommo credits user

Legacy PayOS + sendBalances (POST /billing/topup/create) remains for merchant-controlled fulfillment when PAYOS_* is configured.

Prerequisites

Requirement	Env / note
Gommo domain	GOMMO_API_DOMAIN (see .env.example)
User session	Bearer from /ai/login — same as generation APIs
Device fields	device_id, device_name, device_info (portal sends automatically)
Legacy PayOS (optional)	PAYOS_* + GOMMO_ACCESS_TOKEN for /billing/topup/create

Check config:

GET /billing/status

Returns billingMode: "gommo", gommoPayment: true, and optional payosConfigured.

Packages

GET /billing/packages

Returns credit packages (id, amountVnd, credits, gommoIdBase). Defined in server creditPackages.ts.

Create payment (Gommo)

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

{
  "username": "gommo_username_from_/ai/me",
  "packageId": "basic-member",
  "invoiceBuyer": {
    "type": "consumer",
    "name": "Bán cho người tiêu dùng",
    "email": ""
  },
  "promoCode": "OPTIONAL",
  "referralCode": "OPTIONAL"
}

Response includes payment QR image URL, bank transfer fields (holder, acc, bank, content), VAT breakdown, and orderCode.

The gateway stores the order locally (TOPUP_ORDERS_FILE) for history.

Poll payment status

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

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

Poll every ~3.5s until data.paid === true. Gommo credits the user automatically.

Order history

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

Returns local orders for Gommo and legacy PayOS flows. Statuses: pending, paid, credited, failed.

vs /gateway

Path	Purpose
/gateway/*	Consume credits (models, jobs, chat, …)
/billing/*	Add credits (Gommo top-up or legacy PayOS)

Do not mount billing logic under /gateway.

Full reference

→ Billing API reference
→ Recipe: Gommo credit top-up

Next

→ FAQ · Authentication