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
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 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ử
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 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 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 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
- Tải collection chính thức và import vào
Postman. - Tạo Environment riêng cho
UATvàProduction. - Đặt khóa trong biến bí mật, không hardcode vào collection.
- Authorize để lấy
bearer_tokenvà kiểm traexpires_in. - Test banks, OTP và lưu
bank_id. - Test webhook, history và resend bằng dữ liệu
UAT. - Test Hosted Link, event và metrics theo từng môi trường.
- 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.
