Thanh toán & hoàn tiền

Thanh toán thời gian thực tính theo từng sản phẩm, từng định danh. Một lệnh gọi tạm giữ tiền trước, rồi quyết toán khi mọi sản phẩm được chọn đều có kết quả.

Tạm giữ, rồi quyết toán

Khi một lệnh gọi được chấp nhận, nền tảng tạm giữ tổng đơn giá mỗi lần kiểm tra của các sản phẩm được chọn. Chưa có gì bị tính phí. Khi kết quả trả về, mỗi mục tự quyết toán:

mục charged giữ nguyên khoản tạm giữ
mục refunded hoàn nó về số dư của bạn

Ba tổng số trong phản hồi mô tả quá trình quyết toán đó:

Trường	Ý nghĩa
`total_reserved`	Tạm giữ khi lệnh gọi được chấp nhận
`total_charged`	Thực tế giữ lại
`total_refunded`	Hoàn về số dư của bạn

Chúng luôn cân bằng: total_reserved = total_charged + total_refunded.

Cái gì bị thu, cái gì được hoàn

Kết quả	`billing_status`	Ý nghĩa
`valid` — định danh đã đăng ký	`charged`	Đã có câu trả lời thực sự
`invalid` — định danh chưa đăng ký	`charged`	Đã có câu trả lời thực sự
`unknown` — nhà cung cấp không trả về kết quả kết luận	`refunded`	Không có câu trả lời; kết quả không kết luận không bao giờ bị tính phí
Nhà cung cấp timeout	`refunded`	`error_code: provider_timeout`
Kênh hoặc slot người dùng không khả dụng	`refunded`	`error_code: channel_busy` / `user_busy`
Bảo vệ đồng thời trên một dữ kiện dùng chung	`refunded`	`error_code: fact_refresh_busy`
Nhà cung cấp làm hỏng lần kiểm tra	`refunded`	`error_code: realtime_failed`
Cache kết quả không khả dụng	`refunded`	`error_code: fact_cache_unavailable`

Một lượt trúng cache vẫn bị tính phí. Mục cached: true là câu trả lời thực sự được tạo bởi một lần kiểm tra trước đó và đã được lưu; khoản thu phản ánh câu trả lời, không phải vòng gọi. Chỉ kết quả unknown và thất bại mới được hoàn tiền.

Đọc một lệnh gọi thành công một phần

Vì mỗi mục quyết toán riêng, một lệnh gọi có thể chứa cả hai loại kết quả. Trường hợp đó được báo là status: partial_succeeded — HTTP vẫn là 200. Đừng bao giờ coi 200 là “mọi thứ đều chạy tốt”:

đọc status
với mỗi mục, đọc billing_status và error_code

Các giá trị status: succeeded (mọi mục đều bị tính phí), partial_succeeded (hỗn hợp), failed (không mục nào có câu trả lời có thể tính phí).

Số dư

Các lệnh gọi cần đủ số dư cho toàn bộ khoản tạm giữ. Nếu thiếu, lệnh gọi thất bại với 402 insufficient_balance trước khi bất kỳ sản phẩm nào được liên hệ — không gì bị tạm giữ, không gì bị tính phí.

Bản thân số dư có thể lấy từ GET /v1/balance. Xem Số dư tài khoản.

Hoàn tiền là tự động

Không có bước yêu cầu hoàn tiền. Mục được hoàn tiền sẽ được quyết toán trả lại số dư của bạn ngay trong cùng lệnh gọi, và phản hồi bạn nhận được đã phản ánh các con số cuối cùng.