Tiền: số dư, hạn mức và công nợ

12 phút đọc

Trong hệ thống Ferry, đối tác không cần gọi bất kỳ lệnh thanh toán độc lập nào. Toàn bộ quy trình trừ tiền vé diễn ra tự động bên trong bước xác nhận xuất vé của booking, được đối chiếu ngược theo chuỗi cấp bậc tổ chức từ đại lý lên đến tổ chức gốc.

Trước khi bắt đầu

Điều kiện	Ý nghĩa nghiệp vụ	Tài liệu tham khảo
Khóa API hợp lệ	Toàn bộ các API tra cứu số dư, giao dịch và công nợ yêu cầu xác thực	Xác thực bằng API key
Xác định cấp bậc tổ chức	Biết rõ vị trí của bạn trong chuỗi để hiểu cơ chế kiểm tra hạn mức đệ quy	Tổng quan bề mặt tích hợp
Thông tin tổ chức cấp trên	Nhận thông tin tài khoản ngân hàng và cú pháp nạp tiền chính xác	Xem mục nạp tiền bên dưới
Nắm rõ giá NET đại lý	Số tiền bị trừ thực tế được tính theo giá NET, không phải giá khách cuối	Giá vé và markup nhiều cấp
Quy ước định dạng tiền	Tiền là số nguyên đồng (VNĐ), không có số thập phân hay trường tiền tệ	Quy ước chung

Cơ chế trừ tiền khi xác nhận xuất vé

Sơ đồ dưới đây minh họa quy trình kiểm tra số dư đệ quy và giữ tiền bên trong bước xác nhận xuất vé:

sequenceDiagram
    autonumber
    participant P as "Hệ thống của bạn"
    participant F as "Ferry API"
    participant B as "Số dư tổ chức của bạn"
    participant U as "Tổ chức cấp trên"
    participant K as "Số dư khách hàng"

    P->>F: "Xác nhận xuất vé (confirmToIssue)"
    F->>B: "Kiểm tra số dư khả dụng và hạn mức"

    alt Tổ chức của bạn không đủ tiền
        B-->>F: "Không đủ số dư"
        F-->>P: "Lỗi số dư tổ chức (nạp thêm tiền để xử lý)"
    else Tổ chức của bạn đủ tiền
        B-->>F: "Đủ tiền"
        F->>U: "Kiểm tra đệ quy hạn mức chuỗi cấp trên"

        alt Một cấp phía trên hết hạn mức
            U-->>F: "Hết hạn mức cấp trên"
            F-->>P: "Lỗi số dư (cần liên hệ cấp trên hoặc Ferry)"
        else Toàn bộ chuỗi cấp trên đều đủ
            U-->>F: "Đủ hạn mức tới gốc"
            F->>K: "Kiểm tra số dư khả dụng của khách hàng"

            alt Khách thiếu tiền và không được nợ
                K-->>F: "Thiếu tiền"
                F-->>P: "Lỗi số dư khách hàng"
            else Khách đủ tiền hoặc được phép nợ
                K-->>F: "Hợp lệ"
                F-->>P: "Khóa tiền thành công, chuyển sang gọi hãng xuất vé"
            end
        end
    end

Hạn mức khả dụng và kiểm tra chuỗi đệ quy

Khả năng chi tiêu của một tổ chức được tính bằng Số dư khả dụng + Hạn mức tín dụng.

Khi xác nhận xuất vé, hệ thống thực hiện kiểm tra đệ quy ngược lên toàn bộ các cấp tổ chức cha cho đến khi chạm tới tổ chức gốc:

Mỗi cấp con sẽ phát sinh nghĩa vụ thanh toán cho cấp cha một khoản đúng bằng giá NET ở góc nhìn của cấp đó.
Rủi ro hết hạn mức cấp trên: Đơn hàng của bạn có thể thất bại do một tổ chức cấp trên sử dụng hết hạn mức tín dụng, ngay cả khi số dư tài khoản của bạn vẫn còn rất nhiều. Khi gặp tình huống này, việc tự nạp thêm tiền vào tài khoản của bạn sẽ không có tác dụng; bạn cần liên hệ ngay với tổ chức cấp trên hoặc quản trị viên Ferry để được hỗ trợ nâng hạn mức.

Ferry còn kiểm ví khách hàng cuối. Khả năng chi của khách bằng số dư trừ phần đang giữ cho yêu cầu rút tiền. Nếu thiếu tiền và không được phép nợ, booking giữ nguyên. Nếu được phép nợ, tổ chức cha cho khách vay và trạng thái thanh toán chuyển sang đã trả bằng nợ; khi khách trả hết nợ, trạng thái tự chuyển sang đã trả, không cần gọi thêm API.

Quy trình nạp tiền và dòng tiền vào hệ thống

Sơ đồ dưới đây thể hiện đường đi của dòng tiền từ khi chuyển khoản đến khi ghi nhận vào số dư:

flowchart TB
    A["Chuyển khoản ngoài hệ thống<br/>theo thông tin kênh nạp của cấp trên"] --> B["Cổng ngân hàng của Ferry ghi nhận"]
    B --> C["Hệ thống tự động cộng số dư,<br/>không cần gọi API xác nhận"]
    C --> D["Số dư khả dụng của đại lý tăng"]
    D --> E["Lệnh xuất vé tự động trừ từ số dư này"]
    E --> F["Ghi nhật ký giao dịch và cập nhật sổ nợ"]
    F --> G["Đại lý đọc dữ liệu để đối soát định kỳ"]

Bảng dưới đây tóm tắt các thao tác theo từng bước:

Bước	Hệ thống của bạn	Phía Ferry	Lưu ý đối tác
1	Lấy phương thức nạp tiền của cấp trên	Cung cấp số tài khoản và cú pháp chuyển khoản	Lấy thông tin từ API tổ chức, tránh dùng số cũ
2	Chuyển khoản ngân hàng ngoài hệ thống	Cổng ngân hàng tiếp nhận giao dịch	Chuyển khoản đúng cú pháp để hệ thống tự khớp
3	Tra cứu hạn mức và số dư khả dụng	Trả số dư thực tế và hạn mức tín dụng còn lại	Kiểm tra trước khi thực hiện xuất vé hàng loạt
4	Gọi lệnh xác nhận xuất vé	Khấu trừ số dư theo giá NET của booking	Tiền được trừ tự động cho từng chặng đơn
5	Đọc nhật ký giao dịch để đối soát	Trả danh sách các giao dịch phát sinh	Đối chiếu mã giao dịch và mã booking tương ứng
6	Theo dõi sổ công nợ	Cập nhật các khoản dư nợ giữa các cấp tổ chức	Dành cho đại lý có mạng lưới tổ chức con

Khi nghi ngờ thông tin kênh nạp của cấp trên bị lộ, tổ chức có thể gọi lệnh làm mới mã bảo mật kênh nạp (Organizations). Sau khi làm mới, thông tin kênh nạp cũ sẽ ngừng hiệu lực ngay lập tức.

Đối tác không xử lý thông báo thanh toán từ ngân hàng; ngân hàng gửi trực tiếp cho Ferry. API đối tác cũng không có lệnh hoàn tiền trực tiếp: tiền hoàn đi qua luồng huỷ vé và hoàn tiền.

Các loại giao dịch trong nhật ký đối soát

Hệ thống ghi nhận mọi biến động tài chính trong bảng nhật ký giao dịch với các mã định danh chuẩn:

Mã	Loại nghiệp vụ	Thời điểm phát sinh
`PB`	Thanh toán booking	Khi xác nhận xuất vé booking thành công
`PO`	Thanh toán chặng đơn	Phát sinh song song với `PB`, ở mức chi tiết từng chặng
`DP`	Nạp tiền khách hàng	Khi nạp tiền vào ví của khách hàng cuối
`OD`	Nạp tiền đại lý	Khi tiền chuyển khoản ngân hàng của bạn được ghi nhận
`SO`	Đồng bộ số dư hãng	Giao dịch đối soát nội bộ giữa Ferry và hãng tàu
`BL`	Giao dịch thông báo	Dấu mốc ghi nhận trạng thái không làm thay đổi số dư
`UK`	Giao dịch chưa xác định	Tiền vào nhưng hệ thống chưa khớp được chủ thể
`CB`	Ghi nhận cho khách nợ	Khi booking được xuất vé dưới hình thức cho khách nợ
`CR`	Khách thanh toán nợ	Khi khách hàng hoàn tất việc trả nợ
`CH`	Hoàn tiền do lỗi thanh toán	Khi tiến trình thanh toán gặp trục trặc kỹ thuật
`RF`	Hoàn tiền khi hủy vé	Khi yêu cầu hủy được duyệt tới tổ chức gốc
`DR`	Cấn trừ công nợ	Bù trừ công nợ giữa các cấp tổ chức
`RT`	Hủy lượt nạp tiền	Đảo ngược một giao dịch nạp tiền bị lỗi
`WD`	Rút tiền khỏi ví	Khi khách hàng thực hiện yêu cầu rút tiền
`MA`	Điều chỉnh thủ công	Nhân viên vận hành Ferry can thiệp điều chỉnh số liệu

Mỗi giao dịch gồm ba thuộc tính đối soát quan trọng:

Trạng thái: Thành công, thất bại, hoặc đã hủy. Khi tính toán số dư thực tế, chỉ tổng hợp các giao dịch có trạng thái Thành công.
Chiều biến động: Tăng hoặc giảm số dư; đọc thuộc tính chiều, không suy từ dấu của số tiền.
Chủ thể giao dịch: Khách hàng, booking, chặng đơn, hãng tàu, tổ chức hoặc chưa xác định.

Nếu phát hiện giao dịch mang mã UK (chưa xác định), bạn có thể gọi API gán loại giao dịch để liên kết khoản tiền với đúng đối tượng, tránh gây lệch sổ sách kế toán.

Xử lý giao dịch treo và độ trễ hệ thống

Các tình huống giao dịch treo và độ trễ đối soát cần lưu ý:

Khóa xuất vé (600 giây): Khi đang xuất vé mà gọi lại, hệ thống báo lỗi đang xử lý; cần chờ hết tiến trình và tra cứu lại booking.
Khóa thanh toán (180 giây): Khi bước trừ tiền đang chạy mà gọi lại, hệ thống giữ khóa thanh toán 180 giây và yêu cầu chờ trước khi thử lại.
Xuất vé hỏng một phần: Với booking nhiều chặng, nếu một chặng thành công và chặng sau lỗi, hệ thống hoàn lại tiền chặng hỏng nhưng giữ tiền chặng đã xong (booking chưa có vé nhưng số dư đã trừ một phần).
Booking đã trả tiền nhưng chưa có vé: Tác vụ đối chiếu nền tự động đồng bộ lại với hãng sau vài phút mà không cần gọi thêm lệnh.
Chu kỳ hoàn tiền (15 phút): Tiền hoàn vé cho tổ chức con chạy theo tác vụ định kỳ 15 phút một lượt (thu hồi bản ghi treo sau 10 phút). Tiền có thể ghi có trễ tới 15 phút, đôi khi lâu hơn; đây không phải thời hạn hoàn tiền được bảo đảm.
Số dư là nguồn sự thật: Số dư tài khoản là nguồn sự thật chính, nhật ký giao dịch là bản ghi tham chiếu. Hai bên có thể lệch tạm thời khi tác vụ nền đang chạy; nếu lệch kéo dài quá chu kỳ 15 phút mới cần tra soát sự cố.

Ba lỗi số dư cần phân biệt rõ

Trong quá trình tích hợp, đối tác thường gặp ba thông báo lỗi liên quan đến số dư:

Số dư booking không đủ: Tài khoản của bạn hoặc tổ chức cấp trên không đủ tiền để thanh toán giá NET cho booking đang xử lý.
Số dư khách hàng không đủ: Ví tiền của khách hàng cuối không đủ thanh toán và tài khoản của khách không được cấu hình cho phép ghi nợ.
Số dư không đủ để tạo yêu cầu hủy vé: Tài khoản không đủ số dư để chi trả phí dịch vụ hủy vé theo quy định.

Cả ba lỗi này đều không thể giải quyết bằng việc thử gọi lại liên tục. Đối tác cần kiểm tra và nạp đủ tiền cho đúng chủ thể đang thiếu trước khi tiếp tục thao tác.

Khi phân loại lỗi, đối chiếu mã thay vì chỉ đọc thông báo: 120205 là số dư booking, 130205 là số dư khách hàng, 160105 là số dư để tạo yêu cầu huỷ vé. Trong bước xuất vé còn có 120120 cho số dư tổ chức và 120101 cho số dư khách hàng. Xem Lỗi và cách xử lý trước khi quyết định thử lại.

Lỗi thường gặp và cách xử lý

Triệu chứng	Nguyên nhân khả dĩ	Hướng xử lý	Có nên thử lại
Lỗi số dư dù vừa chuyển khoản	Tiền chưa vào tài khoản ngân hàng hoặc ghi sai cú pháp nạp	Kiểm tra nhật ký giao dịch; đối chiếu lại cú pháp chuyển khoản	Chờ tiền vào
Lỗi số dư dù tài khoản của bạn còn nhiều tiền	Một tổ chức cấp trên trong chuỗi đã hết hạn mức tín dụng	Liên hệ tổ chức cấp trên hoặc Ferry để nâng hạn mức	Không gọi lại
Lỗi số dư khách hàng không đủ	Ví khách hàng không đủ tiền và không được thiết lập cho nợ	Nạp tiền cho khách hoặc bật cấu hình cho nợ nếu được phép	Không gọi lại
Giao dịch mang mã chưa xác định (UK)	Khoản tiền chuyển vào chưa khớp được đối tượng thụ hưởng	Dùng API gán loại giao dịch để liên kết đúng đối tượng	Có, sau khi gán
Tiền hoàn vé chưa thấy ghi có vào số dư	Tác vụ hoàn tiền chạy định kỳ 15 phút/lần	Chờ hết chu kỳ 15 phút rồi kiểm tra lại nhật ký	Không gọi dồn dập
Số dư và nhật ký giao dịch tạm lệch nhau	Tác vụ nền đối soát đang chạy dở	Đọc lại sau một chu kỳ 15 phút	Có, sau khi chờ
Xuất vé hỏng một phần, số dư bị trừ	Một chặng thành công, chặng sau lỗi	Đọc chi tiết từng chặng đơn rồi liên hệ Ferry	Không tự tạo lại booking

Tra cứu trên Scalar

Để tra cứu lược đồ tham số chi tiết và thử nghiệm gọi trực tiếp, mở giao diện Scalar UI theo các nhóm nghiệp vụ:

Nội dung cần xem	Nhóm trên Scalar
Tra cứu nhật ký giao dịch, lọc theo loại và đối tượng	`Transactions`
Gán loại cho giao dịch chưa xác định	`Transactions`
Theo dõi sổ công nợ giữa các tổ chức	`Debt Ledgers`
Xem phương thức nạp tiền của tổ chức cấp trên	`Organizations`
Tra cứu hạn mức tín dụng khả dụng của tổ chức	`Organizations`
Làm mới mã bảo mật của kênh nạp tiền	`Organizations`

Lưu ý rằng trên Scalar không có nhóm API nào mang tên “Payments” dành cho tầng đối tác, vì toàn bộ việc thanh toán diễn ra tự động bên trong nhóm Bookings.

Xem hướng dẫn đăng nhập và điền khóa API tại Tham chiếu API.

Đọc tiếp

Trang	Nội dung liên quan
Đặt vé: vòng đời một booking	Vòng đời đơn và thời điểm khấu trừ tiền vé
Xuất vé và đơn hàng	Trình tự các bước xử lý thanh toán và gọi hãng
Giá vé và markup nhiều cấp	Cơ chế tính giá NET và phân bổ lợi nhuận
Huỷ vé và hoàn tiền	Quy trình hoàn tiền và chu kỳ xử lý tiền hoàn
Quy ước chung	Chuẩn định dạng tiền tệ và xử lý phân trang nhật ký

Điểm chưa xác định

Câu hỏi	Tình trạng
Cảnh báo hết hạn mức cấp trên cho đối tác đa cấp	Chưa có cơ chế tự động gửi cảnh báo khi tổ chức cấp trên sắp cạn hạn mức; cần liên hệ kênh vận hành khi gặp lỗi.
Thời gian ghi có tiền chuyển khoản ngân hàng	Phụ thuộc vào cổng ngân hàng và thời gian xử lý giao dịch, không có cam kết SLA cứng trong API.
Thời gian xử lý tự động giao dịch chưa xác định (`UK`)	Chưa xác định thời gian xử lý tự động; hiện đối tác cần chủ động dùng API gán loại giao dịch.