# Liên kết tài khoản ngân hàng

Kết nối tài khoản ngân hàng nhận tiền của khách (MB Bank, BIDV, ACB hoặc qua Pay2S) để Hạ Tầng thấy từng giao dịch, và khôi phục giao dịch bị sót bằng sao kê.

Hạ Tầng biết khách đã trả tiền bằng cách đọc các giao dịch tiền vào của chính tài khoản ngân hàng của bạn. Bạn chỉ cần liên kết tài khoản một lần; từ đó mọi giao dịch hiện ở **Thanh toán → Giao dịch**, và giao dịch mang mã của một thanh toán sẽ đánh dấu thanh toán đó đã trả. Hạ Tầng chỉ đọc tài khoản: không bao giờ chuyển được tiền ra khỏi tài khoản.

Liên kết cần quyền **Quản lý** trong module Thanh toán. Liên kết ở đúng môi trường bạn đang làm việc: ngân hàng giả lập ở **Thử nghiệm**, ngân hàng thật ở **Chính thức** (xem [Hạ Tầng Payments hoạt động thế nào](https://hatang.dev/vi/help/payments/payments-overview)).

## Trước khi bắt đầu

- Số tài khoản và tên chủ tài khoản **đúng như ngân hàng ghi nhận**.
- Với một số ngân hàng: số CCCD của chủ tài khoản cá nhân hoặc mã số thuế của tài khoản doanh nghiệp.
- **Chủ tài khoản, hoặc người được uỷ quyền**, có mặt lúc liên kết: tuỳ ngân hàng, người đó nhận mã qua SMS, đồng ý trên trang của ngân hàng, hoặc đăng ký dịch vụ tại ngân hàng.

## Liên kết tài khoản

1. Mở **Thanh toán → Cài đặt thanh toán**, tab **Tài khoản ngân hàng**, và bấm **Thêm tài khoản ngân hàng**.
2. Chọn ngân hàng của bạn. Mỗi ngân hàng liên kết theo cách riêng, và biểu mẫu thay đổi theo ngân hàng.
3. Điền biểu mẫu, tích ô đồng ý nếu có, rồi bấm **Gửi mã** hoặc **Liên kết**.
4. Hoàn tất bước với ngân hàng như mô tả bên dưới.

![Thêm tài khoản ngân hàng ở môi trường thử nghiệm: ngân hàng giả lập và biểu mẫu](https://hatang.dev/help/img/vi/payments/add-bank-account.webp)

| Ngân hàng | Cách liên kết | Cách Hạ Tầng biết có giao dịch |
|---|---|---|
| **MB Bank** | MB đối chiếu tên và số giấy tờ chủ tài khoản, rồi nhắn mã tới số điện thoại đăng ký tại MB. Nhập mã ở **Nhập mã từ ngân hàng** và bấm **Liên kết tài khoản** | Thông báo số dư theo thời gian thực |
| **BIDV** | Đăng ký dịch vụ thông báo biến động số dư cho tài khoản tại BIDV trước. Sau đó thêm tài khoản trong Hạ Tầng. Tài khoản hiện **Chờ ngân hàng** cho tới khi BIDV gửi tin đầu tiên, lúc đó tài khoản được kích hoạt | Thông báo số dư theo thời gian thực |
| **ACB** | Sau khi gửi biểu mẫu, chủ tài khoản được chuyển tới trang của ACB để đồng ý. Quay lại Hạ Tầng là tài khoản đã hoạt động. Sự đồng ý có hiệu lực tối đa 180 ngày | Lịch sử tài khoản ACB, đọc mỗi 10 phút |
| **Pay2S** | Liên kết tài khoản trên Pay2S trước, rồi tạo Hook trỏ về Hạ Tầng và dán token của Hook (xem bên dưới) | Pay2S đẩy về theo thời gian thực |
| **Ngân hàng giả lập** (chỉ môi trường thử nghiệm) | Chọn ngân hàng bất kỳ, có thể nhập số tài khoản của bạn. Mã xác nhận luôn là `000000` | Giao dịch do bạn giả lập bằng nút bấm |

Nhập sai mã 5 lần thì mã hết hiệu lực và bạn phải liên kết lại từ đầu.

### Pay2S từng bước

Pay2S đọc tài khoản ở Vietcombank, VietinBank, Techcombank, BIDV, ACB, MB và TPBank và chuyển từng giao dịch về Hạ Tầng.

1. Trong Hạ Tầng, chọn **Pay2S**. Biểu mẫu hiện **Endpoint để khai báo Hook trên Pay2S**; sao chép endpoint này.
2. Trên my.pay2s.vn: liên kết tài khoản ngân hàng, rồi vào **Webhooks → Thêm webhook**. Chọn tài khoản, sự kiện "Tất cả" hoặc "Nhận tiền", và dán endpoint.
3. Bấm biểu tượng chìa khoá ở cột **Token** và sao chép token. Đó là chuỗi dài, không phải số tài khoản ở tiêu đề hộp thoại.
4. Quay lại Hạ Tầng, chọn **Ngân hàng**, nhập **Số tài khoản** đúng như Pay2S ghi, tên chủ tài khoản, dán **Token webhook Pay2S** và bấm **Liên kết**.
5. Tài khoản chờ Pay2S gửi giao dịch đầu tiên rồi chuyển sang hoạt động. Muốn kích hoạt ngay, hãy chuyển một khoản nhỏ vào tài khoản.

## Trạng thái tài khoản

| Trạng thái | Ý nghĩa | Bạn cần làm gì |
|---|---|---|
| **Chờ OTP** | Đang chờ mã, chờ chủ tài khoản đồng ý, hoặc chờ tin đầu tiên từ ngân hàng | Hoàn tất bước với ngân hàng |
| **Đang hoạt động** | Giao dịch đang về | Không cần làm gì |
| **Cần kết nối lại** | Ngân hàng yêu cầu liên kết lại, ví dụ khi sự đồng ý với ACB đã hết hạn | Liên kết lại tài khoản |
| **Lỗi** | Ngân hàng báo có vấn đề với liên kết | Hỏi ngân hàng, rồi liên kết lại |
| **Đã thu hồi** | Đã gỡ liên kết | Không cần làm gì |

Mỗi tài khoản hiện thời điểm liên kết và **giao dịch gần nhất**. Nếu khách nói đã chuyển mà hàng giờ không thấy gì, hãy xem ngày này trước.

## Khớp lệnh và thông báo

Dưới mỗi tài khoản, mở **Khớp lệnh và thông báo**:

![Tài khoản đã liên kết với phần cài đặt khớp lệnh đang mở](https://hatang.dev/help/img/vi/payments/bank-accounts.webp)

| Cài đặt | Tác dụng |
|---|---|
| **Tiền tố mã thanh toán (luồng đơn hàng)** | 2 tới 5 chữ in hoa đứng đầu mọi mã chuyển khoản Hạ Tầng tạo, mặc định là `HT`. Mã có dạng `HTBF7RDGVQ` |
| **Mã đơn riêng của bạn (luồng chỉ webhook)** | Định dạng mã đơn của cửa hàng, ví dụ tiền tố `DH`, từ 6 tới 6 **chữ số**. Hạ Tầng sẽ tìm mã này trong mọi giao dịch, kể cả khi không có thanh toán. Xem [Giao dịch và cách khớp lệnh](https://hatang.dev/vi/help/payments/transactions-and-matching) |
| **Gửi transaction.received cho** | Giao dịch nào được báo tới hệ thống của bạn: chỉ tiền vào, hoặc **tiền vào và ra**; có thể chọn **chỉ khi tìm thấy mã** |
| **Số tiền tối thiểu (VND)** | Giao dịch nhỏ hơn số này không được báo |

Các cài đặt này chỉ thay đổi những gì được báo tới hệ thống của bạn. Thanh toán thì luôn được khớp.

## Khôi phục giao dịch ngân hàng bỏ sót

Đôi khi ngân hàng không báo một giao dịch. Ở **Nhập sao kê ngân hàng**, tải lên file CSV lập từ sao kê của ngân hàng, hoặc dán nội dung, rồi bấm **Nhập**. Các cột gồm `reference`, `booked_at`, `direction`, `amount`, `description`, và nếu có thì `counterparty_account`, `counterparty_name`.

Giao dịch Hạ Tầng đã có sẽ được bỏ qua, nên nhập trùng khoảng thời gian vẫn an toàn. Giao dịch nhập vào được khớp y như giao dịch ngân hàng báo: giao dịch mang mã của một thanh toán sẽ đánh dấu thanh toán đó đã trả.

## Gỡ liên kết

Bấm **Gỡ liên kết** trên tài khoản. MB Bank xác nhận bằng mã như lúc liên kết; các ngân hàng khác được gỡ ngay. Gỡ tài khoản ACB cũng thu hồi sự đồng ý ở ACB. Với BIDV và Pay2S, hãy tắt thêm dịch vụ thông báo hoặc Hook ở phía họ.

Các thanh toán đã có vẫn được giữ. Không tạo được thanh toán mới vào tài khoản đó nữa.

## Xử lý sự cố

| Hiện tượng | Nguyên nhân | Cách xử lý |
|---|---|---|
| Ngân hàng từ chối liên kết | Tên hoặc số giấy tờ không khớp với ngân hàng, hoặc tài khoản đã liên kết với doanh nghiệp khác | Chép tên đúng như trên sao kê ngân hàng (thường là chữ in hoa không dấu) |
| Không nhận được mã SMS của MB | Số điện thoại đăng ký tại MB không phải số bạn nghĩ | Hỏi chủ tài khoản; mã gửi tới số MB đang lưu |
| BIDV hoặc Pay2S mãi **Chờ OTP** | Ngân hàng hoặc Pay2S chưa gửi tin đầu tiên | Kiểm tra dịch vụ hoặc Hook ở phía họ, rồi chuyển một khoản nhỏ vào tài khoản |
| Có giao dịch trong app ngân hàng nhưng không có trong Hạ Tầng | Ngân hàng không báo về | Nhập sao kê của ngày đó |
| Không thấy ngân hàng thật trong danh sách | Bạn đang ở môi trường **Thử nghiệm** | Chuyển sang **Chính thức** bằng thanh ở đầu trang |

Lập trình viên có thể liên kết và cấu hình tài khoản qua API; xem [Kết nối ngân hàng ở trang dành cho lập trình viên](https://hatang.dev/vi/docs/guides/payments/bank-connections).