Gói dịch vụ & thanh toán
Chọn gói & tạo hoá đơn
Chủ cửa hàng chọn gói trả phí và chu kỳ, hệ thống tạo hoá đơn chuyển khoản
Chỉ có trên Hubport SaaS
Trên bản cài đặt riêng (máy chủ riêng), endpoint trả HTTP 404 error_saas_mode_inactive.
Endpoint
POST /v1/platformsubscriptions/checkout
Chỉ chủ cửa hàng được gọi (trường is_owner của Gói của tôi). Endpoint tạo một hoá đơn chờ thanh toán (status = open) cho gói đã chọn; gói chỉ được kích hoạt khi Hubport ghi nhận đủ số tiền chuyển khoản của hoá đơn.
Request Body
| Tên | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
plan_code | string | Có | Mã gói trả phí (trường code trong Danh sách gói). Không phân biệt hoa thường |
cycle | string | Không | Chu kỳ thanh toán: month hoặc year. Mặc định: month |
nonce | string | Không | Chuỗi ngẫu nhiên khác nhau cho mỗi lần gọi. Nên gửi để request không bị chặn bởi cơ chế chống gửi trùng (HTTP 409 error_idempotent_check_duplicate_found) khi chọn lại cùng gói |
{
"plan_code": "PRO",
"cycle": "year",
"nonce": "1760317200123"
}Response Schema
HTTP 201 - Created (tạo hoá đơn mới) / HTTP 200 (dùng lại hoá đơn đang chờ)
| Trường | Kiểu | Mô tả |
|---|---|---|
invoice | object | Invoice Object cần thanh toán |
bank_info | object | Thông tin tài khoản nhận chuyển khoản của Hubport: bank_name, bank_code (tên ngắn ngân hàng dùng cho VietQR, vd MBBank), account_no, account_name, branch |
existing | bool | true nếu đã có hoá đơn chờ thanh toán cho đúng gói và chu kỳ này (trả lại hoá đơn cũ, HTTP 200); false nếu vừa tạo hoá đơn mới (HTTP 201) |
Workflow & Logic
- Kiểm người gọi là chủ cửa hàng.
- Kiểm gói: phải đang mở bán công khai và là gói trả phí (không phải gói dùng thử / miễn phí), có giá cho chu kỳ đã chọn. Giá năm =
price_year(hoặcprice_month * 12nếu gói không đặt giá năm). - Nếu đã có hoá đơn chờ thanh toán cho đúng gói và chu kỳ → trả lại hoá đơn đó (
existing = true). - Ngược lại tạo hoá đơn mới loại
new, đồng thời huỷ (void) các hoá đơn mua gói đang chờ khác của cửa hàng. - Chủ cửa hàng quét ảnh
invoice.payment_qr_urlbằng app ngân hàng, hoặc chuyển khoản số tiềnamount_duetớibank_infovới nội dung ghi đúngtransfer_codecủa hoá đơn. - Hubport tự đối soát chuyển khoản trong vài giây đến vài phút: đủ tiền thì hoá đơn chuyển
paidvà gói được kích hoạt; chuyển thiếu thì hoá đơn vẫnopenvớiamount_duelà phần còn thiếu. Theo dõi bằng Chi tiết hoá đơn (gọi lại định kỳ, vd 5 giây một lần) hoặc Gói của tôi.
Error Codes
| HTTP | Mã lỗi | Mô tả |
|---|---|---|
| 403 | error_company_owner_required | Người gọi không phải chủ cửa hàng |
| 403 | error_company_required | Phiên đăng nhập không gắn với công ty nào |
| 404 | error_saas_mode_inactive | Không phải Hubport SaaS |
| 409 | error_idempotent_check_duplicate_found | Gửi trùng nội dung request trong thời gian ngắn (dùng nonce khác nhau) |
| 422 | error_plan_not_found | Gói không tồn tại, không mở bán hoặc không phải gói trả phí |
| 422 | error_cycle_invalid | cycle không phải month hoặc year |
| 422 | error_plan_price_not_set | Gói chưa có giá cho chu kỳ đã chọn |
| 422 | error_company_hard_deleted | Cửa hàng đã bị xoá vĩnh viễn |
| 422 | error_invoice_create_failed | Không tạo được hoá đơn |
Ví dụ
curl -X POST "https://api.hubport.vn/v1/platformsubscriptions/checkout" \
-H "Authorization: <JWT>" \
-H "Content-Type: application/json" \
-d '{"plan_code":"PRO","cycle":"month","nonce":"1760317200123"}'{
"invoice": {
"id": 1201,
"company_id": 12,
"subscription_id": 0,
"kind": "new",
"plan_id": 3,
"plan_code": "PRO",
"cycle": "month",
"number": "HP-202610-0012",
"transfer_code": "HPK7M2Q9XA",
"amount": 499000,
"amount_paid": 0,
"amount_refunded": 0,
"amount_due": 499000,
"payment_qr_url": "https://qr.sepay.vn/img?acc=0000000000&bank=MBBank&amount=499000&des=HPK7M2Q9XA",
"status": "open",
"overdue": false,
"lines": [
{
"type": "subscription",
"description": "Gói Pro (month)",
"plan_id": 3,
"plan_code": "PRO",
"cycle": "month",
"cycles": 1,
"quantity": 1,
"unit_price": 499000,
"amount": 499000,
"period_start": 0,
"period_end": 0
}
],
"period_start": 0,
"period_end": 0,
"due_at": 1760922000,
"paid_at": 0,
"date_created": 1760317200,
"date_modified": 1760317200
},
"bank_info": {
"bank_name": "Ngân hàng ABC",
"bank_code": "MBBank",
"account_no": "0000000000",
"account_name": "TEN CHU TAI KHOAN",
"branch": "Chi nhánh XYZ"
},
"existing": false
}