Số dư và tính tiền

Tài liệu này mô tả cơ chế tính tiền thật của hệ thống, kể cả những chỗ cơ chế đó chưa hoàn chỉnh. Việc hoàn tiền ở tài liệu riêng: Chính sách hoàn tiền.

1. Số dư trong ví là gì

Số dư ví TexAPI là khoản trả trước cho dịch vụ. Số dư hiển thị bằng credit theo tỷ lệ cố định 100 credit = 1 USD giá trị sử dụng, còn đơn vị kế toán chuẩn là đô-la Mỹ. Số dư chuẩn được ghi đến một phần triệu đô (0,000001 USD), tương đương 0,0001 credit. Về bản chất kế toán, đây là một nghĩa vụ phải thực hiện của TexAPI với bạn — TexAPI chỉ ghi nhận doanh thu khi bạn thực sự sử dụng dịch vụ.

Nói chính xác điều nó KHÔNG phải:

• Không phải tiền điện tử, không phải ví điện tử theo nghĩa pháp luật về trung gian thanh toán, không phải tiền mã hoá, không phải phương tiện thanh toán. Số dư chỉ dùng được cho dịch vụ của TexAPI.
• Không chuyển được cho người khác, không mua bán được, không rút được thành tiền theo yêu cầu.

Credit là đơn vị sử dụng dịch vụ nội bộ của TexAPI, cố định 100 credit = 1 USD giá trị sử dụng. Credit chỉ là cách biểu thị lượng dịch vụ TexAPI trả trước cho khách hàng: không phải tiền điện tử, tiền mã hoá, phương tiện thanh toán, tiền có thể rút hay tài sản có thể chuyển nhượng. Kế toán chuẩn, số dư cơ sở dữ liệu, sổ cái, khoản thu và khoản hoàn vẫn tính và ghi bằng USD. Ví dụ, nạp 5 USD được 500 credit và nạp 10 USD được 1.000 credit, trước mọi khoản thưởng.

1.1 Số dư không có hạn sử dụng

Số dư của bạn không hết hạn. Đây là cam kết, và nó nhất quán với cách hệ thống được xây: không có cột hạn sử dụng nào trên ví hay trên sổ cái, và không có logic hết hạn nào.

Điều này áp dụng cho cả lượng sử dụng kèm gói thuê bao: về bản chất kinh tế, một gói là một lần nạp trước cộng một mức chiết khấu, và phần chưa dùng vẫn là của bạn.

1.2 Số dư khi bạn xoá tài khoản

Nếu tổ chức của bạn còn thành viên khác, việc bạn xoá tài khoản cá nhân không xoá tổ chức và không ảnh hưởng số dư.

2. Nạp tiền

Mỗi kênh có một bảng mệnh giá riêng. PayOS nhận 100.000 · 200.000 · 500.000 · 1.000.000 · 2.000.000 VND; Creem nhận 5 · 10 · 20 · 50 · 100 USD. Mức tối thiểu khác nhau vì kinh tế hai cổng khác nhau: Creem có phí cố định 0,40 USD mỗi giao dịch, còn PayOS không có phí phần trăm. Mức tối thiểu không phải rào cản tuỳ ý.

Về tỷ giá cố định 27.000: đây là hằng số cấu hình, không nối nguồn tỷ giá thời gian thực. Tỷ giá áp cho một đơn hàng được chốt tại thời điểm tạo đơn và ghi vào đơn — thay đổi cấu hình sau đó không định giá lại đơn đã tạo.

Về việc cộng phí thẻ: con số bạn phải thanh toán được hiển thị trước khi bạn xác nhận. Phần chênh là phí của cổng thanh toán, không phải phí của TexAPI, và không hoàn lại được khi hoàn tiền.

2.1 Sau khi bạn thanh toán

Cổng thanh toán gửi thông báo về TexAPI; TexAPI xác thực chữ ký của thông báo, khoá dòng đơn hàng, kiểm tra trạng thái, rồi ghi tiền vào ví — tất cả trong một giao dịch cơ sở dữ liệu. Cùng giao dịch đó áp thưởng nạp lần đầu và mã giảm giá nếu có. Có nút Xác nhận thanh toán nếu bạn không muốn chờ.

Chống ghi trùng. Đơn đã ở trạng thái hoàn thành không được ghi tiền lần hai; các khoản thưởng có thêm chỉ mục duy nhất ở cơ sở dữ liệu để không thể cấp hai lần. Nếu bạn thấy tiền được ghi hai lần cho một giao dịch, đó là lỗi — báo cho hỗ trợ, và đó là trường hợp hoàn tiền bắt buộc.

2.2 Khi thanh toán không thành công

3. Sổ cái

Mọi biến động số dư đều để lại một bút toán, ghi trong cùng giao dịch với biến động đó. Mỗi bút toán lưu: loại, số tiền (âm là tiền ra), số dư sau giao dịch, loại và mã tham chiếu, và dữ liệu bổ trợ. Bạn xem được sổ cái của mình tại Bảng điều khiển → Ví.

Điểm minh bạch cần nói: thưởng nạp lần đầu, thưởng mã giảm giá và tín dụng chào mừng đều được ghi loại adjustment, không phải loại riêng — phân biệt được qua trường tham chiếu. Cột “tổng đã nạp” chỉ tăng với topup và subscription_grant, nghĩa là tiền thưởng không được tính là tiền thật đã nhận. Đó là cách ghi đúng, và nó là cơ sở của quy tắc hoàn tiền.

Hạn chế cần biết: số dư trong ví là một khoản duy nhất, không phân biệt nguồn. Sau khi 1.000 credit đã trả tiền (10 USD chuẩn) và 100 credit thưởng (1 USD giá trị sử dụng) cùng vào ví, hệ thống không ghi lại phần nào được chi trước. Đây là lý do TexAPI dùng quy tắc “hoàn không quá số tiền bạn đã trả cho đơn hàng đó”.

Về tính bất biến: sổ cái được cơ sở dữ liệu bảo vệ để không thể sửa — một cơ chế ở tầng cơ sở dữ liệu chặn mọi lệnh cập nhật trên bảng sổ cái, nên sửa một bút toán sai phải bằng cách ghi thêm một bút toán bù. Lệnh xoá vẫn được phép, vì việc bạn tự xoá tài khoản phụ thuộc vào nó; trước khi xoá, các bút toán được sao sang bảng lưu trữ.

4. Tính tiền một lượt gọi

1. Kiểm tra khoá API, hạn mức thông lượng, trần chi tiêu của khoá, và số dư khả dụng.
2. Tạm giữ một khoản dự phòng: ước lượng chi phí tối đa tính ở giá niêm yết chưa giảm, và khoá khoản đó trong ví. Cơ chế này ngăn việc gọi song song tiêu vượt số dư.
3. Chọn tuyến và gọi lên hạ tầng; chuyển tuyến nếu lỗi.
4. Tính tiền theo lượng thực dùng, áp chiết khấu và sàn chống lỗ.
5. Tất toán: giải phóng khoản tạm giữ, ghi nợ số tiền thực, ghi bút toán, và lưu biên nhận định giá vào bản ghi lượt gọi.

Hệ quả của bước 2 mà bạn sẽ nhìn thấy: khi bạn đang được áp chiết khấu, khoản tạm giữ có thể lớn hơn đáng kể số tiền cuối cùng bị trừ, vì nó tính ở giá chưa giảm. Số dư khả dụng của bạn tạm thời giảm nhiều hơn mức thực chi, và điều đó cũng làm trần chi tiêu theo khoá bị siết chặt hơn thực tế. Khoản tạm giữ được giải phóng khi lượt gọi kết thúc.

Làm tròn trước bằng USD: đến micro-đô, luôn làm tròn LÊN. Chỉ sau khi chốt khoản tất toán này, hệ thống mới đổi sang credit theo tỷ lệ 100 credit/USD. Một micro-đô (0,000001 USD) bằng 0,0001 credit, nên mức làm tròn tối đa mỗi lượt gọi là 0,0001 credit — vẫn tương đương 0,000001 USD, hay khoảng 1 USD sau một triệu lượt gọi.

Biên nhận định giá của mỗi lượt gọi ghi: số token từng loại đã tính, đơn giá hiệu lực, đơn giá niêm yết, mức chiết khấu, tổng gộp, trần cho phép, mức bị giới hạn bởi số dư, và cơ sở tính lượng sử dụng. Biên nhận được ghi một lần tại thời điểm tính tiền và đọc lại nguyên bản, không dựng lại công thức khi xem — nên con số bạn thấy hôm nay là đúng con số đã áp hôm đó, kể cả khi giá đã thay đổi từ đó.

5. Khi nào bạn bị tính tiền và khi nào không

Đây là mục quan trọng nhất của tài liệu. TexAPI công bố cả các trường hợp bất lợi cho bạn.

5.1 KHÔNG bị tính tiền

5.2 CÓ bị tính tiền — kể cả khi bạn không nhận được câu trả lời hoàn chỉnh

Dòng bị ngắt giữa đường. Nếu mô hình đã sinh ra một phần câu trả lời và một phần đã tới bạn, phần đó bị tính tiền. Đúng trong cả ba trường hợp: hạ tầng hết thời gian chờ giữa dòng, kết nối đứt, và chính bạn ngắt kết nối.

Cách tính khi hạ tầng không báo số token — điển hình khi dòng bị cắt:

• Token đầu ra: lấy theo số token thực tế đã chuyển tới bạn.
• Token đầu vào: lấy theo ước lượng ở khoản tạm giữ — và chỉ khi có token đầu ra để tính tiền.
• Nếu không có gì tới bạn: tiền = 0.

Trần bảo vệ bạn: trong trường hợp dựng lại này, số tiền không vượt quá khoản đã tạm giữ khi bắt đầu lượt gọi. Biên nhận ghi rõ cơ sở đã dùng, nên bạn kiểm tra được.

Lý do TexAPI thu, nói thẳng: khi dòng bị cắt, hạ tầng vẫn tính tiền TexAPI cho toàn bộ công việc mô hình đã làm. Tính 0 đồng trong trường hợp này nghĩa là cho không đúng những lượt gọi dài — vốn là những lượt đắt nhất — và tạo động cơ lạm dụng bằng cách chủ động ngắt.

Nếu bạn cho rằng một khoản thu trong nhóm này không đúng: gửi mã lượt gọi tới hỗ trợ. TexAPI có biên nhận định giá đầy đủ để đối chiếu, và sẽ hoàn lại nếu biên nhận cho thấy sai.

5.3 Khoản tạm giữ bị bỏ rơi

Nếu tiến trình xử lý lượt gọi của bạn chết mà không tất toán, tác vụ dọn sẽ đóng khoản tạm giữ sau 15 phút và thu toàn bộ khoản đã tạm giữ — tức thu ở giá niêm yết chưa giảm cho công việc mà bạn có thể chưa nhận được.

Đây là hành vi bất lợi cho bạn và TexAPI công bố nó. Nếu số dư của bạn bằng 0, khoản tạm giữ được đóng mà không thu.

6. Số dư âm

Không thể xảy ra. Được bảo đảm ở ba tầng độc lập: ràng buộc ở cơ sở dữ liệu, kiểm tra trước khi ghi nợ, và giới hạn tại thời điểm tất toán.

Khi số dư hết giữa một lượt gọi: lượt gọi đó hoàn thành, và chỉ bị tính tối đa bằng số dư còn lại — phần chênh TexAPI tự chịu, và biên nhận ghi rõ nó đã bị giới hạn bởi số dư. Lượt gọi tiếp theo trả 402.

TexAPI không cho phép nợ, không tính lãi, không có hạn mức tín dụng.

7. Giá và thay đổi giá

Giá bán được suy ra từ giá vốn, không phải một con số nhập tay: giá bán = giá vốn ÷ (1 − biên mục tiêu). Vì giá bán là kết quả một phép chia, không có đường nào để một mô hình bị đặt giá dưới giá vốn do nhập sai.

Đồng bộ giá vốn chạy khoảng mỗi 30 phút và giá bán tự điều chỉnh theo. Hiện chưa có bước phê duyệt của người ở giữa — hạ tầng tăng giá thì giá của bạn tăng theo, tự động. Bốn bảo đảm đi kèm:

• Giá không áp hồi tố. Mỗi lượt gọi tính theo giá hiệu lực tại thời điểm gọi, và giá đó được ghi trong biên nhận.
• TexAPI thông báo trước 07 ngày khi giá một mô hình tăng quá 10%. Cơ chế tự động chưa có — hiện thực hiện bằng tay.
• Giá và chiết khấu của một kỳ thuê bao đã trả không thay đổi trong kỳ đó.
• Nếu bạn không đồng ý với giá mới: ngừng sử dụng và yêu cầu hoàn phần số dư chưa dùng.

7.1 Chiết khấu

Chiết khấu gói và mã giảm giá cộng với nhau. Khuyến mãi của TexAPI cạnh tranh chứ không cộng — mức áp cuối cùng là mức cao hơn giữa hai bên.

Sàn chống lỗ. Mọi chiết khấu bị chặn bởi một mức sàn tính theo giá vốn của đúng tuyến đã phục vụ lượt gọi đó, không phải giá vốn trung bình — cần thiết vì các tuyến của cùng một mô hình có thể chênh giá vốn rất nhiều. Hệ quả với bạn: một chiết khấu công bố có thể không được áp đủ nếu nó chạm sàn, và biên nhận định giá ghi rõ khi điều đó xảy ra.

8. Gói thuê bao

Hai thế hệ gói. Gói mua từ 24/10/2026 (và các kỳ gia hạn sau đó) là gói hạn mức: thay vì cộng credit vào ví, gói cho bạn một hạn mức sử dụng đo bằng giá PAYG niêm yết, tự nạp lại theo khung. Gói mua trước ngày đó giữ nguyên cơ chế credit đến hết kỳ đã trả.

Giá chưa gồm VAT — xem mục 10. Hạn mức thông lượng theo từng gói ở Điều khoản API mục 4. Mức giá VND là số tiền PayOS thu và là giá niêm yết riêng của gói, không phải quy đổi trực tiếp từ giá USD; ví vẫn ghi bằng USD. Khi mua gói bằng thẻ, nếu sản phẩm thẻ được cấu hình cộng phí xử lý, số tiền cuối cùng có thể cao hơn giá USD niêm yết và luôn được hiển thị trước khi bạn xác nhận.

8.0 Hạn mức 5 giờ và hạn mức tuần

Đơn vị đo là "USD theo giá PAYG niêm yết". Mỗi request được tính theo bảng giá PAYG đang hiệu lực, và đúng số đó cộng vào bộ đếm của hai cửa sổ. Model rẻ chạy xa hơn model đắt trên cùng một hạn mức; khi bảng giá thay đổi, hạn mức thực tế theo token thay đổi theo và chúng tôi thông báo trước (mục 7). Cửa sổ cố định, reset theo giờ Việt Nam (GMT+7): khung 5 giờ reset lúc 0h · 5h · 10h · 15h · 20h (khung cuối ngày 20h–24h dài 4 giờ); tuần reset 00:00 thứ Hai. Dashboard hiển thị đếm ngược chính xác.

Trong hạn mức: request không trừ ví, không giữ trước, không tính tiền — chỉ di chuyển bộ đếm. Vượt hạn mức — tràn sang ví PAYG (mặc định bật): phần dùng tiếp được tính vào ví theo giá PAYG niêm yết trừ chiết khấu của gói (3/5/8%). Tràn là tiền bạn đã nạp sẵn, không tạo nợ; có thể tắt tại Nạp & Gói. Khi tràn bị tắt (hoặc ví trống), request mới nhận lỗi 429 subscription_limit_exceeded kèm thời điểm reset. Hạn mức không chuyển sang kỳ sau và không quy đổi thành credit; RPM/TPM/khoá vẫn áp dụng song song.

8.1 Huỷ gói

Huỷ tại Bảng điều khiển → Ví → Thuê bao. Khi bạn huỷ, TexAPI dừng việc thu định kỳ ở cổng thanh toán — không cần bạn làm thêm bước nào ở phía cổng. Bạn vẫn giữ toàn bộ quyền lợi của kỳ đã trả đến hết ngày kết thúc kỳ: hạn mức thông lượng và chiết khấu không bị cắt ngay.

Nếu vì lý do kỹ thuật việc dừng ở cổng không thành công, giao diện nói rõ với bạn ngay lúc huỷ thay vì báo thành công. Trong trường hợp đó, nếu một kỳ vẫn bị thu, hệ thống nhận ra đó là khoản phải hoàn chứ không kích hoạt lại gói, và TexAPI hoàn lại toàn bộ kỳ đó.

Khi kỳ đã trả kết thúc: chiết khấu và hạn mức thông lượng của gói dừng, ví trở về hạn mức PAYG (60 RPM, 250.000 token/phút, 2 khoá API). Credit còn lại vẫn nằm trong ví và không hết hạn. Kênh PayOS không tự trừ tiền, nên muốn dùng tiếp bạn mua lại gói.

9. Mã giảm giá và tiền thưởng

Cơ chế “giữ mã” cần hiểu đúng: mã loại thưởng nạp không thể tính giá trị lúc bạn nhập, vì nó phụ thuộc số tiền bạn nạp. Vì vậy khi bạn nhập, mã được giữ lại và chỉ được áp dụng khi bạn thực sự nạp tiền. Hai hệ quả: giữ mã không phải đã đổi mã — số lần đổi của mã chưa bị trừ; và mỗi tổ chức chỉ giữ một mã cùng lúc, nhập mã thứ hai sẽ thay mã thứ nhất.

Nếu việc áp mã thất bại vào lúc nạp, tiền nạp của bạn vẫn được ghi — cơ chế được thiết kế để lỗi ở bước mã không làm mất tiền nạp.

Thưởng nạp lần đầu: 10% trên lần nạp tiền thật đầu tiên, một lần cho mỗi tổ chức, có chỉ mục duy nhất ở cơ sở dữ liệu bảo đảm không cấp hai lần. Vì vậy lần nạp đầu 10 USD cộng 1.000 credit đã trả tiền và 100 credit thưởng. Credit thưởng không hết hạn, nhưng không được hoàn — bạn chưa trả tiền cho phần này.

Giới hạn cộng dồn: tổng thưởng trên một đơn nạp — thưởng nạp lần đầu, mã thưởng nạp và thưởng đối tác — không vượt quá 20% số tiền nạp. Nếu các nguồn cộng lại cao hơn, hệ thống cấp tối đa 20% và ghi phần bị giới hạn trong lịch sử giao dịch.

Chống lạm dụng: giới hạn tổng số lần đổi mỗi mã, giới hạn theo tổ chức, mức nạp tối thiểu, giới hạn tần suất nhập mã, và yêu cầu email đã xác minh để nạp tiền. Việc tạo nhiều tài khoản để lấy thưởng nhiều lần là hành vi bị cấm.

10. Thuế và hoá đơn

Hai cam kết trong khi cơ chế chưa chạy, và cả hai đều bảo vệ bạn:

• Nếu phát sinh nghĩa vụ thuế mà hệ thống chưa thu, TexAPI tự chịu phần đó cho các giao dịch đã hoàn thành — không truy thu của khách hàng đã thanh toán.
• Bạn cần hoá đơn: gửi yêu cầu tới hỗ trợ. TexAPI xử lý thủ công. Đây không phải cách làm lâu dài và TexAPI không gọi nó là cách làm lâu dài.

11. Điều chỉnh thủ công của TexAPI

Nhân sự vận hành có thể điều chỉnh số dư của bạn — cấp thêm hoặc trừ. Mọi điều chỉnh:

• ghi một bút toán loại adjustment trong sổ cái bạn xem được;
• ghi vết kiểm tra không thể sửa, gồm người thực hiện và lý do bằng văn bản (bắt buộc);
• bị giới hạn theo trần số tiền của từng vai nhân sự;
• yêu cầu xác thực hai yếu tố khi vượt ngưỡng.

Điều chỉnh trừ tiền chỉ được thực hiện khi: sửa một lỗi ghi tiền của hệ thống, thu hồi tiền thưởng đã cấp do lạm dụng, hoặc xử lý một giao dịch bị đảo ngược ở cổng thanh toán. Mọi trường hợp đều phải có lý do ghi trong vết kiểm tra, và TexAPI thông báo cho bạn.

Điều chỉnh không phải hoàn tiền. Điều chỉnh thay đổi số dư ví; hoàn tiền trả tiền về phương thức thanh toán của bạn.

Nếu bạn thấy một điều chỉnh không giải thích được trong sổ cái: liên hệ hỗ trợ, TexAPI trả lời kèm lý do đã ghi trong 05 ngày làm việc.

12. Đối chiếu và khiếu nại

Sổ cái là bản ghi có thẩm quyền về số dư của bạn. Nếu bạn cho rằng số dư hoặc một khoản thu không đúng:

1. Kiểm tra sổ cái (Ví) và biên nhận định giá của lượt gọi liên quan (Lịch sử sử dụng).
2. Nếu vẫn thấy sai: gửi hỗ trợ kèm mã lượt gọi hoặc mã bút toán.
3. TexAPI trả lời trong 05 ngày làm việc, kèm số liệu đối chiếu.
4. Nếu TexAPI sai: điều chỉnh hoặc hoàn tiền, và không tính bất kỳ phí xử lý nào.