API VPBank – API ngân hàng VPBank mới nhất

API VPBank của SePay giúp bạn truy vấn thông tin giao dịch ngân hàng VPBank (Ngân Hàng Việt Nam Thịnh Vượng) qua API. Hỗ trợ danh sách giao dịch VPBank, lấy thông tin chi tiết một giao dịch cụ thể như: Ngày giao dịch, số tiền, mã tham chiếu, số dư tài khoản, nội dung thanh toán.

SePay là đối tác chiến lược của ngân hàng VPBank, cung cấp API chính thức từ ngân hàng với tốc độ gần như thời gian thực.

Các bước thực hiện:

Bước 1: Đăng ký tài khoản SePay tại my.sepay.vn/register, sau đó thêm tài khoản ngân hàng VPBank.

Bước 2: Vào my.sepay.vn -> API Access, tạo API Token. API Token cần được đưa vào header mỗi khi request đến SePay API. Với cấu trúc header:

• Authorization: Bearer API-TOKEN
• Content-Type: application/json

Bước 3: Bạn có thể sử dụng API VPBank như sau:

API VPBank để lấy danh sách giao dịch ngân hàng

GET https://my.sepay.vn/userapi/transactions/list

Bạn có thể lọc theo các tham số sau khi gửi API:

Ví dụ API VPBank:

API lấy tất cả giao dịch gần nhất

Mặc định chỉ hiển thị 5000 giao dịch gần nhất.

• GET https://my.sepay.vn/userapi/transactions/list

HTTP/1.1 200 OK
----
{
    "status": 200,
    "error": null,
    "messages": {
        "success": true
    },
    "transactions": [
        {
            "id": "49682",
            "bank_brand_name": "VPBank",
            "account_number": "0071000888888",
            "transaction_date": "2023-05-05 19:59:48",
            "amount_out": "0.00",
            "amount_in": "18067000.00",
            "accumulated": "1200541768.00",
            "transaction_content": "DUONG THUY ANH chuyen tien...",
            "reference_number": null,
            "code": null,
            "sub_account": null,
            "bank_account_id": "21"
        },
        {
            "id": "49582",
            "bank_brand_name": "VPBank",
            "account_number": "0071000899999",
            "transaction_date": "2023-05-05 17:59:47",
            "amount_out": "0.00",
            "amount_in": "13646000.00",
            "accumulated": "1384635819.00",
            "transaction_content": "DINH NHU TOAN chuyen tien...",
            "reference_number": null,
            "code": null,
            "sub_account": null,
            "bank_account_id": "20"
        },
        {
            "id": "49465",
            "bank_brand_name": "VPBank",
            "account_number": "0071000888888",
            "transaction_date": "2023-05-05 15:59:47",
            "amount_out": "0.00",
            "amount_in": "21782000.00",
            "accumulated": "1182474768.00",
            "transaction_content": "DUONG THUY ANH chuyen tien...",
            "reference_number": null,
            "code": null,
            "sub_account": null,
            "bank_account_id": "21"
        }
    ]
}

API lấy giao dịch sau 08h00 ngày 30/04/2023 và trước 12h00 ngày 02/05/2023.

• GET https://my.sepay.vn/userapi/transactions/list?transaction_date_min=2023-04-30 08:00:00&transaction_date_max=2023-05-02 12:00:00

API  lấy giao dịch từ ID 49050 trở về sau.

• GET https://my.sepay.vn/userapi/transactions/list?since_id=49050

API  lấy 20 giao dịch gần đây của tài khoản ngân hàng số 0071000888888.

• GET https://my.sepay.vn/userapi/transactions/list?account_number=0071000888888&limit=20

API  lọc giao dịch có mã tham chiếu là 171158.050523.060001

• GET https://my.sepay.vn/userapi/transactions/list?reference_number=171158.050523.060001

API  lấy các giao dịch với số tiền chuyển vào là 16,848,000

• GET https://my.sepay.vn/userapi/transactions/list?amount_in=16848000

API VPBank đếm số lượng giao dịch 

GET https://my.sepay.vn/userapi/transactions/count

Đếm số lượng giao dịch. Bạn có thể lọc theo các tham số sau:

Ví dụ đếm tổng số lượng giao dịch.

• GET https://my.sepay.vn/userapi/transactions/count

HTTP/1.1 200 OK
----
{
    "status": 200,
    "error": null,
    "messages": {
        "success": true
    },
    "count_transactions": 2322
}

Ví dụ đếm tổng số lượng giao dịch của tài khoản ngân hàng 0071000888888.

• GET https://my.sepay.vn/userapi/transactions/count?account_number=0071000888888

API VPBank lấy chi tiết một giao dịch 

GET https://my.sepay.vn/userapi/transactions/details/{transaction_id}

Lấy chi tiết thông tin một giao dịch theo ID

Ví dụ:

• GET https://my.sepay.vn/userapi/transactions/details/48673

HTTP/1.1 200 OK
----
{
    "status": 200,
    "error": null,
    "messages": {
        "success": true
    },
    "transaction": {
        "id": "48673",
        "transaction_date": "2023-05-04 11:59:47",
        "account_number": "0071000888888",
        "sub_account": null,
        "amount_in": "19689000.00",
        "amount_out": "0.00",
        "accumulated": "1128200335.00",
        "code": null,
        "transaction_content": "TRAN THIEN THAO chuyen tien...",
        "reference_number": null,
        "bank_brand_name": "VPBank",
        "bank_account_id": "21"
    }
}

Hướng dẫn tích hợp webhook VPBank – bắn thông tin giao dịch tức thì qua website của bạn

Tích hợp webhook VPBank giúp SePay chủ động gửi thông tin giao dịch phát sinh đến hệ thống của bạn. Nhờ đó, đồng bộ được giao dịch ngân hàng VPBank về hệ thống của bạn theo thời gian thực. Ứng dụng cho việc xác nhận thanh toán tự động, quản lý giao dịch ngân hàng hoặc các nghiệp vụ thanh toán khác.

Thêm tích hợp webhook VPBank

Bước 1: Truy cập menu WebHook.
Bước 2: Nhấn Thêm webhook (nút góc trên bên phải).

Ảnh thêm tích hợp webhook với VPBank

Bước 3: Điền thông tin cấu hình WebHook với VPBank:

Bước 4: Nhấn Thêm để hoàn tất tích hợp.

Dữ liệu gửi qua WebHook VPBank

SePay sẽ gửi một request POST với nội dung JSON như sau:

{
    "id": 92704,                               // ID giao dịch trên SePay
    "gateway": "VPBank",                       // Tên ngân hàng
    "transactionDate": "2023-03-25 14:02:37",  // Thời gian giao dịch (phía ngân hàng)
    "accountNumber": "0123499999",             // Số tài khoản ngân hàng
    "code": null,                              // Mã code thanh toán (SePay tự nhận diện)
    "content": "chuyen tien mua iphone",       // Nội dung chuyển khoản
    "transferType": "in",                      // Loại giao dịch: "in" là tiền vào, "out" là tiền ra
    "transferAmount": 2277000,                 // Số tiền giao dịch
    "accumulated": 19077000,                   // Số dư tài khoản (lũy kế)
    "subAccount": null,                        // Tài khoản phụ (tài khoản định danh, nếu có)
    "referenceCode": "208V009252001511",       // Mã tham chiếu giao dịch
    "description": ""                          // Toàn bộ nội dung chuyển khoản
}

Chứng thực API Key

Khi sử dụng API Key, SePay sẽ gửi kèm theo Header như sau:

Authorization: Apikey API_KEY_CUA_BAN

Kiểm tra hoạt động

Bạn vui lòng chuyển khoản thử để xem webhook có hoạt động như mong đợi không.

Xem WebHook đã được gửi

• • Vào menu Nhật ký → Nhật ký webhook để xem danh sách các WebHook đã gửi.

Danh sách webhook đã gửi

• • Xem nội dung webhook theo từng giao dịch tại Giao dịch → cột Tự động → chọn vào Pay.

Danh sách giao dịch

Danh sách webhooks đã bắn

Nhận diện WebHook thành công

Để SePay hiểu rằng website của bạn đã nhận thành công webhook, website cần trả về kết quả như sau:

Với chứng thực OAuth 2.0

{
    "success": true,
    ...
}

HTTP Status Code phải là 201

Với chứng thực API Key

{
    "success": true,
    ...
}

HTTP Status Code là 200 hoặc 201

Với không chứng thực

{
    "success": true,
    ...
}

HTTP Status Code là 200 hoặc 201

Nếu trả về không đúng như trên, SePay coi webhook đó là THẤT BẠI.

Cơ chế gọi lại (Retry) WebHook tự động

Lưu ý:

• SePay KHÔNG gọi lại nếu kết nối mạng thành công nhưng kết quả trả về là thất bại, trừ khi webhook đó đã được cấu hình retry.
• Retry chỉ được thực hiện khi thỏa điều kiện cấu hình.

Yêu cầu chống trùng lặp giao dịch

Khi webhook bị retry, để tránh xử lý trùng lặp giao dịch, SePay khuyến nghị bạn phải kiểm tra tính duy nhất của giao dịch.

Cách xử lý đề xuất:

• Kiểm tra duy nhất theo trường id.
• Hoặc kết hợp thêm các trường:
  • referenceCode
  • transferType
  • transferAmount

Đảm bảo không ghi nhận trùng giao dịch.

Retry Webhook bằng tay

Cách 1:

Chi tiết giao dịch → Webhook đã bắn → Gọi lại

Cách 2:

Nhật ký Webhook → Gọi lại

Liên hệ SePay để được tư vấn về API Ngân hàng:

• Zalo OA: https://zalo.me/sepayvn
• Facebook: https://www.facebook.com/sepay.vn
• Hotline: 02873.059.589

Xem thêm:

• Hướng dẫn lập trình cổng thanh toán
• Tạo ảnh QR Code VietQR
• Danh sách API ngân hàng