Quản lý tài khoản ngân hàng

Các API dùng để liên kết, xác nhận OTP, xem danh sách, bật/tắt và xoá tài khoản ngân hàng.

Base URL: https://api-partner.pay2s.vn

Các API yêu cầu Bearer Token lấy từ /v1/auth/authorize. Xem hướng dẫn xác thực.

Thay dữ liệu minh hoạ bằng thông tin tài khoản cần liên kết. Giữ số tài khoản, số điện thoại, CCCD/MST và OTP ở kiểu chuỗi để bảo toàn số 0 ở đầu.

🔐 Header chung

Authorization: Bearer <token>
Content-Type: application/json

Gửi Content-Type: application/json với các request có body JSON.

1) Thêm ngân hàng

POST https://api-partner.pay2s.vn/v1/banks

Chọn mẫu theo phương thức kết nối: OpenAPI (type: "openapi") hoặc Internet Banking qua RPA (type: "personal" cho cá nhân, type: "business" cho doanh nghiệp).

Tham số trong request thêm tài khoản

Trường	Kiểu	Cách sử dụng trong các mẫu
`type`	string	Phương thức kết nối: `openapi`, `personal` hoặc `business`.
`bankShortName`	string	Mã ngân hàng, ví dụ `BIDV`, `ACB`, `MBB`, `VCB`, `VTB`.
`accountNumber`	string	Số tài khoản cần liên kết.
`bank_type`	string	Mẫu ACB doanh nghiệp gửi `business`; mẫu cá nhân không gửi trường này.
`accName`	string	Tên chủ tài khoản trong mẫu OpenAPI.
`accMobile`	string	Số điện thoại đăng ký với ngân hàng trong mẫu OpenAPI.
`accEmail`	string	Email chủ tài khoản trong mẫu BIDV OpenAPI.
`cccd`	string	CCCD trong mẫu BIDV/MBBank cá nhân.
`merchantId`	string	Bắt buộc với BIDV OpenAPI; mã dùng để tạo tài khoản ảo (VA).
`username`	string	Tên đăng nhập Internet Banking với RPA, hoặc ACB OneBiz với ACB doanh nghiệp.
`password`	string	Mật khẩu Internet Banking với RPA.

Bảng mô tả các trường của mẫu request, chưa phải danh sách validation đầy đủ. Quy định bắt buộc/tuỳ chọn và giới hạn độ dài theo từng ngân hàng cần được đối chiếu với backend.

1.1 OpenAPI – BIDV

json

{
  "type": "openapi",
  "bankShortName": "BIDV",
  "accountNumber": "0123456789",
  "cccd": "012345678901",
  "merchantId": "VYTEOO1",
  "accName": "NGUYEN VAN A",
  "accMobile": "0900000000",
  "accEmail": "nguyenvana@example.com"
}

merchantId: yêu cầu với BIDV (được dùng khi sinh VA: tiền tố 963869 + mã).
Hệ thống sẽ gửi OTP → cần gọi bước Xác nhận OTP bên dưới.

1.2 OpenAPI – ACB

Cá nhân

json

{
  "type": "openapi",
  "bankShortName": "ACB",
  "accountNumber": "19354957",
  "accName": "NGUYEN VAN A",
  "accMobile": "0900000000"
}

Doanh nghiệp

json

{
  "type": "openapi",
  "bank_type": "business",
  "bankShortName": "ACB",
  "accountNumber": "99979986",
  "accName": "CONG TY DEMO",
  "accMobile": "0900000000",
  "username": "acb_onebiz_user"
}

Với ACB doanh nghiệp, gửi bank_type: "business" và username của ACB OneBiz. Mẫu cá nhân ở trên không gửi bank_type; giá trị mặc định của trường này cần được xác nhận với backend.

1.3 OpenAPI – MBBank

Cá nhân

json

{
  "type": "openapi",
  "bankShortName": "MBB",
  "accountNumber": "737478888",
  "accName": "NGUYEN VAN A",
  "accMobile": "0900000000",
  "cccd": "012345678901"
}

Với MBBank, mẫu trên dành cho cá nhân. Trường cccd dùng CCCD của chủ tài khoản; với hộ kinh doanh/doanh nghiệp, cần xác nhận yêu cầu MST và các trường bổ sung trước khi dùng mẫu này.

1.4 Pay2S-api – Cá nhân (Internet Banking qua RPA sử dụng cho các ngân hàng Vietcombank, Vietinbank)

json

{
  "type": "personal",
  "bankShortName": "VCB",
  "accountNumber": "0123456789",
  "username": "internet_banking_user",
  "password": "secret"
}

1.5 Pay2S-api – Doanh nghiệp (Internet Banking qua RPA sử dụng cho các ngân hàng Vietcombank, Vietinbank, Techcombank)

json

{
  "type": "business",
  "bankShortName": "VTB",
  "accountNumber": "0123456789",
  "username": "internet_banking_user",
  "password": "secret"
}

Với RPA, dùng tên đăng nhập và mật khẩu của đúng ngân hàng đã chọn.

Xử lý sau khi gửi yêu cầu liên kết

Nếu phản hồi có OTP = 1, tiếp tục bước 2) Xác nhận OTP cho tài khoản vừa gửi.
Sau khi xác nhận thành công, gọi GET /v1/banks để kiểm tra tài khoản và trạng thái liên kết.
Nếu phản hồi báo lỗi, xử lý theo nội dung lỗi trước khi tiếp tục.

Không dùng riêng thông báo “Hợp lệ” hoặc việc thiếu trường OTP để kết luận tài khoản đã được kích hoạt. Xem phạm vi xác minh về response và xử lý lỗi OTP.

2) Xác nhận OTP (Confirm OTP)

POST https://api-partner.pay2s.vn/v1/banks/confirm-otp

Gửi OTP của đúng yêu cầu liên kết. Giữ nguyên type, bankShortName, accountNumber so với bước thêm tài khoản; với BIDV giữ nguyên merchantId, với RPA cá nhân giữ nguyên username và password.

2.1 BIDV (OpenAPI)

json

{
  "type": "openapi",
  "bankShortName": "BIDV",
  "accountNumber": "0123456789",
  "merchantId": "VYTEOO1",
  "otp": "016311"
}

2.2 ACB hoặc MBBank (OpenAPI)

Ví dụ dưới đây dùng ACB. Với MBBank, thay bankShortName bằng MBB và dùng số tài khoản MBBank đã gửi ở bước thêm.

json

{
  "type": "openapi",
  "bankShortName": "ACB",
  "accountNumber": "19354957",
  "otp": "767523"
}

2.3 Pay2S‑api (Personal)

json

{
  "type": "personal",
  "bankShortName": "VCB",
  "accountNumber": "0123456789",
  "username": "internet_banking_user",
  "password": "secret",
  "otp": "767523"
}

Nếu vẫn nhận được yêu cầu OTP hoặc lỗi xác nhận, chưa đánh dấu tài khoản là đã liên kết. Kiểm tra mã và thông báo trả về; thời hạn OTP, số lần thử và cách gửi lại cần được xác nhận theo từng ngân hàng.

3) Danh sách tài khoản ngân hàng

GET https://api-partner.pay2s.vn/v1/banks

Không gửi body. Lấy id của tài khoản trong danh sách để dùng cho các endpoint bật/tắt, xoá và xác nhận xoá; {id} không phải số tài khoản.

Phản hồi mẫu:

json

{
  "status": true,
  "message": [
    {
      "id": 410,
      "username": "0123456789",
      "name": "NGUYEN VAN A",
      "accountNumber": "0123456789",
      "vaNumber": "963869789",
      "balance": 1000000,
      "created_at": "2025-10-14 10:42:11",
      "status": 1,
      "statusText": "Đang hoạt động",
      "bankName": "Asia Commercial Bank"
    }
  ]
}

Trong mẫu trên, status ở cấp ngoài là kết quả request; message là mảng tài khoản. message[].status là trạng thái từng tài khoản, với 1 tương ứng “Đang hoạt động” trong ví dụ. Các giá trị trạng thái khác cần được xác nhận với backend.

Với BIDV OpenAPI, vaNumber được mô tả theo dạng 963869<code>. Khi sử dụng VA, lấy giá trị API trả về thay vì tự ghép từ mẫu.

4) Bật / Tắt trạng thái ngân hàng

PATCH https://api-partner.pay2s.vn/v1/banks/{id}/status

Request bật/tắt không gửi body theo Postman Collection (Toggle Status). Dùng id lấy từ danh sách tài khoản. Sau khi gọi, kiểm tra newStatus và đọc lại danh sách để xác nhận trạng thái; không tự động gọi lặp lại khi chưa biết kết quả lần trước.

Phản hồi mẫu:

json

{
  "status": true,
  "message": "Cập nhật trạng thái ngân hàng thành công.",
  "newStatus": 1
}

Chỉ bật được khi liên kết đã thành công. newStatus là trạng thái sau khi cập nhật; bảng giá trị đầy đủ và hành vi khi gọi lặp lại cần được xác nhận với backend.

5) Xoá ngân hàng

DELETE https://api-partner.pay2s.vn/v1/banks/{id}

Không gửi body. Nếu phản hồi có OTP = 1, yêu cầu xoá đang chờ xác nhận: tiếp tục bước 5.1 với cùng {id}. Không coi status: true trong phản hồi này là đã xoá xong.

Phản hồi mẫu:

json

{
  "status": true,
  "message": "Xóa ngân hàng.",
  "OTP": 1,
  "type": "SMS"
}

5.1 Xác nhận xoá (OTP)

POST https://api-partner.pay2s.vn/v1/banks/{id}/delete-confirm

json

{ "otp": "160241" }

Phản hồi mẫu:

json

{ "status": true, "message": "Xóa ngân hàng thành công" }

6) Thống kê tóm tắt (Summary)

GET https://api-partner.pay2s.vn/v1/banks/summary

Trả về tổng quan số lượng ngân hàng đã liên kết theo từng bankName/shortBankName, kèm tổng số.

Ví dụ phản hồi rút gọn:

json

{
  "status": true,
  "bankCounts": [
    { "bankName": "Vietcombank", "shortBankName": "VCB", "count": 2 },
    { "bankName": "BIDV", "shortBankName": "BIDV", "count": 1 }
  ],
  "total": 3
}

🧪 cURL mẫu

Các lệnh dưới đây dùng cú pháp Bash. Thay <token> và dữ liệu mẫu trước khi chạy.

Thêm BIDV (OpenAPI)

bash

curl -X POST https://api-partner.pay2s.vn/v1/banks \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "openapi",
  "bankShortName": "BIDV",
  "accountNumber": "0123456789",
  "cccd": "012345678901",
  "merchantId": "VYTEOO1",
  "accName": "NGUYEN VAN A",
  "accMobile": "0900000000",
  "accEmail": "nguyenvana@example.com"
 }'

Xác nhận OTP BIDV

bash

curl -X POST https://api-partner.pay2s.vn/v1/banks/confirm-otp \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "openapi",
  "bankShortName": "BIDV",
  "accountNumber": "0123456789",
  "merchantId": "VYTEOO1",
  "otp": "016311"
 }'

Danh sách ngân hàng

bash

curl -X GET "https://api-partner.pay2s.vn/v1/banks" \
  -H "Authorization: Bearer <token>"

Bật/Tắt trạng thái

bash

curl -X PATCH "https://api-partner.pay2s.vn/v1/banks/410/status" \
  -H "Authorization: Bearer <token>"

Xoá ngân hàng

bash

curl -X DELETE "https://api-partner.pay2s.vn/v1/banks/410" \
  -H "Authorization: Bearer <token>"

Xác nhận xoá (OTP)

bash

curl -X POST "https://api-partner.pay2s.vn/v1/banks/410/delete-confirm" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "otp": "160241" }'

Phạm vi xác minh và thông tin cần bổ sung

Các request đã được đối chiếu với Postman Collection công khai. Collection không lưu response mẫu và có request “List Bank” khai báo POST kèm body thêm tài khoản; vì vậy chưa thể dùng collection để xác nhận schema response hoặc phương thức lấy danh sách. Các response trên trang là ví dụ từ tài liệu hiện có.

Những chi tiết cần xác nhận với backend trước khi hoàn thiện tích hợp:

Schema response thành công, chờ OTP và lỗi của bước thêm/xác nhận; HTTP status và mã lỗi tương ứng.
Thời hạn OTP, giới hạn số lần thử, cách gửi lại và quy trình OTP cho RPA doanh nghiệp.
Quy tắc bắt buộc/tuỳ chọn, giá trị mặc định của bank_type và validation theo từng ngân hàng; mẫu ACB doanh nghiệp và MBBank chưa có request riêng trong collection.
Schema thực tế của danh sách tài khoản, bảng trạng thái và hành vi bật/tắt khi request được gửi lại.

Khi gặp 401 Unauthorized, kiểm tra Bearer Token và lấy token mới theo hướng dẫn xác thực nếu token đã hết hạn. Với lỗi OTP, dùng thông báo thực tế để hướng dẫn người dùng; tài liệu chưa xác định endpoint gửi lại OTP.

Quản lý tài khoản ngân hàng ​

🔐 Header chung ​

1) Thêm ngân hàng ​

Tham số trong request thêm tài khoản ​

1.1 OpenAPI – BIDV ​

1.2 OpenAPI – ACB ​

Cá nhân ​

Doanh nghiệp ​

1.3 OpenAPI – MBBank ​

Cá nhân ​

1.4 Pay2S-api – Cá nhân (Internet Banking qua RPA sử dụng cho các ngân hàng Vietcombank, Vietinbank) ​

1.5 Pay2S-api – Doanh nghiệp (Internet Banking qua RPA sử dụng cho các ngân hàng Vietcombank, Vietinbank, Techcombank) ​

Xử lý sau khi gửi yêu cầu liên kết ​

2) Xác nhận OTP (Confirm OTP) ​

2.1 BIDV (OpenAPI) ​

2.2 ACB hoặc MBBank (OpenAPI) ​

2.3 Pay2S‑api (Personal) ​

3) Danh sách tài khoản ngân hàng ​

4) Bật / Tắt trạng thái ngân hàng ​

5) Xoá ngân hàng ​

5.1 Xác nhận xoá (OTP) ​

6) Thống kê tóm tắt (Summary) ​

🧪 cURL mẫu ​

Thêm BIDV (OpenAPI) ​

Xác nhận OTP BIDV ​

Danh sách ngân hàng ​

Bật/Tắt trạng thái ​

Xoá ngân hàng ​

Xác nhận xoá (OTP) ​

Phạm vi xác minh và thông tin cần bổ sung ​

Quản lý tài khoản ngân hàng

🔐 Header chung

1) Thêm ngân hàng

Tham số trong request thêm tài khoản

1.1 OpenAPI – BIDV

1.2 OpenAPI – ACB

Cá nhân

Doanh nghiệp

1.3 OpenAPI – MBBank

Cá nhân

1.4 Pay2S-api – Cá nhân (Internet Banking qua RPA sử dụng cho các ngân hàng Vietcombank, Vietinbank)

1.5 Pay2S-api – Doanh nghiệp (Internet Banking qua RPA sử dụng cho các ngân hàng Vietcombank, Vietinbank, Techcombank)

Xử lý sau khi gửi yêu cầu liên kết

2) Xác nhận OTP (Confirm OTP)

2.1 BIDV (OpenAPI)

2.2 ACB hoặc MBBank (OpenAPI)

2.3 Pay2S‑api (Personal)

3) Danh sách tài khoản ngân hàng

4) Bật / Tắt trạng thái ngân hàng

5) Xoá ngân hàng

5.1 Xác nhận xoá (OTP)

6) Thống kê tóm tắt (Summary)

🧪 cURL mẫu

Thêm BIDV (OpenAPI)

Xác nhận OTP BIDV

Danh sách ngân hàng

Bật/Tắt trạng thái

Xoá ngân hàng

Xác nhận xoá (OTP)

Phạm vi xác minh và thông tin cần bổ sung