Thanh toán trả sau
Với thanh toán trả sau, bạn đặt hàng Energy, Bandwidth, kích hoạt và kiểm tra AML mà không cần nạp tiền đặt cọc trước. Các dịch vụ được định giá theo biểu phí áp dụng riêng cho từng khách hàng, bao gồm cả các mức chiết khấu hiện hành. Các khoản phí, thanh toán và điều chỉnh được phản ánh trong hóa đơn của bạn theo các điều khoản thanh toán và lập hóa đơn trong hợp đồng của bạn.
Trả sau được Netts kích hoạt theo yêu cầu dành cho các tài khoản doanh nghiệp. Các endpoint trong phần này chỉ phản hồi cho các tài khoản có tính năng thanh toán trả sau; các tài khoản khác sẽ nhận mã 403 postpaid_required.
Cách thức hoạt động
- Bạn đặt hàng như bình thường. Cùng các endpoint đặt hàng, cùng một API key. Tài khoản trả sau không cần số dư tiền gửi cho các đơn hàng này. Giá áp dụng là giá theo hợp đồng của bạn, bao gồm cả các chiết khấu của bạn.
- Các dịch vụ đã cung cấp được ghi nhận là các khoản phí. Một đơn hàng được chấp nhận chưa phải là một dịch vụ đã được cung cấp. Một khoản phí sẽ xuất hiện trong mức sử dụng sau khi dịch vụ hoặc một phần có thể tính phí riêng biệt của đơn hàng đã được cung cấp — điều này có thể diễn ra muộn hơn so với phản hồi của đơn hàng.
- Giá và tỷ giá được cố định và lưu giữ. Một báo giá hợp lệ sẽ cố định mức giá theo hợp đồng của bạn cho đơn hàng đó. Nếu không có báo giá, mức giá theo hợp đồng của bạn tại thời điểm đặt hàng sẽ được áp dụng, và số tiền theo loại tiền tệ trong hợp đồng của bạn được tính theo tỷ giá tại thời điểm dịch vụ được cung cấp. Các số tiền đã ghi nhận sẽ không được tính toán lại khi bạn xem mức sử dụng, nhận hóa đơn hoặc thực hiện thanh toán.
- Bạn nhận và thanh toán hóa đơn của mình. Chu kỳ thanh toán và các điều khoản thanh toán là những điều khoản đã được thỏa thuận trong hợp đồng của bạn. Hóa đơn hiển thị các dịch vụ trong kỳ, các khoản thanh toán và điều chỉnh đã áp dụng, cùng với số tiền còn phải trả; việc thanh toán không xóa đi các bản ghi dịch vụ. Xem hóa đơn và thanh toán. Tiền tệ thanh toán, mạng lưới và điều khoản thanh toán được hiển thị trong
settlementtại tài khoản. Khoản thanh toán thừa sẽ được giữ lại trên tài khoản của bạn dưới dạng hạn mức tín dụng và được sử dụng cho các khoản phí tiếp theo.
Biểu phí, báo giá và tỷ giá hối đoái được ghi nhận
Báo giá (freezePrice) sẽ cố định mức giá theo hợp đồng của bạn trong một phút. Hãy đặt hàng với quoteId và các tham số tương tự trong vòng một phút đó, và đơn hàng sẽ được tính theo mức giá đã báo, ngay cả khi giá thay đổi hoặc dịch vụ được cung cấp sau đó. Báo giá là tùy chọn; xem Energy 1 giờ và Energy 5 phút để biết các trường yêu cầu.
Nếu không có báo giá, số tiền theo loại tiền tệ trong hợp đồng của bạn sẽ được tính theo tỷ giá tại thời điểm dịch vụ được cung cấp, chứ không phải thời điểm bạn xem giá hoặc xem tài khoản của mình. Tỷ giá hiện tại — tỷ giá của bạn và tỷ giá hiển thị trong phản hồi tài khoản — chỉ nhằm mục đích so sánh; đó không phải là cam kết về tỷ giá cho đơn hàng trong tương lai.
Các lượt kiểm tra AML được định giá bằng đô la Mỹ và được ghi nhận bằng loại tiền tệ trong hợp đồng của bạn; giá trị tương đương bằng TRX được tính theo tỷ giá khi quá trình kiểm tra hoàn tất. Không tính toán lại khoản phí AML từ số tiền TRX đã được làm tròn.
Số tiền được hiển thị bằng TRX và bằng loại tiền tệ trong hợp đồng của bạn; các hạn mức của bạn được tính theo loại tiền tệ trong hợp đồng của bạn. usdPerTrx là tỷ giá giữa TRX và loại tiền tệ trong hợp đồng của bạn. Bạn thanh toán bằng loại tiền tệ và mạng lưới trong hợp đồng của bạn, được hiển thị trong settlement.
Một đơn hàng có thể có nhiều hơn một khoản phí, ví dụ như Energy và phí kích hoạt được tính riêng. Mỗi khoản phí có thời gian và tỷ giá riêng. Số tiền được làm tròn một lần đến sáu chữ số thập phân, theo quy tắc làm tròn đến số chẵn gần nhất (half-even); báo giá vẫn giữ nguyên các số tiền đã báo. Hãy đối soát đơn hàng theo các khoản phí của đơn hàng đó, chứ không phải bằng cách áp dụng tỷ giá hiện tại vào tổng số tiền của đơn.
Mọi mốc thời gian đều theo chuẩn UTC. Mọi số tiền đều là chuỗi thập phân, ví dụ "30000.000000" — hãy phân tích cú pháp chúng dưới dạng kiểu số thập phân (decimal), không dùng kiểu số thực (float).
Hạn mức tín dụng
Netts thiết lập hạn mức tín dụng cho tài khoản của bạn: số tiền tối đa bạn có thể nợ tại bất kỳ thời điểm nào. Hạn mức này được hiển thị trong tài khoản và hạn mức với "origin": "netts". Bạn có thể xem nhưng không thể thay đổi hoặc tắt nó — hãy liên hệ với người quản lý Netts của bạn nếu bạn cần một hạn mức khác.
Các sản phẩm và API key dùng chung hạn mức tín dụng cấp tài khoản duy nhất này. Mỗi đơn hàng mới đều được kiểm tra đối chiếu với từng hạn mức áp dụng. Khi quá trình kiểm tra đó phát hiện hạn mức khả dụng không đủ, đơn hàng sẽ bị từ chối trước khi thực hiện:
{
"detail": {
"code": 1004,
"msg": "Postpaid credit limit reached.",
"paymentMode": "postpaid",
"reason": "limit_reached",
"product": "*",
"period": "outstanding",
"limitId": 1
}
}Endpoint đặt hàng phản hồi mã 402. Việc thanh toán sẽ giải phóng lại hạn mức. Nếu quá trình kiểm tra tạm thời không khả dụng, endpoint đặt hàng sẽ phản hồi mã 503 với mã lỗi 5036 — hãy thử lại sau, lần thử bị từ chối sẽ không bị tính phí. Số tiền khả dụng hiển thị qua yêu cầu đọc dữ liệu là con số tại thời điểm hiện tại, không phải là phần giữ trước cho đơn hàng sau; các đơn hàng khác được chấp nhận có thể làm thay đổi con số này.
Các hạn mức của riêng bạn
Bên trong hạn mức của Netts, bạn có thể thiết lập các hạn mức riêng thấp hơn của mình — nhằm kiểm soát chi tiêu hoặc giới hạn các sản phẩm riêng lẻ:
- Hạn mức tổng thể của riêng bạn — tổng số tiền bạn cho phép bản thân được nợ, thấp hơn hạn mức của Netts.
- Hạn mức sản phẩm — mức chi tiêu mà một sản phẩm có thể sử dụng, ví dụ
energy_5m.
Các hạn mức của bạn không bao giờ làm tăng thêm tín dụng. Các hạn mức sản phẩm không cộng dồn: với hạn mức Netts là 50 USD, các hạn mức sản phẩm 50 USD cho energy_1h và 50 USD cho energy_5m vẫn cùng chia sẻ hạn mức tín dụng cấp tài khoản là 50 USD. Quá trình kiểm tra đơn hàng áp dụng mọi hạn mức liên quan, và mục hạn mức sẽ hiển thị số tiền hiện có thể chi tiêu cho từng sản phẩm.
Một hạn mức có thể tính theo:
period | Nội dung được tính |
|---|---|
outstanding | các khoản phí chưa thanh toán, cộng với các đơn hàng đã được chấp nhận nhưng chưa được ghi nhận |
day | các khoản phí trong ngày UTC hiện tại, bao gồm cả những khoản đã thanh toán, cộng với các đơn hàng đã được chấp nhận nhưng chưa được ghi nhận |
week | các khoản phí trong tuần UTC hiện tại tính từ Thứ Hai 00:00 UTC, bao gồm cả những khoản đã thanh toán, cộng với các đơn hàng đã được chấp nhận nhưng chưa được ghi nhận |
order | số tiền của một đơn hàng mới đơn lẻ |
Một khoản thanh toán sẽ làm giảm nợ của bạn nhưng không đặt lại mức sử dụng trong ngày hoặc trong tuần. Hạn mức tín dụng từ việc thanh toán thừa được hiển thị dưới dạng creditApplied và được trừ một lần vào tổng nợ của bạn; khoản này không cộng thêm vào từng hạn mức sản phẩm.
Các hạn mức của bạn được tính bằng loại tiền tệ của hạn mức Netts và không thể cao hơn hạn mức đó. Nếu Netts giảm hạn mức của mình xuống thấp hơn một trong các hạn mức của bạn, ràng buộc áp dụng thấp hơn sẽ vẫn có hiệu lực.
Sản phẩm: energy_1h, energy_5m, bandwidth, activation, aml_check.
Quyền hạn của API key
Mỗi API key cần có quyền cho phần này. Người quản lý Netts của bạn sẽ cấp quyền theo từng key:
| Quyền | Cho phép |
|---|---|
billing.read | tài khoản, tỷ giá, hạn mức, mức sử dụng, hóa đơn và các khoản thanh toán |
limits.write | tạo, thay đổi, tắt và bật các hạn mức của riêng bạn |
Nếu không có quyền, endpoint sẽ phản hồi mã 403 với billing_read_required hoặc forbidden. Danh sách trắng IP của key áp dụng tương tự như mọi endpoint khác. Các endpoint này vẫn khả dụng khi số dư tiền gửi bằng không.
Các endpoint
| Endpoint | Chức năng |
|---|---|
GET /apiv2/billing/account | hạn mức tín dụng, nợ và số tiền khả dụng hiện tại |
GET /apiv2/billing/rate | tỷ giá hiện tại của TRX so với loại tiền tệ trong hợp đồng của bạn |
GET /apiv2/billing/limits | tất cả các hạn mức cùng số tiền đã dùng và khả dụng, khả dụng theo từng sản phẩm |
POST /apiv2/billing/limits | tạo, thay đổi, tắt và bật các hạn mức của riêng bạn |
GET /apiv2/billing/usage | các thành phần tính phí, được liên kết với đơn hàng tương ứng |
GET /apiv2/billing/invoices | danh sách hóa đơn, chi tiết một hóa đơn cùng các khoản phí |
GET /apiv2/billing/payments | các khoản thanh toán và hạn mức tín dụng |
Định dạng phản hồi
{ "success": true, "data": { }, "timestamp": "2026-10-19T20:12:30+00:00" }Lỗi từ dịch vụ:
{
"success": false,
"error": { "code": "postpaid_required", "message": "this account has no postpaid billing" },
"timestamp": "2026-10-19T20:12:30+00:00"
}Key bị thiếu hoặc không hợp lệ, hoặc yêu cầu đến từ IP nằm ngoài danh sách trắng của key, sẽ bị từ chối bởi API gateway trước khi chuyển tiếp tới dịch vụ, với mã 401:
{ "detail": { "code": -1, "msg": "Invalid or missing API key" } }Mã -2 với "Invalid API key or IP not in whitelist" có nghĩa là IP không nằm trong danh sách trắng của key. Yêu cầu vượt quá 10 lượt mỗi giây hoặc 300 lượt mỗi phút từ một IP sẽ bị từ chối với mã 429 và {"message": "API rate limit exceeded"}.
| HTTP | code | Ý nghĩa |
|---|---|---|
| 400 | invalid_request, invalid_amount, idempotency_key_required, invalid_idempotency_key | tham số bị thiếu hoặc sai định dạng |
| 403 | postpaid_required | tài khoản không có tính năng thanh toán trả sau |
| 403 | postpaid_disabled | tính năng thanh toán trả sau bị tạm dừng: bạn có thể đọc, nhưng không thể thay đổi hạn mức |
| 403 | billing_read_required, forbidden | key thiếu quyền billing.read hoặc limits.write |
| 403 | netts_limit_readonly | hạn mức do Netts thiết lập và không thể thay đổi |
| 404 | not_found | không tìm thấy hạn mức hoặc hóa đơn như vậy trên tài khoản của bạn |
| 409 | revision_conflict | hạn mức đã bị thay đổi trong lúc thực hiện — hãy đọc lại dữ liệu |
| 409 | limit_exists | bạn đã có hạn mức cho sản phẩm và chu kỳ này |
| 409 | idempotency_conflict | Idempotency-Key đã được sử dụng với một yêu cầu khác |
| 409 | no_account_limit | tài khoản chưa được Netts thiết lập hạn mức tín dụng |
| 422 | above_account_limit | giá trị cao hơn hạn mức của Netts |
| 422 | product_not_postpaid | sản phẩm không khả dụng cho hình thức trả sau |
| 422 | unit_mismatch | đơn vị tiền tệ của hạn mức Netts đã thay đổi — hãy đặt giá trị mới trước khi bật hạn mức của bạn |
| 503 | unavailable | tạm thời không khả dụng — hãy thử lại sau |
| 503 | rate_unavailable | tỷ giá của bạn tạm thời không khả dụng — hãy thử lại sau |