API ngân hàng Pay2S giúp website và ứng dụng truy vấn giao dịch ngân hàng để theo dõi tiền vào, tiền ra và xây dựng quy trình đối soát chuyển khoản. Thay vì kiểm tra từng giao dịch thủ công, bạn có thể lấy dữ liệu qua API, đối chiếu với đơn hàng và cập nhật trạng thái thanh toán theo quy tắc của hệ thống.
Nếu đang tích hợp Pay2S V1, bạn cần phân biệt API tạo thanh toán với API lấy giao dịch. Bài viết này hướng dẫn cách chọn đúng chức năng, tạo token, gửi request và xử lý dữ liệu biến động số dư.
Doanh nghiệp cần kết nối dữ liệu giao dịch với website, POS hoặc phần mềm quản lý có thể tìm hiểu giải pháp Open API Banking trước khi chọn phạm vi tích hợp.
Quy trình tích hợp gồm lấy Secret Key, tạo token, truy vấn giao dịch và kiểm tra kết quả trước khi đưa vào đối soát đơn hàng.
1. Phân biệt API biến động số dư và Collection Link V1
Trong Pay2S Playground, mục Collection Link V1 dùng để tạo đơn hàng và liên kết thanh toán. API này gọi đến:
POST https://payment.pay2s.vn/v1/gateway/api/createĐể truy vấn giao dịch tiền vào hoặc tiền ra, bạn sử dụng API Giao Dịch:
POST https://api.pay2s.vn/userapi/transactionsHai API phục vụ những công việc khác nhau:
| Chức năng | API phù hợp |
|---|---|
| Tạo đơn hàng và liên kết thanh toán | Collection Link V1 |
| Lấy danh sách giao dịch trong khoảng ngày | API Giao Dịch |
| Nhận dữ liệu giao dịch do Pay2S chủ động gửi | Webhook giao dịch |
Tài liệu gọi luồng tạo thanh toán là Collection Link V1; endpoint lấy giao dịch được công bố riêng, không có /v1/ trong đường dẫn. Khi triển khai, hãy dùng đúng URL của từng chức năng. Bạn có thể đối chiếu tại tài liệu Collection Link V1 của Pay2S.
Với website đang dùng Collection Link V1, bạn có thể tạo thanh toán cho khách hàng, xử lý kết quả qua IPN của luồng thanh toán và sử dụng API giao dịch để đối soát dữ liệu tài khoản.
2. Cần chuẩn bị gì trước khi tích hợp API ngân hàng Pay2S?
Trước khi bắt đầu, bạn nên chuẩn bị:
- Tài khoản Pay2S và tài khoản ngân hàng cần theo dõi đã liên kết.
- Secret Key trong mục tích hợp Website/Application.
- Postman để kiểm tra request hoặc backend để gọi API.
- Số tài khoản và khoảng ngày muốn truy vấn.
Trước khi lấy khóa tích hợp, hãy kiểm tra ngân hàng Pay2S hỗ trợ và điều kiện kết nối của tài khoản cần theo dõi.
Hãy thực hiện việc gọi API từ backend. Secret Key và token cần được lưu trong cấu hình bảo mật của máy chủ, tránh đặt trực tiếp trong JavaScript công khai trên website.
3. Lấy Secret Key và tạo pay2s-token
Bước 1: Lấy đúng Secret Key
Đăng nhập Pay2S, mở Tích hợp → Website/Application, tìm dòng Secret key và sao chép giá trị tại đó.
Cần phân biệt Secret Key với Access key và Partner code. API giao dịch sử dụng token được tạo từ Secret Key.
Bước 2: Chuyển Secret Key sang Base64
Công thức tạo token:
pay2s-token = Base64(Secret Key)Hãy mã hóa toàn bộ chuỗi Secret Key đúng một lần.
Ví dụ minh họa:
Secret Key: example-secret
pay2s-token: ZXhhbXBsZS1zZWNyZXQ=Nếu dùng PHP, bạn có thể tạo token từ biến môi trường:
$secretKey = getenv('PAY2S_SECRET_KEY');
if ($secretKey === false || $secretKey === '') {
throw new RuntimeException('Chưa cấu hình PAY2S_SECRET_KEY');
}
$token = base64_encode($secretKey);Base64 có thể giải mã ngược, vì vậy token cần được bảo vệ như Secret Key. Khi thay Secret Key, bạn cũng cần tạo lại token tương ứng. Xem hướng dẫn xác thực API giao dịch Pay2S để kiểm tra cách gửi header.
4. Cách gọi API lấy biến động số dư bằng Postman
Bước 1: Tạo request POST
Trong Postman, tạo request mới với:
Method: POST
URL: https://api.pay2s.vn/userapi/transactionsBước 2: Thiết lập Headers
Thêm hai header:
| Key | Value |
|---|---|
Content-Type |
application/json |
pay2s-token |
Token Base64 đã tạo |
Tại tab Authorization, chọn No Auth.
Giá trị của pay2s-token chỉ chứa token. Không thêm tiền tố Bearer, Basic hoặc dấu ngoặc kép vào giá trị header.
Bước 3: Nhập JSON Body
Chọn Body → raw → JSON, sau đó nhập:
{
"bankAccounts": "0123456789",
"begin": "01/10/2026",
"end": "13/10/2026"
}Thay số tài khoản minh họa bằng tài khoản cần truy vấn.
Ý nghĩa các tham số:
| Tham số | Kiểu dữ liệu | Bắt buộc | Ý nghĩa |
|---|---|---|---|
bankAccounts |
String | Không | Số tài khoản muốn lọc giao dịch |
begin |
String | Có | Ngày bắt đầu, định dạng dd/mm/yyyy |
end |
String | Có | Ngày kết thúc, định dạng dd/mm/yyyy |
Theo tài liệu, bạn có thể bỏ bankAccounts để lấy giao dịch của tất cả tài khoản trong phạm vi truy cập:
{
"begin": "01/10/2026",
"end": "13/10/2026"
}Hãy giữ số tài khoản ở dạng chuỗi để bảo toàn các số 0 ở đầu.
Bước 4: Gửi request và kiểm tra phản hồi
Nhấn Send, sau đó kiểm tra cả mã trạng thái HTTP và nội dung JSON.
Trong phản hồi JSON, chú ý:
status: trạng thái xử lý yêu cầu.messages: thông báo từ Pay2S.transactions: danh sách giao dịch trả về.
Việc nhận được phản hồi HTTP thành công chưa đủ để quyết định cập nhật đơn hàng. Backend vẫn cần kiểm tra trạng thái nghiệp vụ và dữ liệu của từng giao dịch.
5. Ví dụ gọi API ngân hàng Pay2S bằng cURL
Bạn có thể tham khảo request sau. Cú pháp xuống dòng trong ví dụ dành cho Bash:
curl --request POST \
'https://api.pay2s.vn/userapi/transactions' \
--header 'Content-Type: application/json' \
--header 'pay2s-token: YOUR_BASE64_TOKEN' \
--data-raw '{
"bankAccounts": "0123456789",
"begin": "01/10/2026",
"end": "13/10/2026"
}'Trong đó:
YOUR_BASE64_TOKENlà token được tạo từ Secret Key.0123456789là số tài khoản minh họa.beginvàendcần được thay theo thời gian muốn tra cứu.
Khi đưa vào ứng dụng, hãy đọc token từ cấu hình backend để tránh lưu khóa trực tiếp trong mã nguồn.
6. Đọc dữ liệu biến động số dư trả về
Dưới đây là phản hồi minh họa đã rút gọn:
{
"status": true,
"messages": "Thành công",
"transactions": [
{
"id": 10001,
"transaction_date": "2026-10-13 09:30:00",
"transaction_id": "DEMO10001",
"account_number": "0123456789",
"vaNumber": null,
"bank": "ACB",
"amount": 250000,
"description": "THANHTOAN DH10001",
"type": "IN",
"checksum": "demo-checksum-10001"
}
]
}Các trường thường dùng khi xử lý giao dịch:
| Trường | Ý nghĩa |
|---|---|
id |
ID giao dịch duy nhất trên Pay2S |
transaction_date |
Thời gian giao dịch |
transaction_id |
Mã giao dịch gốc từ ngân hàng |
account_number |
Tài khoản nhận hoặc gửi tiền |
vaNumber |
Số tài khoản ảo, có thể là null |
bank |
Mã ngân hàng |
amount |
Số tiền giao dịch, đơn vị VNĐ |
description |
Nội dung chuyển khoản |
type |
IN là nhận tiền, OUT là chuyển tiền |
checksum |
Mã duy nhất của giao dịch do Pay2S tạo |
Với ví dụ trên, hệ thống nhận được một giao dịch tiền vào 250.000 đồng, có nội dung THANHTOAN DH10001.
Lưu ý, amount là số tiền của giao dịch. Trường này không biểu thị số dư hiện tại của tài khoản. Đối chiếu tên trường theo cấu trúc phản hồi API giao dịch Pay2S trước khi ánh xạ vào ứng dụng.
7. Cách đối soát chuyển khoản với đơn hàng
Để tự động xác nhận thanh toán, bạn nên xây dựng quy tắc đối chiếu rõ ràng.
Ví dụ, đơn hàng DH10001 cần thanh toán 250.000 đồng vào tài khoản 0123456789. Backend có thể kiểm tra:
- Giao dịch có
typebằngIN. - Tài khoản nhận tiền khớp với tài khoản của đơn hàng.
- Số tiền đáp ứng quy tắc thanh toán của đơn.
- Nội dung chuyển khoản chứa mã đơn đúng định dạng.
- Giao dịch chưa được sử dụng để xác nhận một đơn hàng khác.
Hãy lưu id giao dịch và đặt ràng buộc duy nhất trong cơ sở dữ liệu. Cách này giúp tránh ghi nhận tiền hoặc cập nhật thanh toán nhiều lần khi cùng một giao dịch xuất hiện trong các lần truy vấn.
Nếu khách chuyển thiếu tiền, thừa tiền hoặc ghi sai nội dung, hệ thống nên đưa giao dịch vào danh sách cần kiểm tra theo quy trình của cửa hàng.
Với đơn được tạo bằng Collection Link V1, hãy triển khai xử lý kết quả theo tài liệu IPN của luồng thanh toán. API giao dịch có thể hỗ trợ đối soát tài khoản và kiểm tra chênh lệch.
Nếu triển khai cho POS hoặc chuỗi cửa hàng, bạn có thể tham khảo cách ứng dụng API thanh toán ngân hàng tại điểm bán để gắn giao dịch với đơn hàng và quy trình vận hành.
8. Nhận biến động số dư tự động bằng Webhook
Ngoài việc chủ động gọi API, bạn có thể cấu hình Webhook để Pay2S gửi dữ liệu giao dịch đến endpoint của mình.
Các bước cấu hình cơ bản:
- Mở Webhooks → Thêm webhook.
- Chọn tài khoản ngân hàng đã liên kết.
- Chọn sự kiện nhận tiền, chuyển tiền hoặc tất cả.
- Nhập URL nhận dữ liệu của backend.
- Lưu token được cung cấp khi tạo Hook.
Bạn nên sử dụng HTTPS cho endpoint nhận dữ liệu.
Phân biệt token và tên trường của Webhook
Webhook giao dịch sử dụng header:
Authorization: Bearer YOUR_TOKEN_WEBHOOKĐây là token của Webhook, cần phân biệt với pay2s-token dùng để truy vấn API giao dịch.
Tên trường giữa hai luồng cũng khác nhau:
| API truy vấn giao dịch | Webhook giao dịch |
|---|---|
account_number |
accountNumber |
transaction_date |
transactionDate |
description |
content |
type |
transferType |
amount |
transferAmount |
Receiver cần kiểm tra token trước khi xử lý mảng transactions. Sau khi lưu dữ liệu thành công hoặc đưa vào hàng đợi bền vững, hãy phản hồi HTTP 200 kèm JSON:
{
"success": true
}Webhook có thể được gửi lại, vì vậy cơ chế chống xử lý trùng vẫn cần được áp dụng. Bạn có thể kết hợp Webhook để nhận thông báo và API truy vấn để đối soát định kỳ. Xem tài liệu kỹ thuật Webhook giao dịch Pay2S khi xây dựng endpoint tiếp nhận.
Nếu nhiều nhân sự cần theo dõi tiền về, giải pháp chia sẻ biến động số dư giúp bạn xem thêm cách tổ chức thông báo theo nhu cầu vận hành.
9. Những lỗi thường gặp khi tích hợp
Token không hợp lệ
Kiểm tra xem bạn đã lấy đúng Secret Key, mã hóa Base64 đúng một lần và gửi đúng header pay2s-token hay chưa.
Các nguyên nhân dễ gặp gồm:
- Sao chép nhầm Access key.
- Gửi nguyên Secret Key chưa chuyển đổi.
- Mã hóa Base64 hai lần.
- Token có khoảng trắng hoặc ký tự xuống dòng.
- Tiếp tục dùng token cũ sau khi thay Secret Key.
Không thấy giao dịch cần tìm
Kiểm tra số tài khoản, khoảng ngày truy vấn và dữ liệu trên Pay2S. Định dạng ngày gửi lên phải là dd/mm/yyyy.
Nếu giao dịch có trên Pay2S nhưng ứng dụng không hiển thị, hãy kiểm tra thêm điều kiện lọc và cách đọc mảng transactions trong backend.
Gặp lỗi 429 Too Many Requests
Tài liệu API giao dịch công bố giới hạn tối đa 60 request/phút. Khi vượt giới hạn, hệ thống trả lỗi 429 Too Many Requests.
Bạn nên điều phối các tác vụ gọi API, tránh nhiều tiến trình truy vấn đồng thời và tăng khoảng chờ khi gặp lỗi giới hạn.
Đơn hàng được xác nhận nhiều lần
Kiểm tra cơ chế chống trùng theo ID giao dịch. Việc ghi nhận giao dịch và cập nhật đơn hàng nên được thực hiện trong cùng giao dịch cơ sở dữ liệu để hạn chế xử lý đồng thời gây sai lệch.
10. Câu hỏi thường gặp về API ngân hàng Pay2S
API ngân hàng Pay2S có lấy được cả tiền vào và tiền ra không?
API giao dịch có trường type để phân biệt IN và OUT. Ứng dụng có thể dựa vào trường này để xử lý giao dịch nhận tiền hoặc chuyển tiền.
Có bắt buộc gửi số tài khoản không?
Theo tài liệu, bankAccounts là tham số tùy chọn. Bỏ trường này để lấy giao dịch của tất cả tài khoản trong phạm vi truy cập; begin và end vẫn bắt buộc.
Có cần tạo chữ ký HMAC khi lấy danh sách giao dịch không?
Request lấy danh sách giao dịch sử dụng header pay2s-token. Chữ ký HMAC của Collection Link V1 thuộc luồng tạo thanh toán riêng.
API giao dịch có trả về số dư hiện tại không?
Phản hồi được mô tả trong hướng dẫn này là danh sách giao dịch phát sinh. Không dùng amount của một giao dịch làm số dư tài khoản.
Nên bắt đầu kiểm tra ở đâu?
Bạn có thể mở Pay2S Playground mục Danh sách giao dịch để xem cấu trúc request và response, sau đó thực hiện các bước cấu hình token và truy vấn bằng Postman theo hướng dẫn trên.
