Payroll Product Mapping | API Developer Portal

Image

Image

Product introduction

ACB cung cấp dịch vụ chi lương qua Open API nhằm giúp Khách hàng tạo và duyệt lệnh chi lương trên chính hệ thống/phần mềm của khách hàng.
Dịch vụ chi lương bao gồm:
• Chi Lương ngoài hệ thống ACB
• Chi Lương trong hệ thống ACB

- Thực hiện chi lương trên chính hệ thống Khách hàng, nhằm tối ưu hóa chi phí quản lý Doanh nghiệp
- Giảm thời gian thực hiện chi lương

• Điều kiện tài khoản chi
   - Khách hàng phải đăng ký TKTT dịch vụ chi lương tại ACB
   - TKTT thuộc danh sách được phép giao dịch và phải đang hoạt động.
   - Khách hàng sử dụng dịch vụ chi lương theo danh sách chỉ định (whitelist) thì danh sách này phải được đăng ký trước với ngân hàng.
• Điều kiện tài khoản thụ hưởng:
   - Trong hệ thống ACB:
       + Tài khoản thụ hưởng không nằm trong danh sách cấm nhận tiền còn hiệu lực.
       + Tài khoản thụ hưởng là tài khoản cùng đơn vị tiền tệ với tài khoản trích.
       + Trạng thái của tài khoản thụ hưởng khác trạng thái đóng.
       + Tên đơn vị thụ hưởng phải trùng khớp với họ tên chủ tài khoản trong ngân hàng.
       + Chủ tài khoản thụ hưởng không phải là người nước ngoài.
   - Ngoài hệ thống: Ngân hàng thụ hưởng phải nằm trong danh sách ngân hàng thụ hưởng do ACB cung cấp.

#Bước	Mô tả
Bước 1: Khách hàng	Tạo bó giao dịch chi lương qua API Khởi Tạo Bó Giao Dịch bao gồm các thông tin: • Loại chuyển khoản • Tài khoản thụ hưởng • Tên Tài khoản thụ hưởng • Mã bankcode (đối với luồng Citad) • Số tiền • Nội dung chuyển • Chữ ký xác thực giao dịch
Bước 2: ACB	Kiểm tra bó giao dịch chi lương: - Bó giao dịch hợp lệ: ACB hạch toán các giao dịch hợp lệ và thông báo kết quả hạch toán cho KH. - Bó giao dịch không hợp lệ: Phản hồi lỗi cho khách hàng.
Bước 3: Khách hàng	Nhận thông tin trả kết quả xử lý bó giao dich.

Errors list

#	HTTP Status Code	Response Code	Description
1	200	00000000	Success
2	289	02010001	Mismatch certificate
3	289	02010001	Not found partner
4	289	02010002	Not found batch trace number
5	289	02010003	Not found transaction trace number
6	289	02010004	The account not found
7	289	02010005	Batch trace number is duplicated
8	289	02010006	Not found certificate
9	289	02010007	Request trace is duplicated
10	400	01010002	Missing token
11	400	01010004	Missing X-Request-Id
12	400	01010005	Missing X-Channel
13	400	01030001	Bad request format
14	400	01030002	Transaction trace number is duplicated
15	401	01010001	Invalid token
16	403	01010003	Forbidden
17	408	02030001	Unknown Internal Server Error
18	500	02039999	Request timeout

Kịch bản kiểm thử

KỊCH BẢN KIỂM THỬ CÁC NGHIỆP VỤ SẢN PHẨM THÔNG TIN TÀI KHOẢN

(Phục vụ cho việc kiểm thử sản phẩm trên hệ thống)

STT	Tính năng	Mô tả tình huống	Điều kiện	Kết quả mong đợi
Truy vấn danh sách giao dịch
1	Truy vấn danh sách giao dịch	Truy vấn danh sách giao dịch thành công	- Fromdate = todate - Account number hợp lệ - Ngày truy vấn có phát sinh giao dịch	Http code: 200 Data trả về chi tiết giao dịch
2	Truy vấn danh sách giao dịch	Truy vấn danh sách giao dịch không có dự liệu	- Fromdate = todate - Account number hợp lệ - Ngày truy vấn không có phát sinh giao dịch	Http code: 200 Data rỗng
3	Truy vấn danh sách giao dịch	Truy vấn danh sách giao dịch thất bại	- Sai định dạng ngày - Hoặc page, size không hợp lệ	Http code: 202 Error code: 42020018 Message: Bad request format
4	Truy vấn sanh sách giao dịch	Truy vấn danh sách giao dịch thất bại	- Fromdate khác todate - Account number hợp lệ	Http code: 202 Error code: 42020018 Message: Bad request format
5	Truy vấn danh sách giao dịch	Truy vấn danh sách giao dịch thất bại	- Fromdate = todate - Account number không thuộc khách hàng	Http code: 202 Error code: 42020006 Message: The account not found
6	Truy vấn danh sách giao dịch	Truy vấn danh sách giao dịch thất bại	- Token hết hạn	Http code: 401 Error code: 42020183 Message: Token is expired
Truy vấn thông tin số dư tài khoản
1	Truy vấn số dư tài khoản	Truy vấn số dư tài khoản thành công	- Account number hợp lệ	Http code: 200 Data trả về có current_balance và available_balance
2	Truy vấn số dư tài khoản	Truy vấn số dư thất bại	- Account number không thuộc khách hàng	Http code: 202 Error code: 42020006 Message: The account not found
3	Truy vấn số dư tài khoản	Truy vấn số dư thất bại	- Không nhập account number	Http code: 202 Error code: 42020018 Message: Bad request format
4	Truy vấn số dư tài khoản	Truy vấn số dư thất bại	- Token hết hạn	Http code: 401 Error code: 42020183 Message: Token is expired
C. Truy vấn lịch sử giao dịch
01	Truy vấn lịch sử giao dịch theo khoảng số giao dịch trong khoảng thời gian	Truy vấn lịch sử giao dịch thành công	Yêu cầu ràng buộc của các trường theo danh sách bên dưới: account = Required from_transaction_number = Required to_transaction_number = Required transaction_number = Not submit from_date = Required to_date = Required date = Not submit limit = Not submit transaction_source = Optional currency = Optional	Thực hiện truy vấn thành công Mã trả về: 200 OK
02	Truy vấn lịch sử giao dịch theo khoảng số giao dịch trong khoảng thời gian	Truy vấn lịch sử giao dịch thất bại	Yêu cầu ràng buộc => đổi sang không ràng buộc của các trường theo danh sách bên dưới: account = Required from_transaction_number = Required to_transaction_number = Not submit transaction_number = Not submit from_date = Required to_date = Required date = Not submit limit = Not submit transaction_source = Optional currency = Optional	Mã trả về: 400 - 40020400 some inputs are missing
03	Truy vấn lịch sử giao dịch theo chính xác số giao dịch	Truy vấn lịch sử giao dịch thành công	Yêu cầu ràng buộc của các trường theo danh sách bên dưới: account = Required from_transaction_number = Not submit to_transaction_number = Not submit transaction_number = Required from_date = Required to_date = Required date = Not submit limit = Not submit transaction_source = Optional currency = Optional	Thực hiện truy vấn thành công Mã trả về: 200 OK
04	Truy vấn lịch sử giao dịch theo chính xác số giao dịch	Truy vấn lịch sử giao dịch thất bại	Yêu cầu ràng buộc => đổi sang không ràng buộc của các trường theo danh sách bên dưới: account = Required from_transaction_number = Not submit to_transaction_number = Not submit transaction_number = Not submit from_date = Required to_date = Not submit date = Not submit	Thực hiện truy vấn không thành công Mã trả về: 400 - 40020400 some inputs are missing
05	Truy vấn cả giao dịch trong khoản thời gian	Truy vấn lịch sử giao dịch thành công	Yêu cầu ràng buộc của các trường theo danh sách bên dưới: account = Required from_transaction_number = Not submit to_transaction_number = Not submit transaction_number = Not submit from_date = Required to_date = Required date = Not submit limit = Not submit transaction_source = Optional currency = Optional	Thực hiện truy vấn thành công Mã trả về: 200 OK
06	Truy vấn cả giao dịch trong khoản thời gian	Truy vấn lịch sử giao dịch thất bại	Yêu cầu ràng buộc => đổi sang không ràng buộc của các trường theo danh sách bên dưới: account = Required from_transaction_number = Not submit to_transaction_number = Not submit transaction_number = Not submit from_date = Not submit to_date = Not submit date = Not submit limit = Not submit transaction_source = Optional currency = Optional	Thực hiện truy vấn không thành công Mã trả về: 400 - 40020400 some inputs are missing
07	Truy vấn lịch sử giao dịch theo khoản số giao dịch	Truy vấn lịch sử giao dịch thành công	Yêu cầu ràng buộc của các trường theo danh sách bên dưới: account = Required from_transaction_number = Required to_transaction_number = Required transaction_number = Not submit from_date = Not submit to_date = Not submit date = Required limit = Not submit transaction_source = Optional currency = Optional	Thực hiện truy vấn thành công Mã trả về: 200 OK
08	Truy vấn lịch sử giao dịch theo khoản số giao dịch	Truy vấn lịch sử giao dịch thất bại	Yêu cầu ràng buộc => đổi sang không ràng buộc của các trường theo danh sách bên dưới: account = Required from_transaction_number = Required to_transaction_number = Required transaction_number = Not submit from_date = Not submit to_date = Not submit date = Not submit limit = Not submit transaction_source = Optional currency = Optional	Thực hiện truy vấn không thành công Mã trả về: 400 - 40020400 some inputs are missing
09	Truy vấn lịch sử giao dịch theo chính xác số giao dịch	Truy vấn lịch sử giao dịch thành công	Yêu cầu ràng buộc của các trường theo danh sách bên dưới: account = Required from_transaction_number = Not submit to_transaction_number = Not submit transaction_number = Required from_date = Not submit to_date = Not submit date = Required limit = Not submit transaction_source = Optional currency = Optional	Thực hiện truy vấn thành công Mã trả về: 200 OK
10	Truy vấn lịch sử giao dịch theo chính xác số giao dịch	Truy vấn lịch sử giao dịch thất bại	Yêu cầu ràng buộc => đổi sang không ràng buộc của các trường theo danh sách bên dưới: account = Required from_transaction_number = Not submit to_transaction_number = Not submit transaction_number = Not submit from_date = Not submit to_date = Not submit date = Required limit = Not submit transaction_source = Optional currency = Optional	Thực hiện truy vấn không thành công Mã trả về: 400 - 40020400
11	Truy vấn tất cả giao dịch theo ngày	Truy vấn lịch sử giao dịch thành công	Yêu cầu ràng buộc của các trường theo danh sách bên dưới: account = Required from_transaction_number = Not submit to_transaction_number = Not submit transaction_number = Not submit from_date = Not submit to_date = Not submit date = Required limit = Not submit transaction_source = Optional currency = Optional	Thực hiện truy vấn thành công Mã trả về: 200 OK
12	Truy vấn tất cả giao dịch theo ngày	Truy vấn lịch sử giao dịch thất bại	Yêu cầu ràng buộc => đổi sang không ràng buộc của các trường theo danh sách bên dưới: account = Required from_transaction_number = Not submit to_transaction_number = Not submit transaction_number = Not submit from_date = Not submit to_date = Not submit date = Not submit limit = Not submit transaction_source = Optional currency = Optional	Thực hiện truy vấn không thành công Mã trả về: 400 - 40020400
13	Truy vấn lịch sử giao dịch gần nhất theo giới hạn	Truy vấn lịch sử giao dịch thành công	Yêu cầu ràng buộc của các trường theo danh sách bên dưới: account = Required from_transaction_number = Not submit to_transaction_number = Not submit transaction_number = Not submit from_date = Not submit to_date = Not submit date = Not submit limit = Required transaction_source = Optional currency = Optional	Thực hiện truy vấn thành công Mã trả về: 200 OK
14	Truy vấn lịch sử giao dịch gần nhất theo giới hạn	Truy vấn lịch sử giao dịch thất bại	Yêu cầu ràng buộc => đổi sang không ràng buộc của các trường theo danh sách bên dưới: account = Required from_transaction_number = Not submit to_transaction_number = Not submit transaction_number = Not submit from_date = Not submit to_date = Not submit date = Not submit limit = Not submit transaction_source = Optional currency = Optional	Thực hiện truy vấn không thành công Mã trả về: 400 - 40020400
15	Truy vấn lịch sử giao dịch	Truy vấn giao dịch thất bại	- Token hết hạn	Error code: 42020183 Message: Token is expired
16	Truy vấn lịch sử giao dịch	Truy vấn giao dịch thất bại	- Sai định dạng ngày	Error code: 42020018 Message: Bad request format

KỊCH BẢN KIỂM THỬ CÁC NGHIỆP VỤ CHI LƯƠNG QUA API

(Phục vụ cho việc kiểm thử sản phẩm trên hệ thống)

STT	Tính năng	Mô tả tình huổng	Điều kiện	Kết quả mong đợi
1	Khởi tạo bó giao dịch	- Tạo bó giao dịch chuyển khoản trong hệ thống ACB thành công - Nhận bằng tài khoản	Thông tin thụ hưởng hợp lệ Không tính phí chi lương	Http code: 200 BatchStatus: ORIG
2	Khởi tạo bó giao dịch	- Tạo bó giao dịch chuyển khoản trong hệ thống ACB thành công - Nhận bằng tài khoản	Thông tin thụ hưởng hợp lệ Có tính phí chi lương	Http code: 200 BatchStatus: ORIG
3	Khởi tạo bó giao dịch	- Tạo bó giao dịch chuyển khoản ngoài hệ thống ACB thành công (luồng nhập số Tài khoản) - Nhận bằng tài khoản	Bank.code/province hợp lệ Không tính phí chi lương	Http code: 200 BatchStatus: ORIG
4	Khởi tạo bó giao dịch	- Tạo bó giao dịch chuyển khoản ngoài hệ thống ACB thành công (luồng nhập số Tài khoản) - Nhận bằng tài khoản	Bank.code/province hợp lệ Có tính phí chi lương	Http code: 200 BatchStatus: ORIG
5	Khởi tạo bó giao dịch	- Tạo bó giao dịch chuyển khoản ngoài hệ thống ACB thành công (luồng nhập số Thẻ) - Nhận bằng thẻ	Bank.code/province hợp lệ Không tính phí chi lương	Http code: 200 BatchStatus: ORIG
6	Khởi tạo bó giao dịch	- Tạo bó giao dịch chuyển khoản ngoài hệ thống ACB thành công (luồng nhập số Thẻ) - Nhận bằng thẻ	Bank.code/province hợp lệ Có tính phí chi lương	Http code: 200 BatchStatus: ORIG
7	Khởi tạo bó giao dịch	- Tạo bó giao dịch không thành công khi RequestTrace đã từng tồn lại	Đã có bó giao dịch với RequestTrace được tạo trước đó	Http code: 289 Error code: 02020007 Message: Request trace is duplicated
8	Khởi tạo bó giao dịch	Tạo bó giao dịch không thành công khi BatchTraceNumber đã từng tồn tại	Đã có bó giao dịch với BatchTraceNumber được tạo trước đó	Http code: 289 Error code: 02020005 Message: Batch trace number is duplicated
9	Khởi tạo bó giao dịch	- Tạo bộ giao dịch không thành công khi token hết hạn/ token không hợp lệ	Token hết hạn/ Token không hợp lệ	Http code: 401 Error code: 01010001 Message: Invalid token
10	Khởi tạo bó giao dịch	- Tạo bộ giao dịch không thành công khi không truyền token	Không truyền token	Http code: 400 Error code: 01010002 Message: Missing token
11	Khởi tạo bó giao dịch	- Tạo bộ giao dịch không thành công khi không truyền chữ ký CA	Thiếu chữ ký CA khi khởi tạo bó giao dịch	Http code: 289 Error code: 0201000 Message: Mismatch certificate
12	Khởi tạo bó giao dịch	- Tạo bộ giao dịch không thành công khi tài khoản trích không thuộc Owner	Tài khoản trích không thuộc Owner	Http code: 289 Error code: 02020004 Message: The account not found
13	Khởi tạo bó giao dịch	- Tạo bộ giao dịch không thành công khi tài khoản trích không truyền giá trị trường Channel	Không truyền giá trị trường Channel	Http code: 400 Error code: 01010005 Message: Missing X-Channel
14	Khởi tạo bó giao dịch	- Tạo bộ giao dịch không thành công khi tài khoản trích không truyền giá trị trường Request-Id	Không truyền giá trị trường Request-Id	Http code: 400 Error code: 01010004 Message: Missing X-Request-Id
15	Thông báo kết quả trạng thái gói giao dịch	- Đối tác nhận được thông tin kết quả xử lý gói giao dịch thông qua url call back	Khởi tạo bó giao dịch thành công	Nhận thông tin trả kết quả xử lý bó giao dich – thành công BatchStatus: COMP Nhận thông tin trả kết quả xử lý giao dịch con trong bó – thành công TransactionStatus: TRAN
16	Truy vấn trạng thái bó giao dịch	- Truy vấn bó giao dịch với giá trị BatchTraceNumber đã khởi tạo thành công		Response Code: 00000000 Response Message: success
17	Truy vấn trạng thái bó giao dịch	- Truy vấn bó giao dịch với giá trị TransactionTraceNumber đã khởi tạo thành công		Response Code: 00000000 Response Message: success
18	Truy vấn trạng thái bó giao dịch	- Truy vấn bó giao dịch với giá trị BatchTraceNumber không tồn tại		Http code: 289 Error code: 02020002 Message: Not found batch trace number
19	Truy vấn chi tiết giao dịch trong bó	- Truy vấn chi tiết giao dịch với giá trị TransactionTraceNumber không tồn tại		Http code: 289 Error code: 02020003 Message: Not found transaction trace number

key mapping

payroll

Mô tả

ACB cung cấp dịch vụ chi lương qua Open API nhằm giúp Khách hàng tạo và duyệt lệnh chi lương trên chính hệ thống/phần mềm của khách hàng

API Order

payroll-post-batch|payroll-callback|payroll-get-batch|payroll-get-batch-detail