# Postman API thanh toán ngân hàng Pay2S: Cách test BankHub nhanh và an toàn

- Link: https://mail.hoadontudong.com.vn/postman-api-thanh-toan-ngan-hang-pay2s/
- Published: 2026-10-15T23:50:04+07:00
- Author: Hóa Đơn Tự Động

`Postman` giúp đội kỹ thuật kiểm tra nhanh API thanh toán ngân hàng Pay2S trước 
khi viết adapter trong backend. Với BankHub, một collection tốt có thể mô phỏng 
tuần tự lấy `Bearer Token`, thêm tài khoản, xác nhận OTP, đọc danh sách, tạo webhook,
xem lịch sử và gọi Analytics. Tuy nhiên `Postman` chỉ là công cụ kiểm thử; credential
và dữ liệu phải được bảo vệ như khi chạy `Production`.

Tài liệu `Postman` Collection của Pay2S Partner API là điểm bắt đầu để dựng chuỗi
request có thể chạy lại. Trên hoadontudong.com.vn, hướng dẫn này dùng `Postman` 
để kiểm tra các bước phụ thuộc nhau: token lấy từ đâu, ID nào đi vào request tiếp
theo và trạng thái nào cần đọc lại. Hai môi trường `UAT` và `Production` phải được
kiểm tra riêng để tránh lấy một response mô phỏng làm kết luận về hệ thống thật.

## Tải collection và tạo Environment

![Minh họa tải Postman collection và tạo Environment](https://hoadontudong.com.vn/
wp-content/uploads/2026/10/bankhub-postman-inline-collection-imagegen.png)

Tải collection và tạo Environment

Tài liệu Pay2S cung cấp collection Partner API để import vào `Postman`. Sau khi 
import, tạo Environment riêng cho `UAT` và `Production`. Các biến thường gồm base_url,
access_key, secret_key và `bearer_token`. `Secret Key` nên đặt trong biến bí mật
của `Postman`, không ghi thẳng vào collection hoặc tên request. base_url phải đổi
theo môi trường; không dùng token `UAT` gọi endpoint `Production`.

Nên thêm biến `customer_reference`, `bank_id`, webhook_id, `history_id` và mã thử
nghiệm thay vì sửa body ở nhiều request. Khi response tạo tài khoản hoặc webhook
trả ID, copy giá trị vào biến môi trường hoặc biến collection có kiểm soát. Dữ liệu
mẫu như số tài khoản, CCCD, OTP và mật khẩu phải là dữ liệu `UAT` được phép dùng.
Không đưa thông tin thật vào workspace chia sẻ.

## Test authorize và `Bearer Token`

Request đầu tiên là `POST /v1/auth/authorize`. Header Authorization dùng Basic base64(
access_key:secret_key), còn `Content-Type` là `application/json`. Gửi request và
kiểm tra success, `token_type`, `access_token` và `expires_in`. Không copy token
vào URL. Sau khi có token, lưu vào `bearer_token` rồi dùng `Authorization: Bearer`{{`
bearer_token`}} cho các request phía sau.

QA nên thử cả credential hợp lệ, `Secret Key` sai, Base64 sai, token rỗng và token
hết hạn. Mỗi case lưu HTTP status, error code và thông điệp đã che dữ liệu nhạy 
cảm. Nếu nhận `401` ở request banks, không vội sửa body ngân hàng; trước tiên kiểm
tra token và base_url. [Bài xác thực API thanh toán ngân hàng Pay2S](https://hoadontudong.com.vn/xac-thuc-api-thanh-toan-ngan-hang-pay2s/)
giải thích sâu hơn vì sao `Basic Auth` và `Bearer Token` là hai bước khác nhau.

## Test liên kết ngân hàng và OTP

Trong folder Banks, bắt đầu bằng request thêm tài khoản đúng mẫu ngân hàng. Giữ 
số tài khoản, số điện thoại, CCCD, mã số thuế và OTP dạng chuỗi. Nếu phản hồi báo
OTP, gửi request confirm-otp với cùng type, `bankShortName`, `accountNumber` và 
trường bổ sung cần thiết. Không dùng OTP đã hết hạn hoặc copy từ môi trường khác.
Với `UAT`, chỉ dùng OTP thử nghiệm được tài liệu nêu.

Sau confirm, gọi `GET /v1/banks` và kiểm tra status, id, `accountNumber`, bankName,
shortBankName và vaNumber nếu có. Lưu id vào biến `bank_id` để dùng cho status, 
delete và webhook. Test thêm trường hợp OTP sai, account chưa hoạt động, request
lặp và token hết hạn. Không coi status true của request thêm là trạng thái tài khoản
đã sẵn sàng.

## Test webhook giao dịch và lịch sử

![Minh họa test webhook giao dịch và lịch sử bằng Postman](https://hoadontudong.
com.vn/wp-content/uploads/2026/10/bankhub-postman-inline-webhook-imagegen.png)

Test webhook giao dịch và lịch sử

Request tạo webhook nhận `user_bank_id` lấy từ danh sách, `webhook_url` và type `
IN`, `OUT` hoặc `ALL`. Dùng endpoint HTTPS kiểm thử có thể ghi nhận payload, nhưng
không đưa token thật vào công cụ công khai. Sau khi tạo, `GET /v1/webhooks` để kiểm
tra id, trạng thái, URL, loại giao dịch và token đã cấp. Tách token webhook khỏi`
bearer_token` trong Environment.

`GET /v1/webhooks/history` giúp xem Pay2S đã gửi gì, endpoint trả response nào, `
status_code` ra sao và `call_time`. Nếu endpoint test trả lỗi, dùng resend với `
history_id` và kiểm tra receiver có chống trùng. Payload cần được đọc theo transactions,`
paymentCode`, `extraData`, `partnerRefId` và trường có điều kiện. Bài [webhook giao dịch ngân hàng Pay2S](https://hoadontudong.com.vn/webhook-giao-dich-ngan-hang-pay2s/)
cung cấp checklist xử lý sau khi request `Postman` thành công.

## Test Hosted Link và webhook sự kiện

Hosted Link cần backend tạo link session, vì vậy `Postman` có thể dùng để kiểm tra
request `POST /v1/bankhub/link-sessions`, response `session_id`, environment, `expires_in`
và `hosted_link_url`. Không tự ghép URL hoặc token. Form và `SDK` được mở trên trình
duyệt, còn `Postman` dùng để tra session qua `GET /v1/bankhub/link-sessions/{session_id}`
hoặc xem customer accounts.

Webhook sự kiện Hosted Link cần receiver thật hoặc công cụ phù hợp để kiểm tra Authorization,
event ID, timestamp và `HMAC` trên raw body. `Postman` có thể giúp replay payload
đã lưu trong `UAT` nhưng không nên dùng để kết luận callback trình duyệt là trạng
thái cuối. Đọc event `BANK_ACCOUNT_LINKED`, `LINK_SESSION_COMPLETED` và `LINK_SESSION_UNCERTAIN`
khác nhau. [Bài webhook BankHub trạng thái liên kết](https://hoadontudong.com.vn/webhook-bankhub-pay2s-trang-thai-lien-ket/)
là tài liệu đối chiếu cho phần này.

## Test Analytics và so sánh `UAT` `Production`

Sau khi gửi requests, gọi /v1/metrics/calls, /v1/metrics/logs, /v1/metrics/endpoints
và /v1/metrics/status để xem request đã ghi nhận. Chú ý page, limit, path, status
và method ở calls; logs và endpoints có thể có cấu trúc khác giữa `Production` và`
UAT`. Lưu response mẫu trong test report nhưng ghi rõ đó là môi trường nào và thời
điểm nào.

Một collection tốt có test script kiểm tra status code, trường success hoặc status,
kiểu dữ liệu id, `token_type` và mảng data. Tuy nhiên đừng viết script buộc schema`
UAT` làm chuẩn `Production`. Khi tài liệu đánh dấu response là minh họa hoặc chưa
gọi `Production`, QA cần ghi chú mức độ tin cậy và yêu cầu xác nhận backend trước
khi đóng test.

## Kỷ luật an toàn khi dùng `Postman`

Không commit file Environment chứa `Secret Key`, `Bearer Token` hoặc webhook token.
Không chụp screenshot có credential, `accountNumber` thật, OTP hoặc payload người
chuyển. Khi chia sẻ collection, dùng placeholder và để biến bí mật trống. Sau khi
kết thúc test, xóa token cache hoặc rotate khóa nếu đã chia sẻ nhầm. Workspace team
nên phân quyền người được xem secret.

`Postman` không thay thế test tự động trong CI. Sau khi request đã được kiểm chứng,
chuyển logic tạo header, refresh token, retry, chống trùng và validate response 
vào backend. Mọi request `Production` cần approval, account đúng và dữ liệu đúng.
[Bài tổng quan API thanh toán ngân hàng Pay2S](https://hoadontudong.com.vn/api-thanh-toan-ngan-hang-pay2s/)
giúp đặt các request `Postman` vào kiến trúc lớn hơn thay vì coi collection là sản
phẩm tích hợp hoàn chỉnh.

## Góc nhìn triển khai thực tế

Một collection dễ bàn giao nên chia thư mục theo hành trình thay vì sắp xếp ngẫu
nhiên theo URL: authorize, banks, link session, webhooks, transaction replay và 
metrics. Pre-request script chỉ nên tạo giá trị không nhạy cảm hoặc đọc biến bí 
mật; test script kiểm tra status, content type, trường bắt buộc và lưu ID cần cho
request kế tiếp. Environment `UAT` và `Production` phải tách riêng, tên biến nhất
quán, còn token sau authorize chỉ nằm trong workspace phù hợp. Khi xuất collection,
kiểm tra lại xem secret có bị nhúng vào example hay không.

Test case tốt mô tả mục tiêu, dữ liệu đầu vào, điều kiện trước, request, response
mong đợi và cách dọn dữ liệu. Với liên kết ngân hàng, không ghi OTP thật vào lịch
sử; với webhook, dùng endpoint test có thể xác minh header và lưu raw body; với 
giao dịch, dùng idempotency hoặc payload đã che để replay. Kiểm tra request hợp 
lệ, token sai, body thiếu trường, ID không tồn tại, timeout và gọi lại. Sau mỗi 
case, ghi rõ đó là `UAT` hay `Production`, vì cùng một endpoint có thể trả schema
hoặc dữ liệu mẫu khác nhau.

Sau khi kiểm chứng request bằng `Postman`, hãy ghi assertion tương ứng cho adapter:
token hết hạn được xử lý thế nào, timeout có được gửi lại không, payload trùng có
tạo thêm tác động không. Một lượt `Postman` trả thành công chỉ cho thấy request 
đó được xử lý trong điều kiện vừa thử. Backend còn cần giữ dữ liệu bền vững và phục
hồi khi một bước sau thất bại; những hành vi này phải được thử ở ứng dụng thật trước
khi đóng tính năng.

## Kiểm soát chất lượng và vận hành

Bản collection bàn giao cần đi qua một lượt rà soát bằng tìm kiếm: `Access Key`,`
Secret Key`, token, URL callback, số tài khoản và OTP có thể nằm cả trong saved 
example hoặc script. Xóa giá trị thật, giữ placeholder cùng kiểu dữ liệu cần thiết,
rồi xuất file để kiểm tra lại độc lập với workspace đang mở. Với `UAT` và `Production`,
người nhận chỉ nên nhận cấu hình của môi trường họ được phép dùng; quyền truy cập
workspace không thay thế việc kiểm soát nội dung file đã xuất.

Để kiểm tra tính lặp lại của bộ `Postman`, chạy một lượt với Environment sạch. Authorize
phải tạo token trước khi gọi banks; `user_bank_id` phải đến từ response của đúng
tài khoản thử; webhook history và resend phải dùng ID của lần gửi vừa kiểm tra. 
Một biến còn sót từ hôm trước có thể làm request xanh dù chuỗi phụ thuộc đã hỏng.
Sau lượt `UAT`, dọn dữ liệu hoặc ghi lại ID được giữ để lần sau không tạo thêm bản
ghi; chỉ chạy thao tác `Production` trong phạm vi đã cho phép.

Báo cáo kiểm thử cần đủ ngắn để người khác tái hiện lỗi: mục tiêu case, environment,
commit collection, thời điểm, response đã che dữ liệu và trạng thái đọc lại. Nếu
request thành công nhưng receiver chưa ghi nhận, ghi rõ cả hai kết quả thay vì chấm
toàn bộ case là pass. Khi đưa `Postman` vào pipeline, dừng lượt chạy nếu authorize
thất bại và gom lỗi theo bước; tránh để một token sai tạo hàng loạt lỗi thứ cấp 
che khuất nguyên nhân ban đầu.

## Quy trình triển khai API thanh toán ngân hàng Pay2S

 1. Tải collection chính thức và import vào `Postman`.
 2. Tạo Environment riêng cho `UAT` và `Production`.
 3. Đặt khóa trong biến bí mật, không hardcode vào collection.
 4. Authorize để lấy `bearer_token` và kiểm tra `expires_in`.
 5. Test banks, OTP và lưu `bank_id`.
 6. Test webhook, history và resend bằng dữ liệu `UAT`.
 7. Test Hosted Link, event và metrics theo từng môi trường.
 8. Chuyển logic đã xác nhận vào backend có retry và chống trùng.

## Câu hỏi thường gặp

### `Postman` có thể gọi trực tiếp `Production` không?

Có thể về mặt kỹ thuật nếu tài khoản có quyền, nhưng phải có approval, credential
đúng và dữ liệu an toàn. Nên bắt đầu từ `UAT`.

### `bearer_token` có phải `Secret Key` không?

Không. `Bearer Token` là token tạm lấy từ `Access Key` và `Secret Key`; vẫn cần 
bảo vệ nhưng có thời hạn riêng.

### Có nên lưu OTP trong Environment không?

Không nên lưu lâu dài. OTP chỉ dùng trong phiên kiểm thử và cần xóa sau khi hoàn
tất.

### `Postman` có kiểm tra webhook tự động được không?

Có thể replay hoặc gọi endpoint, nhưng receiver vẫn phải kiểm chữ ký, lưu event 
và chống trùng như `Production`.

### Nếu response `UAT` khác `Production` thì sao?

Ghi nhận khác biệt, chuẩn hóa adapter và xác nhận schema với backend; không lấy `
UAT` làm chuẩn duy nhất.

## Đọc tiếp trong cụm BankHub Pay2S

 * [tổng quan API thanh toán ngân hàng Pay2S](https://hoadontudong.com.vn/api-thanh-toan-ngan-hang-pay2s/)
 * [xác thực và quản lý token](https://hoadontudong.com.vn/xac-thuc-api-thanh-toan-ngan-hang-pay2s/)
 * [test liên kết tài khoản ngân hàng](https://hoadontudong.com.vn/lien-ket-tai-khoan-ngan-hang-pay2s-api/)
 * [test Hosted Link và SDK](https://hoadontudong.com.vn/pay2s-bankhub-hosted-link-sdk/)
 * [đọc metrics và lịch sử API](https://hoadontudong.com.vn/analytics-api-thanh-toan-ngan-hang-pay2s/)