Operation number thống nhất
Mã này liên kết player, amount, currency, payment method, payment provider và toàn bộ lịch sử xử lý.
Documentation / Payment Flow
Payment API hoạt động như thế nào
Xem toàn bộ payment flow: từ tạo deposit và xác nhận thanh toán đến credit tiền, withdrawal, refund và đối soát tài chính.
Deposit
tạo và credit
Payout
kiểm tra và gửi
Status
xác nhận giao dịch
Đối soát
kiểm soát tài chính
Payment flow
Từ request đến kết quả cuối
01
Tạo giao dịch
Ghi nhận player, amount, currency, payment method và operation number duy nhất.
02
Xác nhận thanh toán
Chuyển player đến payment page, yêu cầu bank confirmation hoặc xử lý payment trực tiếp.
03
Nhận status cuối
Kiểm tra response của payment provider và xác nhận kết quả cuối của giao dịch.
04
Cập nhật balance và accounting
Credit hoặc debit tiền đúng một lần, tính fee và ghi giao dịch để đối soát.
Tổng quan
Mỗi payment đi qua các giai đoạn có kiểm soát
Platform gán operation number riêng, liên kết nó với response của payment provider và chỉ thay đổi trạng thái tài chính sau khi kết quả được xác nhận. Request lặp lại không được tạo debit hoặc credit lần thứ hai.
Status rõ ràng
Giao dịch chỉ đi qua các giai đoạn được phép và không thay đổi kết quả đã hoàn tất nếu không có adjustment riêng.
Accounting tài chính riêng
Payment status, balance change, fee và accounting entry liên kết với nhau nhưng được kiểm tra riêng.
Deposit flow
Deposit flow điển hình
Deposit bắt đầu bằng một internal operation và kết thúc bằng credit một lần sau khi payment provider xác nhận.
01
Xác minh request và tạo giao dịch
Platform kiểm tra player, KYC, limit, currency, amount và payment method, sau đó gán internal operation number.
02
Gửi payment đến provider
Provider nhận amount, currency, player data, return URL, notification URL và thông tin thanh toán cần thiết.
03
Xác nhận thanh toán
Player xác nhận payment trên trang bên ngoài, qua 3-D Secure hoặc trong ứng dụng ngân hàng.
04
Nhận xác nhận và credit tiền
Sau khi xác minh signature và status cuối, platform tăng balance của player đúng một lần và hoàn tất giao dịch.
Withdrawal và refund
Withdrawal, cancellation và refund
Giao dịch đi ra yêu cầu xác minh player, balance khả dụng, risk, payment detail và response cuối của payment provider.
Xác minh player
KYC, tuổi, account status, limit, self-exclusion và withdrawal method được phép.
Kiểm tra risk
AML, dấu hiệu fraud, wagering condition, source of funds và operator approval.
Reserve amount
Amount được giữ trên balance cho đến khi nhận kết quả payout cuối.
Gửi đến payment provider
Tạo payout request riêng với số duy nhất và thông tin người nhận đã xác minh.
Chờ kết quả
Platform chấp nhận status trung gian và không debit amount lần nữa.
Refund
Refund được tạo thành giao dịch riêng, liên kết với payment gốc và amount riêng.
Hủy
Cancellation chỉ có thể thực hiện trước giai đoạn không thể đảo ngược và không thay thế refund cho giao dịch đã hoàn tất.
Đối soát cuối
Provider report, payout data, fee và balance change phải cho cùng một kết quả.
Operation status
Status model được khuyến nghị
Internal status chuẩn hóa các response khác nhau của payment provider thành một model rõ ràng cho platform.
Đã tạo
Giao dịch đã được tạo trong platform nhưng chưa được gửi đến hoặc chưa được provider chấp nhận.
Cần hành động
Player cần xác nhận payment, nhập thông tin hoặc thực hiện hành động với ngân hàng.
Đang xử lý
Provider đã nhận giao dịch nhưng kết quả cuối chưa được xác nhận.
Hoàn tất
Giao dịch đã hoàn tất thành công, sau đó balance được thay đổi đúng một lần.
Bị từ chối
Giao dịch kết thúc với trạng thái từ chối, lý do được lưu và không có thêm debit hoặc credit.
Chưa xác nhận
Kết quả giao dịch chưa xác định do lỗi kết nối, response delay hoặc dữ liệu mâu thuẫn.
Không thể coi kết quả chưa xác định là bị từ chối
Payment có thể đã được provider chấp nhận dù response không đến kịp thời. Trước tiên hãy yêu cầu status hiện tại hoặc chờ xác nhận, sau đó mới quyết định có cần giao dịch khác hay không.
Độ tin cậy và đối soát
Bảo vệ duplicate và đối soát tài chính
Độ tin cậy của Payment API phụ thuộc vào hành vi an toàn với request lặp lại, confirmation bị trễ và lỗi một phần.
Bảo vệ khỏi giao dịch lặp lại
Mỗi deposit, withdrawal và refund có một số duy nhất.
Request lặp lại trả về kết quả hiện có và không tạo giao dịch tài chính mới.
Notification lặp lại được kiểm tra theo event number và trạng thái payment hiện tại.
Balance change được liên kết với payment number và chỉ áp dụng một lần.
Accounting tài chính và đối soát
Lưu riêng amount, fee, net amount, currency và provider reference.
Không ghi đè ngược thời gian lên bản ghi đã hoàn tất; hãy tạo adjustment riêng.
Đối soát API operation, provider report, balance change và payout.
Ghi lại từng chênh lệch, nguyên nhân, owner và kết quả xử lý.
Testing
Cần kiểm tra gì trước launch
Kiểm tra payment thành công, bị từ chối, mất kết nối, confirmation lặp lại, kết quả chưa xác định, refund và đối soát tài chính.
Deposit và withdrawal thành công
Tất cả status trung gian, confirmation, balance change và reporting cuối.
Giao dịch bị từ chối
Không đủ tiền, thông tin không hợp lệ, vượt limit, ngân hàng từ chối, risk review và payment method không khả dụng.
Mất kết nối
Kết nối bị ngắt sau khi request gửi đi, còn confirmation đến sau hoặc được yêu cầu riêng.
Request lặp lại
Cùng giao dịch hoặc confirmation đến lại sau khi xử lý đã hoàn tất.
Refund và cancellation
Refund toàn phần và một phần, cancellation trước khi xử lý và cấm hủy giao dịch đã hoàn tất.
Đối soát
Amount, fee, status cuối, balance và provider report khớp nhau sau tất cả scenario.
Checklist trước launch
Production payment được bật sau khi đã kiểm tra status, confirmation, bảo vệ duplicate, balance và financial reporting.
Test và production environment sử dụng credential, notification endpoint và account khác nhau.
Việc user quay lại website không được dùng làm bằng chứng payment thành công.
Signature và event number được xác minh trước khi thay đổi balance.
Deposit, withdrawal và refund được bảo vệ khỏi thực thi lặp lại.
Status chưa xác định được làm rõ với provider và kiểm tra trong quá trình đối soát.
Đã cấu hình error alert, PSP report và quy trình điều tra chênh lệch.
Cần thiết kế payment flow?
Gửi danh sách PSP, payment method, currency, market, quy tắc balance và status. APIACE sẽ giúp xây dựng deposit, withdrawal, refund, confirmation và đối soát tài chính.