Developer
Tài liệu / Partner API & BankHub
Thử API trong Playground ↗Trải nghiệm BankHub Hosted Link ↗

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

✧ Mở bằng AI

Sao chép tài liệu, mở AI rồi dán vào cuộc trò chuyện.

ChatGPTClaudePerplexityGrok
≡ Xem Markdown

Môi trường: phần hướng dẫn phía dưới áp dụng cho Production (api-partner.pay2s.vn). UAT (api-partner-uat.pay2s.vn) có phản hồi riêng; các mẫu đã gọi UAT ngày 11/10/2026 nằm ở mục “Request và response đối chiếu” cuối trang. API trực tiếp UAT hỗ trợ ACB/openapi và OTP thử 123456; không dùng OTP này ở Production.

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

{
  "type": "openapi",
  "bankShortName": "BIDV",
  "accountNumber": "0123456789",
  "cccd": "012345678901",
  "merchantId": "VYTEOO1",
  "accName": "NGUYEN VAN A",
  "accMobile": "0900000000",
  "accEmail": "[email protected]"
}

1.2 OpenAPI – ACB

Cá nhân

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

Doanh nghiệp

{
  "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

{
  "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ử dụng cho các ngân hàng Vietcombank, Vietinbank)

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

1.5 Pay2S-api – Doanh nghiệp (Internet Banking qua RPA sử dụng cho các ngân hàng Vietcombank, Vietinbank, Techcombank)

{
  "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

  1. 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.
  2. 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.
  3. 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)

{
  "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.

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

2.3 Pay2S‑api (Personal)

{
  "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:

{
  "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:

{
  "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:

{
  "status": true,
  "message": "Xóa ngân hàng.",
  "OTP": 1,
  "type": "SMS"
}

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

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

{ "otp": "160241" }

Phản hồi mẫu:

{ "status": true, "message": "Xóa ngân hàng thà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:

{
  "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)

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": "[email protected]"
 }'

Xác nhận OTP BIDV

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

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

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

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

Xoá ngân hàng

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

Xác nhận xoá (OTP)

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:

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.

Request và response đối chiếu ngày 11/10/2026

Các mẫu dưới đây giữ cấu trúc trường và kiểu dữ liệu. Khóa, chữ ký, URL phiên đã được thay bằng placeholder; danh sách chỉ giữ tối đa hai phần tử và dữ liệu ảnh/PDF/XML dài được rút gọn. Không sao chép placeholder để gọi API thật.

Danh sách ngân hàng đã liên kết

Thử API trong Playground ↗Trải nghiệm BankHub Hosted Link ↗

Đã gọi API demo/UAT.

GET /v1/banks

Tham số path/query (không gửi JSON body):

{}

HTTP 200. Response:

{
  "status": true,
  "message": [
    {
      "id": 19,
      "name": "NGUYEN VAN DEMO",
      "accountNumber": "P2SUAT7A52E214CB4A2F227852",
      "vaNumber": "",
      "status": 1,
      "shortBankName": "ACB",
      "bankName": "Ngân hàng Á Châu (ACB)",
      "customer_reference": "DEV_5425ec25f88b87b7a38fa5a2a1111495_179165667730313cc72",
      "simulated": true,
      "demo_user_bank_id": 5179
    },
    {
      "id": 18,
      "name": "NGUYEN DEV PAY2S",
      "accountNumber": "P2SUATABF651203269273FDD39",
      "vaNumber": "",
      "status": 1,
      "shortBankName": "ACB",
      "bankName": "Ngân hàng Á Châu (ACB)",
      "customer_reference": "DEV_97ba780a4affdc6c936c98bbeabd2a52_1791656524283169d3f",
      "simulated": true,
      "demo_user_bank_id": 5178
    }
  ]
}

Thống kê ngân hàng

Thử API trong Playground ↗Trải nghiệm BankHub Hosted Link ↗

Đã gọi API demo/UAT.

GET /v1/banks/summary

Tham số path/query (không gửi JSON body):

{}

HTTP 200. Response:

{
  "success": true,
  "data": {
    "total": 6,
    "active": 6,
    "inactive": 0,
    "simulated": true
  }
}

Thêm ngân hàng bằng API

Thử API trong Playground ↗Trải nghiệm BankHub Hosted Link ↗

Đã gọi API demo/UAT.

POST /v1/banks

Body:

{
  "type": "openapi",
  "bankShortName": "ACB",
  "accountNumber": "1791659973755786",
  "accName": "TAI KHOAN DEMO",
  "accMobile": "0900000000",
  "customer_reference": "DEV_d33eb1382b55f87313b6840bff80f880_179165997375564ac8e"
}

HTTP 200. Response:

{
  "status": true,
  "message": "Gửi OTP giả lập thành công.",
  "OTP": 1,
  "type": "openapi",
  "data": {
    "session_id": "4a4a0832eb84405d5a643be0a961803c",
    "status": "awaiting_otp",
    "environment": "uat",
    "bank": "ACB",
    "purpose": "LINK_BANK_ACCOUNT",
    "unlink_mode": "bank",
    "parent_origin": "",
    "partner_name": "Demo UAT",
    "bank_choices": [
      {
        "id": "acb_personal",
        "bank_code": "ACB",
        "name": "Ngân hàng Á Châu",
        "account_type": "personal",
        "account_type_label": "Cá nhân",
        "connection_type": "openapi",
        "fields": [
          "account_name",
          "phone"
        ]
      },
      {
        "id": "acb_business",
        "bank_code": "ACB",
        "name": "Ngân hàng Á Châu",
        "account_type": "business",
        "account_type_label": "Doanh nghiệp",
        "connection_type": "openapi",
        "fields": [
          "account_name",
          "phone"
        ]
      }
    ],
    "profile_id": "acb_personal",
    "branding": {
      "partnerName": "Demo UAT",
      "primaryColor": "#09834d",
      "partnerLogo": "",
      "supportUrl": "",
      "privacyUrl": ""
    },
    "expires_at": "2026-10-10 19:34:34Z",
    "error": null,
    "account_masked": "••••5786",
    "return_url": ""
  }
}

Xác nhận OTP ngân hàng

Thử API trong Playground ↗Trải nghiệm BankHub Hosted Link ↗

Đã gọi API demo/UAT.

POST /v1/banks/confirm-otp

Body:

{
  "type": "openapi",
  "bankShortName": "ACB",
  "accountNumber": "1791659973755786",
  "otp": "123456"
}

HTTP 200. Response:

{
  "status": true,
  "message": "Liên kết giả lập thành công.",
  "data": {
    "session_id": "4a4a0832eb84405d5a643be0a961803c",
    "status": "connected",
    "environment": "uat",
    "bank": "ACB",
    "purpose": "LINK_BANK_ACCOUNT",
    "unlink_mode": "bank",
    "parent_origin": "",
    "partner_name": "Demo UAT",
    "bank_choices": [
      {
        "id": "acb_personal",
        "bank_code": "ACB",
        "name": "Ngân hàng Á Châu",
        "account_type": "personal",
        "account_type_label": "Cá nhân",
        "connection_type": "openapi",
        "fields": [
          "account_name",
          "phone"
        ]
      },
      {
        "id": "acb_business",
        "bank_code": "ACB",
        "name": "Ngân hàng Á Châu",
        "account_type": "business",
        "account_type_label": "Doanh nghiệp",
        "connection_type": "openapi",
        "fields": [
          "account_name",
          "phone"
        ]
      }
    ],
    "profile_id": "acb_personal",
    "branding": {
      "partnerName": "Demo UAT",
      "primaryColor": "#09834d",
      "partnerLogo": "",
      "supportUrl": "",
      "privacyUrl": ""
    },
    "expires_at": "2026-10-10 19:34:34Z",
    "error": null,
    "account_masked": "••••5786",
    "return_url": ""
  }
}

Bật / tắt ngân hàng

Thử API trong Playground ↗Trải nghiệm BankHub Hosted Link ↗

Đã gọi API demo/UAT.

PATCH /v1/banks/{id}/status

Body:

{}

HTTP 200. Response:

{
  "status": true,
  "message": "Đã đổi trạng thái giả lập.",
  "data": {
    "id": 21,
    "status": 0
  }
}

Yêu cầu xóa ngân hàng

Thử API trong Playground ↗Trải nghiệm BankHub Hosted Link ↗

Đã gọi API demo/UAT.

DELETE /v1/banks/{id}

Tham số path/query (không gửi JSON body):

{}

HTTP 200. Response:

{
  "status": true,
  "OTP": 1,
  "message": "Nhập OTP giả lập 123456 để hủy liên kết."
}

OTP xác nhận xóa ngân hàng

Thử API trong Playground ↗Trải nghiệm BankHub Hosted Link ↗

Đã gọi API demo/UAT.

POST /v1/banks/{id}/delete-confirm

Body:

{
  "otp": "123456"
}

HTTP 200. Response:

{
  "status": true,
  "message": "Đã hủy liên kết giả lập."
}
Tìm trong 57 trang tài liệu · Esc để đóng