API Reference
Tài liệu tham chiếu chi tiết các endpoint Public API của VietBilling: cấu trúc request, response, error codes và ví dụ code cho Customer, Checkout, Sub.
Base URL và xác thực
Base URL production là https://api.vietbilling.com/public/v2. Tất cả endpoint dưới đây dùng Authorization: Bearer <organization-api-key> và JSON. API key xác định Organization nên URL không chứa Organization ID.
Lưu ý: Hiện tại API được phục vụ tại subdomain
https://api.vietbilling.com/public/v2. Trong lộ trình chuyển đổi unified routing tương lai, endpoint sẽ được hỗ trợ tạihttps://vietbilling.com/api/public/v2.
| Method | Endpoint | Mục đích |
|---|---|---|
POST | /customers | Tạo Customer |
POST | /checkouts | Tạo Checkout và có thể tự tạo Customer |
GET | /checkouts/{checkoutId} | Đọc Checkout |
GET | /subscriptions/{subscriptionId} | Đọc Subscription |
PATCH | /subscriptions/{subscriptionId} | Đổi Product hoặc lên lịch/hủy lịch cancel |
GET | /benefit-grants | Liệt kê BenefitGrants đang hoạt động của Customer |
Ví dụ request
curl -X GET \
"https://api.vietbilling.com/public/v2/subscriptions/sub_123" \
-H "Authorization: Bearer $VIETBILLING_API_KEY" \
-H "Accept: application/json"
Quy ước lỗi
Kiểm tra HTTP status trước khi đọc dữ liệu. Lỗi validation cần được sửa tại request; lỗi xác thực cần dừng ngay; lỗi mạng và 5xx có thể retry với backoff và giới hạn số lần.