API ngân hàng Pay2S giúp phần mềm kết nối dữ liệu ngân hàng và tiếp nhận thông báo giao dịch. Với Partner API, đội phát triển có thể xây dựng luồng liên kết tài khoản, xác thực và đăng ký Webhook ngay trong hệ thống của mình.
Bài này tập trung vào Partner API & BankHub, dành cho người đã có backend. Nếu cần truy vấn lịch sử, hãy xem thêm bài hướng dẫn lấy biến động số dư bằng API ngân hàng Pay2S.
1. Chuẩn bị tích hợp API ngân hàng Pay2S
Chuẩn bị tài khoản Pay2S, quyền truy cập BankHub, backend và URL HTTPS nhận Webhook. Lưu khóa trong biến môi trường hoặc kho bí mật phía máy chủ; tránh đưa vào mã JavaScript trình duyệt.
Partner API Production dùng https://api-partner.pay2s.vn. Tách cấu hình UAT và Production để tránh dùng nhầm token hoặc dữ liệu thử. Tài liệu tổng quan Partner API mô tả thứ tự tích hợp.
2. Lấy Bearer Token bằng Access Key và Secret Key
Vào merchant.pay2s.vn → Bankhub → thiết lập để lấy cặp khóa. Ghép access_key:secret_key, mã hóa Base64 một lần rồi gửi:
POST https://api-partner.pay2s.vn/v1/auth/authorize
Authorization: Basic BASE64_ACCESS_KEY_COLON_SECRET_KEY
Content-Type: application/jsonĐọc data.access_token và data.expires_in trong phản hồi. Mẫu tài liệu có thời hạn 3.600 giây; backend nên quản lý hạn dùng theo giá trị thực nhận. Xem hướng dẫn xác thực chính thức.
Khi gọi API ngân hàng, gửi Authorization: Bearer ACCESS_TOKEN. Token này khác token xác thực Webhook và khác pay2s-token của API lịch sử giao dịch.
3. Liên kết tài khoản và kiểm tra OTP
Gọi POST /v1/banks với mẫu phù hợp ngân hàng và loại tài khoản. Với OpenAPI, các trường có thể gồm type, bankShortName, accountNumber, accName và accMobile. Yêu cầu bổ sung khác nhau theo ngân hàng.
Nếu phản hồi yêu cầu OTP, thực hiện POST /v1/banks/confirm-otp theo đúng mẫu. Giữ số tài khoản, điện thoại và OTP ở kiểu chuỗi để bảo toàn số 0 đầu.
Sau đó gọi GET /v1/banks để kiểm tra trạng thái. Lấy ID bản ghi tài khoản từ id; không dùng số tài khoản thay ID. Đối chiếu tài liệu quản lý ngân hàng trước khi ánh xạ phản hồi.
4. Đăng ký URL nhận giao dịch
Dùng Bearer Token gọi POST /v1/webhooks. Ví dụ body dưới đây dùng ID giả định; hãy thay bằng ID vừa lấy:
{
"user_bank_id": 25,
"webhook_url": "https://example.com/pay2s/webhook",
"type": "IN"
}IN nhận tiền vào, OUT nhận tiền ra, ALL nhận cả hai. Lưu token Webhook của cấu hình tương ứng. Backend nhận thông báo cần xác thực token và lưu dữ liệu bền vững trước khi xác nhận.
Đọc tiếp cách xử lý Webhook Pay2S để đối soát đơn hàng, kèm kiểm tra số tiền và chống trùng.
5. Kiểm tra trước khi vận hành
- Thử token hợp lệ, hết hạn và sai token.
- Kiểm tra trạng thái tài khoản sau bước OTP.
- Gửi lại cùng giao dịch để kiểm tra chống trùng.
- Thử mất kết nối và kiểm tra khả năng phục hồi.
- Che khóa, token và dữ liệu nhạy cảm trong log.
Đây là các kiểm tra triển khai đề xuất. Với lỗi thực tế, lưu mã phản hồi và thời điểm để đối chiếu; tránh gọi lặp thao tác thay đổi trạng thái khi chưa rõ kết quả.
Câu hỏi thường gặp
Partner API có thay cho API lịch sử giao dịch không?
Mỗi nhóm có mục đích và cách xác thực riêng. Chọn tài liệu tương ứng với chức năng cần xây dựng.
Có dùng một token cho mọi hướng kết nối không?
Không. Bearer Token gọi Partner API và token nhận Webhook phục vụ hai hướng trao đổi khác nhau.
Bắt đầu triển khai: hoàn thành xác thực, kiểm tra tài khoản rồi thử một luồng nhận tiền trước khi mở rộng. Tham khảo thêm ứng dụng API thanh toán tại điểm bán.
