# API ngân hàng Pay2S: Hướng dẫn tích hợp Partner API

- Link: https://mail.hoadontudong.com.vn/api-ngan-hang-pay2s-tich-hop-partner-api/
- Published: 2026-10-13T13:42:12+07:00
- Author: Hóa Đơn Tự Động

**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](https://hoadontudong.com.vn/?p=314).

## 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](https://mail.hoadontudong.com.vn/tai-lieu-pay2s/)
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](https://mail.hoadontudong.com.vn/tai-lieu-pay2s/).

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](https://mail.hoadontudong.com.vn/tai-lieu-pay2s/)
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](https://hoadontudong.com.vn/api-ngan-hang-pay2s-webhook-doi-soat/),
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ả.

![Logo Pay2S by Web2M](https://hoadontudong.com.vn/wp-content/uploads/2026/10/logo-
pay2s.png)

## 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](https://hoadontudong.com.vn/api-thanh-toan-ngan-hang-diem-ban/).