Pay2S

Appearance

🏦 Bank Subscription / Quản lý ngân hàng (theo Postman Collection) ​

Các API yêu cầu Bearer Token lấy từ /v1/auth/authorize (Basic → Bearer).

🔐 Header chung ​

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

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

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

Có nhiều biến thể theo từng ngân hàng / cơ chế: OpenAPI (BIDV, ACB, …) hoặc Pay2S-api (personal/business).
Dưới đây là các body mẫu đúng theo collection.

1.1 OpenAPI – BIDV ​

json
{
  "type": "openapi",
  "bankShortName": "BIDV",
  "accountNumber": "8810281999",
  "cccd": "068095012120",
  "merchantId": "VYTEOO1",
  "accName": "NGUYEN TRONG VY",
  "accMobile": "0708077478",
  "accEmail": "[email protected]"
}
  • 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 ​

json
{
  "type": "openapi",
  "bankShortName": "ACB",
  "accountNumber": "19354957",
  "accName": "NGUYEN TRONG VY",
  "accMobile": "0902506099"
}

Với ACB, trường bank_type có thể mặc định personal (PERS) hoặc business (ORG) ở tầng core – collection mẫu để tối thiểu như trên.

1.3 Pay2S‑api – Personal (Internet Banking) ​

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

Một số bank personal có thể trả về OTP hoặc Hợp lệ tùy quy trình xác minh.
Nếu trả về OTP, tiếp tục gọi https://api-partner.pay2s.vn/v1/banks/confirm-otp.

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

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

2.1 BIDV (OpenAPI) ​

json
{
  "type": "openapi",
  "bankShortName": "BIDV",
  "accountNumber": "8810281999",
  "merchantId": "VYTEOO1", //Cần phải nhập hậu tố cho VA Number
  "otp": "016311"
}

2.2 ACB hoặc MBBank (OpenAPI) ​

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

2.3 Pay2S‑api (Personal) ​

json
{
  "type": "personal",
  "bankShortName": "BIDV",
  "accountNumber": "8810281999",
  "username": "bidv_user",
  "password": "abc123",
  "otp": "767523"
}

Trả về Hợp lệ → ngân hàng được kích hoạt. Nếu vẫn OTP → kiểm tra lại mã OTP hoặc thời hạn OTP.

3) Danh sách ngân hàng của user ​

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

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"
    }
  ]
}

Lưu ý: với BIDV OpenAPI, vaNumber có thể hiển thị dạng 963869 + <shortCode>.

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

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

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 (không còn trạng thái hide treo OTP).

5) Xoá ngân hàng ​

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

  • Một số ngân hàng OpenAPI (ví dụ MBB/ACB khi chưa active) sẽ trả về yêu cầu OTP xoá.

Phản hồi mẫu:

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

json
{ "otp": "160241" }

Phản hồi mẫu:

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

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

🧪 cURL mẫu ​

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": "8810281999",
  "cccd": "068095012120",
  "merchantId": "VYTEOO1",
  "accName": "NGUYEN TRONG VY",
  "accMobile": "0708077478",
  "accEmail": "[email protected]"
 }'

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": "8810281999",
  "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" }'

Lưu ý

  • Body mẫu ở trên được lấy đúng từ Postman collection (BIDV, ACB, personal).
  • Với BIDV OpenAPI, merchantId là bắt buộc và VA hiển thị dạng 963869<code>.
  • Nếu API trả về OTP = 1, bạn phải thực hiện bước Confirm OTP tương ứng.