Virtual Account Product Mapping | API Developer Portal

Image

Image

Product introduction

ACB cung cấp dịch vụ tài khoản định danh (Virtual Account) cho Khách hàng Doanh nghiệp (KHDN).
Tài Khoản Định Danh là một giải pháp công nghệ số giúp Doanh nghiệp quản lý các khoản ghi có, trong đó có sự liên kết giữa một Tài Khoản thanh toán chính của Doanh nghiệp với tập hợp các Tài Khoản Định Danh

- Quản lý hiệu quả tình trạng ghi có của các tài khoản, cập nhật thông tin chính xác theo Người chuyển tiền/mục đích chuyển.

- Tự động hạch toán/ đối soát các khoản tiền ghi có về tài khoản.

- Khách hàng có thể tuỳ ý lựa chọn số tài khoản đẹp theo nhu cầu quản lý nội bộ mà vẫn đảm bảo an toàn bảo mật các giao dịch ngân hàng.

- Dễ dàng tải các báo cáo trên tài khoản về phầm mềm kế toán doanh nghiệp (ERP).

Tính năng:

Tên Đơn vị thụ hưởng có 2 trường hợp:

+ Shortname và Diễn giải (Shortname phải đăng ký với ACB).

+ Tên Đơn vị thụ hưởng là tên pháp nhân đăng ký với ACB.

Điều kiện sử dụng bộ API này:

- Khách hàng doanh nghiệp đã thực hiện đăng ký đầu số tài khoản định danh tại quầy giao dịch ACB và có trạng thái đang hoạt động đến thời điểm thực hiện nghiệp vụ.

- Giá trị đầu số được đăng ký tại quầy lần đầu phải bao gồm cả đăng ký đầu số và nội dung số tài khoản định danh (theo quy tắc số 2 trong mô tả API đăng ký tài khoản định danh).

- Trường hợp hủy, khách hàng sử dụng với yêu cầu hủy nội dung số tài khoản định danh (số tài khoản phải có trạng thái đang hoạt động). Nếu muốn hủy đầu số tài khoản định danh, khách hàng phải đến quầy giao dịch để thực hiện.

- Trường hợp cập nhật thông tin, khách hàng chỉ có thể cập nhật thông tin diễn giải cho số tài khoản định danh có trạng thái đang hoạt động.

1. Quy trình đăng ký tài khoản định danh

#Bước	Mô tả
Bước 1: Đăng ký tài khoản định danh	KHDN của ACB đã đến phòng giao dịch để đăng ký đầu số tài khoản định danh theo quy tắc ghi có số 2: Giá trị đầu số được đăng ký tại quầy lần đầu phải bao gồm cả đăng ký đầu số và nội dung số tài khoản định danh. Sau đó KHDN gọi API Đăng ký tài khoản định danh để gửi yêu cầu sang ACB thực hiện đăng ký thêm tài khoản định danh theo quy tắc 2.
Bước 2: Kiểm tra thông tin đăng ký	Nhận yêu cầu đăng ký tài khoản định danh từ KHDN và thực hiện kiểm tra thông tin đăng ký như sau: Kiểm tra tính hợp lệ của đầu số: Tối đa 3 ký tự và thỏa: Ký tự đầu tiên bắt buộc là số 0, hoặc chữ . 2 ký tự sau có thể là chữ (a-z) hoặc số (0-9). Ví dụ: AAA, NTN, 006 Đầu số đã tồn tại trong hệ thống và có trạng thái Đang hoạt động. Đăng ký theo quy tắc ghi có số 2: Giá trị đầu số được đăng ký tại quầy lần đầu phải bao gồm cả đăng ký đầu số và nội dung số tài khoản định danh. Kiểm tra tính hợp lệ của nội dung tài khoản định danh: Tối đa 15 ký tự, bao gồm “chữ” hoặc “số” hoặc “chữ và số” (A-Z,0-9) (không chứa các ký tự đặc biệt). Ví dụ: 012345678912345, Ab3456789 Nội dung tài khoản định danh đăng ký phải không tồn tại trong hệ thống.
Bước 3: Nhận kết quả đăng ký tài khoản định danh	Thực hiện đăng ký tài khoản định danh theo rule của ACB và thông báo kết quả cho khách hàng thông qua API Thông báo kết quả đăng ký tài khoản định danh (API này do khách hàng xây dựng dựa theo chuẩn API do ACB cung cấp).

#Bước

Mô tả

Bước 1: Đăng ký tài khoản định danh

KHDN của ACB đã đến phòng giao dịch để đăng ký đầu số tài khoản định danh theo quy tắc ghi có số 2: Giá trị đầu số được đăng ký tại quầy lần đầu phải bao gồm cả đăng ký đầu số và nội dung số tài khoản định danh.
Sau đó KHDN gọi API Đăng ký tài khoản định danh để gửi yêu cầu sang ACB thực hiện đăng ký thêm tài khoản định danh theo quy tắc 2.

Bước 2: Kiểm tra thông tin đăng ký

Nhận yêu cầu đăng ký tài khoản định danh từ KHDN và thực hiện kiểm tra thông tin đăng ký như sau:

Kiểm tra tính hợp lệ của đầu số:
- Tối đa 3 ký tự và thỏa:
  - Ký tự đầu tiên bắt buộc là số 0, hoặc chữ .
  - 2 ký tự sau có thể là chữ (a-z) hoặc số (0-9).
  - Ví dụ: AAA, NTN, 006
- Đầu số đã tồn tại trong hệ thống và có trạng thái Đang hoạt động.
Đăng ký theo quy tắc ghi có số 2: Giá trị đầu số được đăng ký tại quầy lần đầu phải bao gồm cả đăng ký đầu số và nội dung số tài khoản định danh.
Kiểm tra tính hợp lệ của nội dung tài khoản định danh:
- Tối đa 15 ký tự, bao gồm “chữ” hoặc “số” hoặc “chữ và số” (A-Z,0-9) (không chứa các ký tự đặc biệt). Ví dụ: 012345678912345, Ab3456789
- Nội dung tài khoản định danh đăng ký phải không tồn tại trong hệ thống.

Bước 3: Nhận kết quả đăng ký tài khoản định danh

Thực hiện đăng ký tài khoản định danh theo rule của ACB và thông báo kết quả cho khách hàng thông qua API Thông báo kết quả đăng ký tài khoản định danh (API này do khách hàng xây dựng dựa theo chuẩn API do ACB cung cấp).

2. Quy trình hủy tài khoản định danh

#Bước	Mô tả
Bước 1: Gửi yêu cầu hủy tài khoản định danh	KHDN gọi API hủy tài khoản định danh để gửi yêu cầu sang ACB thực hiện hủy thông tin tài khoản định danh đã đăng ký.
Bước 1.2: Kiểm tra thông tin và cập nhật trạng thái ngừng hoạt động cho tài khoản định danh	Nhận yêu cầu hủy tài khoản định danh từ KHDN và thực hiện kiểm tra thông tin hủy như sau: Kiểm tra tính hợp lệ của đầu số: Tối đa 3 ký tự và thỏa: Ký tự đầu tiên bắt buộc là số 0, hoặc chữ 2 ký tự sau có thể là chữ (a-z) hoặc số (0-9) Ví dụ: AAA, NTN, 006 Đầu số có trạng thái Đang hoạt động. Kiểm tra tính hợp lệ của nội dung tài khoản định danh: Tối đa 15 ký tự, bao gồm “chữ” hoặc “số” hoặc “chữ và số” (A-Z,0-9) (không chứa các ký tự đặc biệt). Ví dụ: 012345678912345 Ab3456789 Nội dung tài khoản định danh đang tồn tại trong hệ thống và có trạng thái đang hoạt động. Thực hiện cập nhật trạng thái ngừng hoạt động cho tài khoản định danh tương ứng theo rule của ACB và thông báo kết quả cho khách hàng.
Bước 1.3: Nhận kết quả hủy tài khoản định danh	Nhận kết quả hủy tài khoản định danh tương ứng từ ACB.

#Bước

Mô tả

Bước 1: Gửi yêu cầu hủy tài khoản định danh

KHDN gọi API hủy tài khoản định danh để gửi yêu cầu sang ACB thực hiện hủy thông tin tài khoản định danh đã đăng ký.

Bước 1.2: Kiểm tra thông tin và cập nhật trạng thái ngừng hoạt động cho tài khoản định danh

Nhận yêu cầu hủy tài khoản định danh từ KHDN và thực hiện kiểm tra thông tin hủy như sau:

Kiểm tra tính hợp lệ của đầu số:
- Tối đa 3 ký tự và thỏa:
  - Ký tự đầu tiên bắt buộc là số 0, hoặc chữ
  - 2 ký tự sau có thể là chữ (a-z) hoặc số (0-9)
  - Ví dụ: AAA, NTN, 006
- Đầu số có trạng thái Đang hoạt động.
Kiểm tra tính hợp lệ của nội dung tài khoản định danh:
- Tối đa 15 ký tự, bao gồm “chữ” hoặc “số” hoặc “chữ và số” (A-Z,0-9) (không chứa các ký tự đặc biệt).
- Ví dụ: 012345678912345
  Ab3456789
- Nội dung tài khoản định danh đang tồn tại trong hệ thống và có trạng thái đang hoạt động.

Thực hiện cập nhật trạng thái ngừng hoạt động cho tài khoản định danh tương ứng theo rule của ACB và thông báo kết quả cho khách hàng.

Bước 1.3: Nhận kết quả hủy tài khoản định danh

Nhận kết quả hủy tài khoản định danh tương ứng từ ACB.

3. Quy trình điều chỉnh thông tin tài khoản định danh

#Bước	Mô tả
Bước 1: Gửi yêu cầu điều chỉnh thông tin tài khoản định danh	KHDN gọi API Điều chỉnh thông tin tài khoản định danh để gửi yêu cầu sang ACB thực hiện điều chỉnh thông tin tài khoản định danh đã đăng ký.
Bước 1.2: Kiểm tra và cập nhật thông tin điều chỉnh tài khoản định danh	Nhận yêu cầu điều chỉnh thông tin tài khoản định danh từ KHDN và thực hiện kiểm tra thông tin cần điều chỉnh như sau: Kiểm tra tính hợp lệ của đầu số: Tối đa 3 ký tự và thỏa: Ký tự đầu tiên bắt buộc là số 0, hoặc chữ 2 ký tự sau có thể là chữ (a-z) hoặc số (0-9) Ví dụ: AAA, NTN, 006 Đầu số có trạng thái Đang hoạt động (VAPrefixStatusCd = ‘ACT’) Kiểm tra tính hợp lệ của nội dung tài khoản định danh: Tối đa 15 ký tự, bao gồm “chữ” hoặc “số” hoặc “chữ và số” (A-Z,0-9) (không chứa các ký tự đặc biệt). Ví dụ: 012345678912345 Ab3456789 Nội dung tài khoản định danh đang tồn tại trong hệ thống và có trạng thái đang hoạt động. Thực hiện điều chỉnh thông tin tài khoản định danh tương ứng cho KHDN theo rule của ACB và thông báo kết quả cho khách hàng.
Bước 1.3: Nhận kết quả điều chỉnh thông tin tài khoản định danh	Nhận kết quả điều chỉnh thông tin tương ứng từ ACB

#Bước

Mô tả

Bước 1: Gửi yêu cầu điều chỉnh thông tin tài khoản định danh

KHDN gọi API Điều chỉnh thông tin tài khoản định danh để gửi yêu cầu sang ACB thực hiện điều chỉnh thông tin tài khoản định danh đã đăng ký.

Bước 1.2: Kiểm tra và cập nhật thông tin điều chỉnh tài khoản định danh

Nhận yêu cầu điều chỉnh thông tin tài khoản định danh từ KHDN và thực hiện kiểm tra thông tin cần điều chỉnh như sau:

Kiểm tra tính hợp lệ của đầu số:
- Tối đa 3 ký tự và thỏa:
  - Ký tự đầu tiên bắt buộc là số 0, hoặc chữ
  - 2 ký tự sau có thể là chữ (a-z) hoặc số (0-9)
  - Ví dụ: AAA, NTN, 006
- Đầu số có trạng thái Đang hoạt động (VAPrefixStatusCd = ‘ACT’)
Kiểm tra tính hợp lệ của nội dung tài khoản định danh:
- Tối đa 15 ký tự, bao gồm “chữ” hoặc “số” hoặc “chữ và số” (A-Z,0-9) (không chứa các ký tự đặc biệt).
- Ví dụ: 012345678912345
  Ab3456789
- Nội dung tài khoản định danh đang tồn tại trong hệ thống và có trạng thái đang hoạt động.

Thực hiện điều chỉnh thông tin tài khoản định danh tương ứng cho KHDN theo rule của ACB và thông báo kết quả cho khách hàng.

Bước 1.3: Nhận kết quả điều chỉnh thông tin tài khoản định danh

Nhận kết quả điều chỉnh thông tin tương ứng từ ACB

4. Quy trình truy vấn thông tin tài khoản định danh

Để truy vấn thông tin tài khoản định danh qua API, khách hàng có thể gọi API Truy vấn thông tin tài khoản định danh.

Errors list

#	HTTP Status Code	Response Code	Response Error Code	Description English
1	200	200	00000000	Success
2	202	400	30020400	Bad request
3	202	500	30020500	Something went wrong
4	401	401	42020182	Invalid token
5	401	401	42020186	Missing token

Kịch bản kiểm thử

Tải tài liệu

1. Tạo Tài khoản định danh

STT	Tính năng	Mô tả tình huống	Điều kiện	Kết quả mong đợi
1	Tạo tài khoản định danh thành công	Sử dụng API đăng ký tài khoản định danh Sử dụng API truy vấn thông tin tài khoản định danh – truy vấn trạng thái tài khoản ACT	Đúng prefix_code Virtual account < hoặc = 15 ký tự	Mã lỗi: 200-0000000 Success
2	Tạo tài khoản định danh không thành công	Sử dụng API đăng ký tài khoản định danh Sử dụng API truy vấn thông tin tài khoản định danh	Sai thông tin prefix_code	Không thấy tài khoản tồn tại
3	Tạo tài khoản định danh không thành công	Sử dụng API đăng ký tài khoản định danh	virtual_account lớn hơn 15 ký tự/ virtual_account có chưa ký tự đặc biệt @#...	Mã lỗi: 202 – 30020400 Bad request
4	Tạo tài khoản định danh không thành công	Sử dụng API đăng ký tài khoản định danh	Token hết hạn	Mã lỗi: 401 - 42020182 Invalid token
5	Tạo tài khoản định danh không thành công	Sử dụng API đăng ký tài khoản định danh	Không có token	Mã 401 – 42020186 Missing token

2. Hủy Tài khoản định danh

STT	Tính năng	Mô tả tình huống	Điều kiện	Kết quả mong đợi
1	Hủy tài khoản định danh thành công	Sử dụng API hủy tài khoản định danh Sử dụng API truy vấn thông tin tài khoản định danh – truy vấn trạng thái tài khoản IACT	Đúng prefix_code Đúng virtual_account	Mã lỗi: 200-0000000 Success
2	Hủy tài khoản định danh không thành công	Sử dụng API hủy tài khoản định danh	Đúng prefix_code Sai virtual_account	Mã lỗi: 202 – 30020500 Something went wrong
3	Hủy tài khoản định danh không thành công	Sử dụng API hủy tài khoản định danh	Thiếu trường thông tin	Mã lỗi 202 – 30020400 Bad request
4	Hủy tài khoản định danh không thành công	Sử dụng API hủy tài khoản định danh	Token hết hạn	Mã lỗi: 401 – 42020182 Invalid token
5	Hủy tài khoản định danh không thành công	Sử dụng API hủy tài khoản định danh	Không có token	Mã 401 – 42020186 Missing token

3. Điều chỉnh thông tin Tài khoản định danh (chỉ áp dụng đối với beneficiary_name_rule = 1)

STT	Tính năng	Mô tả tình huống	Điều kiện	Kết quả mong đợi
1	Điều chỉnh thông tin tài khoản định danh thành công	Sử dụng API điều chỉnh thông tin tài khoản định danh	Đúng prefix_code Đúng virtual_account Đúng virtual_account_explain (nhỏ hơn hoặc bằng 60 ký tự; A-Z, 0-9)	Mã lỗi: 200-0000000 Success
2	Điều chỉnh thông tin tài khoản định danh không thành công	Sử dụng API điều chỉnh thông tin tài khoản định danh	Sai prefix_code Đúng virtual_account Đúng virtual_account_explain (nhỏ hơn hoặc bằng 60 ký tự; A-Z, 0-9)	Mã lỗi: 202 – 30020500 Something went wrong
3	Điều chỉnh thông tin tài khoản định danh không thành công	Sử dụng API điều chỉnh thông tin tài khoản định danh	Đúng prefix_code Đúng virtual_account Sai virtual_account_explain (lớn hơn hoặc bằng 60 ký tự; có ký tự đặc biệt)	Mã lỗi 202 – 30020400 Bad request
4	Điều chỉnh thông tin tài khoản định danh không thành công	Sử dụng API điều chỉnh thông tin tài khoản định danh	Token hết hạn	Mã lỗi: 401 – 42020182 Invalid token
5	Điều chỉnh thông tin tài khoản định danh không thành công	Sử dụng API điều chỉnh thông tin tài khoản định danh	Không có token	Mã 401 – 42020186 Missing token

4. Truy vấn thông tin Tài khoản định danh

STT	Tính năng	Mô tả tình huống	Điều kiện	Kết quả mong đợi
1	Truy vấn thông tin tài khoản định danh thành công	Sử dụng API truy vấn thông tin tài khoản định danh Truy vấn danh sách tài khoản định danh	Đúng prefix_code	Mã lỗi: 200-0000000 Success
2	Truy vấn thông tin tài khoản định danh thành công	Sử dụng API truy vấn thông tin tài khoản định danh Thông tin tài khoản định danh	Đúng prefix_code Đúng virtual_account	Mã lỗi: 200-0000000 Success
3	Truy vấn thông tin tài khoản định danh thành công	Sử dụng API truy vấn thông tin tài khoản định danh Lấy danh sách theo page và size	Đúng prefix_code Page: 0 Size: nhỏ hơn hoặc bằng 1000	Mã lỗi: 200-0000000 Success
4	Truy vấn thông tin tài khoản định danh không thành công	Sử dụng API truy vấn thông tin tài khoản định danh	Đúng prefix_code Page khác số 0 Size: nhỏ hơn hoặc bằng 1000	Mã lỗi: 200-0000000 Success Không có dữ liệu
5	Truy vấn thông tin tài khoản định danh không thành công	Sử dụng API truy vấn thông tin tài khoản định danh	Đúng prefix_code Page: 0 Size: lớn hơn 1000	Mã lỗi 202 – 30020400 Bad request
6	Truy vấn thông tin tài khoản định danh không thành công	Sử dụng API truy vấn thông tin tài khoản định danh	Sai prefix_code	Mã lỗi: 202 – 30020500 Something went wrong
7	Truy vấn thông tin tài khoản định danh không thành công	Sử dụng API truy vấn thông tin tài khoản định danh	Token hết hạn	Mã lỗi: 401 – 42020182 Invalid token
8	Truy vấn thông tin tài khoản định danh không thành công	Sử dụng API truy vấn thông tin tài khoản định danh	Không có token	Mã 401 – 42020186 Missing token

key mapping

virtual-account

Mô tả

Tài Khoản Định Danh là một giải pháp công nghệ số giúp Doanh nghiệp quản lý các khoản phải thu, trong đó có sự liên kết giữa một Tài Khoản thanh toán chính của Doanh nghiệp với tập hợp các Tài Khoản Định Danh.

API Order

virtual-account-create-batch|virtual-account-notification|virtual-account-put-prefix|virtual-account-delete-prefix|virtual-account-get-prefix