Cách thiết lập tự động nạp tiền vào bảng điều khiển SMM qua API

Cần chuẩn bị gì trước khi thiết lập tự động nạp tiền

Tự động nạp tiền liên kết số dư của bảng điều khiển SMM với dịch vụ thanh toán hoặc hệ thống thanh toán nội bộ. Dịch vụ kiểm tra số dư còn lại, tạo thanh toán khi đạt ngưỡng đã đặt và chỉ ghi có tiền sau khi xác nhận thanh toán. Để hoạt động cần có tài liệu API của bảng điều khiển, quyền truy cập API thanh toán, khóa riêng cho môi trường thử nghiệm và môi trường vận hành, cùng nhật ký của tất cả giao dịch.

Trước khi phát triển, hãy kiểm tra xem API của bảng điều khiển có khả năng trả về số dư, nhận yêu cầu ghi có, hiển thị lịch sử nạp tiền và nhận mã định danh giao dịch bên ngoài hay không. Nếu bảng điều khiển không hỗ trợ ghi có qua API, tự động hóa chỉ có thể tạo yêu cầu hoặc gửi thông báo cho người vận hành. Nhược điểm của phương án này là tiền vẫn phải nạp thủ công.

Tách biệt việc kiểm tra số dư và quyết định thanh toán

Nên chạy việc kiểm tra số dư còn lại bằng một tác vụ riêng theo lịch. Tác vụ này lấy số dư, so sánh với ngưỡng và chuyển kết quả cho trình xử lý nạp tiền. Không tạo thanh toán ngay tại thời điểm phản hồi API mà không kiểm tra các giao dịch đang dang dở hiện tại: các tác vụ song song có thể thấy cùng một số dư thấp và tạo ra nhiều lệnh thanh toán.

Trước khi thanh toán mới, trình xử lý phải kiểm tra xem có giao dịch nào ở trạng thái «đã tạo», «chờ thanh toán» hoặc «đang xác nhận» hay không. Nếu có bản ghi như vậy, lần thử mới không được khởi chạy cho đến khi hoàn tất đối soát. Nhược điểm của xử lý tuần tự là khi API bên ngoài phản hồi chậm, việc nạp tiền có thể bắt đầu muộn hơn so với nhiều yêu cầu song song.

Chọn ngưỡng và logic số tiền nạp

Ngưỡng số dư được chọn với mức dự phòng cho các đơn hàng đang hoạt động, hàng đợi tại nhà cung cấp và độ trễ thanh toán. Với kênh có hoạt động không đồng đều, chỉ dựa vào mức chi tiêu trung bình là rủi ro: sau buổi stream, khi chạy quảng cáo hoặc đơn hàng hàng loạt, các khoản trừ có thể tăng mạnh. Riêng mức tới hạn được đặt để gửi thông báo, nhưng không nhất thiết tạo thanh toán tự động.

Số tiền nạp có thể cố định hoặc tính theo chi tiêu trong khoảng thời gian đã chọn. Số tiền cố định dễ kiểm soát và đối soát hơn. Nhược điểm là trong giai đoạn yên ắng, số dư có thể giữ tiền thừa, còn khi đơn hàng tăng đột biến thì một lần nạp có thể không đủ. Số tiền tính toán linh hoạt hơn, nhưng cần loại bỏ các khoản trừ bất thường và hoàn tiền khỏi thống kê.

Thiết lập giới hạn tài chính riêng biệt với ngưỡng

Ngưỡng chỉ trả lời câu hỏi khi nào hệ thống được phép bắt đầu quá trình nạp tiền. Giới hạn trả lời câu hỏi khác: hệ thống được phép trừ bao nhiêu tiền. Hãy đặt số tiền tối đa cho một giao dịch, tổng giới hạn cho một kỳ và số dư cho phép sau khi ghi có. Các quy tắc này được kiểm tra trước khi tạo thanh toán, không phải sau khi đã thanh toán.

Tự động nạp tiền không được trừ tiền mà không có giới hạn cho giao dịch và kỳ hạn. Nếu số tiền tính toán cao hơn mức cho phép, nên chuyển giao dịch sang kiểm tra thủ công và gửi thông báo. Nhược điểm của giới hạn cứng là khi chi phí tăng nhanh, số dư có thể cạn trước khi nhân viên phụ trách xác nhận tăng giới hạn.

Tạo khóa riêng và bảo vệ quyền truy cập

Đối với script tự động nạp tiền, hãy dùng khóa API riêng với quyền tối thiểu: đọc số dư, tạo thanh toán, kiểm tra trạng thái và ghi có giao dịch đã xác nhận. Khóa này không cần quyền truy cập người dùng, cài đặt dịch vụ, đơn hàng và rút tiền. Nếu dịch vụ hỗ trợ giới hạn theo địa chỉ IP, chỉ cho phép yêu cầu từ máy chủ tích hợp.

Khóa được lưu trong biến môi trường hoặc kho lưu trữ bí mật được bảo vệ. Không truyền chúng vào mã trình duyệt, nhật ký, kho lưu trữ công khai và thông báo lỗi. Mỗi khóa phải có người sở hữu và quy trình thay thế rõ ràng. Nhược điểm của việc xoay khóa thường xuyên là việc nạp tiền sẽ dừng nếu không cập nhật bí mật mới trong tất cả quy trình vận hành.

Tạo thanh toán với mã định danh duy nhất

Mỗi lần nạp tiền được gán một mã định danh nội bộ trước khi gọi API thanh toán. Mã này được lưu trong nhật ký và truyền làm khóa bất biến hoặc số giao dịch bên ngoài. Khi xảy ra timeout mạng, có thể lặp lại cùng yêu cầu với cùng mã định danh: dịch vụ thanh toán phải trả về giao dịch đã tạo thay vì trừ tiền lần nữa.

Dưới đây là ví dụ yêu cầu chung. Hãy thay tên trường và địa chỉ bằng giá trị từ tài liệu của nhà cung cấp cụ thể. Biến PAYMENT_ID lưu ID duy nhất được tạo trước, còn CALLBACK_URL trỏ đến trình xử lý webhook.

curl -X POST "$PAYMENT_API_URL/payments" \
-H "Authorization: Bearer $PAYMENT_API_KEY" \
-H "Idempotency-Key: $PAYMENT_ID" \
-H "Content-Type: application/json" \
-d '{"amount":"$TOPUP_AMOUNT","currency":"$CURRENCY","external_id":"$PAYMENT_ID","callback_url":"$CALLBACK_URL"}'

Không xác định tính duy nhất của thanh toán chỉ dựa vào số tiền và thời gian tạo. Hai lần nạp tiền giống nhau có thể là hợp lệ, còn yêu cầu lặp lại sau sự cố thì không. Nhược điểm của ID bên ngoài trong cơ sở dữ liệu riêng là phải lưu trữ đáng tin cậy và không tái sử dụng sau khi hủy giao dịch.

Kiểm tra số dư và lưu trạng thái giao dịch

Yêu cầu số dư phải được thực hiện trước khi quyết định nạp tiền mới và sau khi ghi có thành công. Yêu cầu chung có thể như sau: curl -X GET "$PANEL_API_URL/balance" -H "Authorization: Bearer $PANEL_API_KEY". Trong phản hồi, hãy lưu không chỉ số tiền mà cả thời gian kiểm tra để không đưa ra quyết định dựa trên dữ liệu cũ.

Với mỗi giao dịch, hãy ghi lại bản ghi với ID nội bộ, ID thanh toán tại nhà cung cấp, số tiền, tiền tệ, thời gian tạo, trạng thái, phản hồi API và lý do lỗi. Chuỗi trạng thái phù hợp: «đã tạo», «chờ thanh toán», «đã thanh toán», «đang ghi có», «đã ghi có», «đã hủy», «cần kiểm tra».

Chỉ được ghi có vào bảng điều khiển đối với thanh toán đã xác nhận và chưa được xử lý. Không ghi đè trạng thái mà không có lịch sử: khi có tranh chấp phải thấy được yêu cầu nào đã gửi và vì sao giao dịch bị thay đổi. Nhược điểm của nhật ký chi tiết là nó có thể chứa dữ liệu nhạy cảm, vì vậy quyền truy cập vào nó bị hạn chế.

Nhận webhook và đối soát trạng thái thanh toán

Trang thanh toán thành công và chuyển hướng người dùng không xác nhận việc tiền đã vào. Xác nhận là webhook từ dịch vụ thanh toán hoặc kiểm tra lại trạng thái qua API của nó. Khi nhận webhook, hãy kiểm tra chữ ký, thời gian gửi, ID thanh toán, ID bên ngoài, số tiền và tiền tệ. Chỉ sau đó mới chuyển giao dịch sang trạng thái đã xác nhận thanh toán.

Sau khi kiểm tra webhook, nên yêu cầu trạng thái thanh toán hiện tại từ nhà cung cấp. Ví dụ: curl -X GET "$PAYMENT_API_URL/payments/$PROVIDER_PAYMENT_ID" -H "Authorization: Bearer $PAYMENT_API_KEY". Hãy đối soát trạng thái với dữ liệu nhật ký, sau đó gửi yêu cầu ghi có vào bảng điều khiển SMM với cùng ID nội bộ.

Webhook lặp lại không được tạo lần ghi có thứ hai. Trình xử lý tìm giao dịch theo ID bên ngoài, thấy trạng thái «đã ghi có» và trả về phản hồi thành công mà không có hành động mới. Nhược điểm của webhook là chúng có thể bị trễ hoặc không đến nếu trình xử lý không khả dụng.

Xử lý timeout, thử lại và thanh toán bị treo

Khi timeout sau khi tạo thanh toán, không gửi yêu cầu mới với ID khác. Trước tiên hãy tìm giao dịch theo mã định danh nội bộ hoặc lặp lại yêu cầu với cùng khóa bất biến. Nếu nhà cung cấp đã nhận yêu cầu ban đầu, họ sẽ trả về thanh toán hiện có. Điều này bảo vệ khỏi việc trừ tiền hai lần khi kết nối bị ngắt.

Nếu webhook không đến trong thời gian đã đặt, tác vụ nền sẽ yêu cầu trạng thái thanh toán qua API. Các lần kiểm tra lặp lại được thực hiện với khoảng nghỉ tăng dần và số lần thử có giới hạn để không làm quá tải API và nhật ký. Giao dịch tồn tại quá lâu ở trạng thái chờ được chuyển sang kiểm tra thủ công, chứ không bị coi là đã hủy mà không đối soát.

Khi có phản hồi về lỗi mạng tạm thời hoặc API không khả dụng, việc thử lại là chấp nhận được. Khi bị từ chối thanh toán, sai số tiền, chữ ký webhook không hợp lệ hoặc vượt giới hạn, không nên tự động lặp lại yêu cầu. Nhược điểm của việc thử lại là làm phức tạp logic trạng thái và có thể tạo tải thừa khi nhà cung cấp gặp sự cố hàng loạt.

Ghi có thanh toán đã xác nhận vào bảng điều khiển SMM

Trước khi ghi có, trình xử lý kiểm tra lại: số tiền không vượt giới hạn, tiền tệ khớp, giao dịch chưa bị hủy và trạng thái chưa phải «đã ghi có». Yêu cầu truyền số tiền và mã định danh thanh toán bên ngoài. Nếu API của bảng điều khiển hỗ trợ khóa bất biến, hãy dùng cùng ID giao dịch nội bộ.

Dạng yêu cầu chung: curl -X POST "$PANEL_API_URL/balance/topups" -H "Authorization: Bearer $PANEL_API_KEY" -H "Content-Type: application/json" -H "Idempotency-Key: $PAYMENT_ID" -d '{"amount":"$TOPUP_AMOUNT","currency":"$CURRENCY","external_id":"$PAYMENT_ID"}'

Sau phản hồi của bảng điều khiển, hãy yêu cầu lại số dư và lưu kết quả vào nhật ký. Nếu tiền đã bị trừ tại dịch vụ thanh toán nhưng API của bảng điều khiển trả về lỗi, không tạo thanh toán mới. Giao dịch vẫn ở trạng thái «cần kiểm tra» cho đến khi thử ghi có lại hoặc đối soát thủ công. Nhược điểm của sơ đồ thận trọng này là số dư có thể tạm thời không được nạp tự động.

Thêm thông báo, công tắc và kiểm tra khởi chạy

Thông báo cần thiết cho các bất thường: số dư giảm xuống dưới mức tới hạn, thanh toán bị từ chối, không nhận được webhook, vượt giới hạn, API không khả dụng hoặc giao dịch cần kiểm tra thủ công. Trong tin nhắn chỉ cần nêu ID nội bộ, trạng thái và lý do. Không đưa vào đó khóa API, chữ ký webhook và thông tin thanh toán.

Hãy để một công tắc riêng cho tự động nạp tiền mà không xóa tích hợp. Nó cần thiết khi thay đổi nhà cung cấp, bảo trì kỹ thuật, nghi ngờ có lỗi hoặc chi phí thay đổi đột ngột. Nhược điểm của công tắc là rõ ràng: nếu không bật lại sau khi bảo trì, số dư có thể cạn trong lúc đơn hàng đang hoạt động.

Danh sách kiểm tra trước khi bật tự động nạp tiền

• Việc kiểm tra số dư không tạo thanh toán khi còn giao dịch chưa hoàn tất.
• Mỗi thanh toán được tạo ID nội bộ duy nhất và khóa bất biến.
• Đã thiết lập giới hạn cho một giao dịch và kỳ hạn đã chọn.
• Webhook được kiểm tra theo chữ ký, số tiền, tiền tệ và mã định danh.
• Khi không có webhook, việc đối soát lại trạng thái qua API được khởi chạy.
• Timeout không dẫn đến việc tạo thanh toán thứ hai trước khi kiểm tra thanh toán đầu tiên.
• Việc ghi có vào bảng điều khiển được thực hiện một lần và ghi vào nhật ký.
• Chế độ thử nghiệm đã được kiểm tra với trường hợp thành công, từ chối, webhook trùng lặp và API không khả dụng.