Thử API bằng Postman

✧ Mở bằng AI

Sao chép tài liệu, mở AI rồi dán vào cuộc trò chuyện.

Collection Developer Pay2S tập hợp các request mẫu để thử tích hợp. Import collection, cấu hình bộ khóa của bạn rồi chạy từng request cần dùng.

Tải và import collection

Tải Developer Pay2S.postman_collection.json

Tải Environment mẫu không chứa khóa

Tải file JSON ở liên kết trên.
Mở Postman, chọn Import, chọn file vừa tải.
Trong Collections, mở Developer Pay2S.

Nếu trình duyệt hiển thị nội dung JSON, lưu thành file .json rồi import. Có thể import trực tiếp bằng URL nếu phiên bản Postman của bạn hỗ trợ.

Collection gồm những gì?

Nhóm	Dùng để
Order API	Tạo Collection Link, hủy đơn, mô phỏng Return URL và IPN
Transactions	Truy vấn lịch sử giao dịch
Recipient Name	Tra cứu tên chủ tài khoản
Webhooks	Gửi payload mẫu tới webhook của bạn
QR Payment	Các request OneQR và VietQR
API HDDT	Lấy kết nối, tạo nháp, gửi nháp, phát hành, xem chi tiết, đồng bộ và lấy file

Cấu hình trước khi chạy

Import thêm Environment mẫu ở trên, chọn Pay2S - Local rồi nhập các giá trị của bạn. Bản collection mới đọc khóa từ Environment và không chứa khóa/token thật.

Biến	Giá trị
`accessKey`	Access Key của bạn
`partnerCode`	Partner Code tương ứng
`secretKey`	Secret Key cùng bộ khóa; giữ riêng, không chia sẻ bản export chứa khóa
`orderId`	Mã đơn đã tạo, dùng khi thử hủy
`connection_id`	ID kết nối trả về từ API HĐĐT
`invoice_id`	ID hóa đơn trả về sau khi tạo nháp
`external_ref`	Mã tham chiếu nghiệp vụ của bạn khi tạo hóa đơn

Khóa lấy từ Environment

Các script đọc khóa theo cùng cách sau; bạn chỉ cần nhập Environment, không cần sửa khóa trong script:

const accessKey = pm.environment.get('accessKey');
const partnerCode = pm.environment.get('partnerCode');
const secretKey = pm.environment.get('secretKey');

Không điền khóa thật trực tiếp vào collection để tránh chia sẻ nhầm khi export. Nếu đã import bản cũ, import lại bản mới để nhận các script đã sửa.

Thử tạo đơn thanh toán

Mở Order API → Collection Link Create Order → Create.
Trong Pre-request Script, cấu hình khóa như trên; đổi bankAccounts thành tài khoản đã liên kết, đúng bank_id và số tài khoản không có khoảng trắng.
Sửa amount, redirectUrl, ipnUrl và dữ liệu người mua/hàng hóa theo tình huống thử.
Chọn Body dạng raw → JSON, gửi request.
Kiểm tra response, mở payUrl trả về để xem trang thanh toán.

Request Create hiện dùng V2: script tạo requestId, orderId, Base64 extraData, ký HMAC rồi gọi pm.request.body.update(...). Vì vậy, sửa riêng Body có thể bị script ghi đè khi bấm Send. Hãy sửa dữ liệu trong script trước bước ký.

Địa chỉ example.com là ví dụ; thay bằng endpoint của bạn để kiểm tra chuyển hướng và IPN. Mỗi lần Send, script tạo mã đơn mới; lưu đúng orderId của đơn cần kiểm tra.

Xem Collection Link V2 để hiểu dữ liệu hóa đơn. Nếu chỉ thử luồng V1 cũ, dùng contract Collection Link V1 và chuỗi ký V1, không chỉ bỏ signatureVersion khỏi body V2.

Thử hủy đơn

Create tự lưu orderId vào Environment. Kiểm tra đúng đơn chưa thanh toán cần hủy; nếu dùng đơn khác, thay giá trị này.
Mở request Cancel trong nhóm Order API.
Dùng cùng bộ khóa đã tạo đơn rồi gửi request.

Script Cancel đọc khóa và orderId từ Environment, tạo chữ ký riêng với requestType=cancel. Không dùng lại chữ ký create.

Thành công trả status: "cancelled", resultCode: 0. Đơn đã thanh toán không được hủy; gọi lại đơn đã hủy vẫn thành công. Xem API hủy đơn hàng để tra mã lỗi.

Thử Return URL, IPN và webhook

Tự động kiểm thử đơn demo trên Pay2S

Sau khi Create trả environment: "demo", mở Order API → Simulate Demo Payment → Simulate Payment rồi Send. Request dùng orderId đã lưu trong Environment, ghi nhận thanh toán demo và đưa đơn vào hàng chờ gửi IPN tới ipnUrl. Đợi IPN ở backend của bạn để xác nhận test hoàn tất.

Gọi lại không tạo thêm giao dịch. Đơn production bị từ chối. Xem API mô phỏng thanh toán demo để biết response và mã lỗi.

Muốn nhận lại callback để test trigger, chạy Resend Demo IPN trong cùng thư mục. Request này gửi và ký resendIpn: true; không tạo thêm giao dịch. Nếu IPN đang chờ hoặc đang gửi, giữ nguyên lượt hiện có.

Chỉ mô phỏng callback tới hệ thống của bạn

Các request này dùng để mô phỏng gửi dữ liệu tới hệ thống của bạn, không phải thao tác yêu cầu Pay2S ghi nhận đã nhận tiền.

Return URL dùng biến redirectUrl.
Request IPN dùng ipnUrl, thống nhất với Create.
Webhook dùng endpoint và thông tin xác thực của endpoint nhận nếu có.

Điền đủ các biến trong URL, Body và script của request. Phía nhận cần kiểm tra chữ ký, mã đơn và số tiền; xem xác thực IPN. Các request mô phỏng cũng cần đối chiếu lại payload với contract IPN trước khi dùng kiểm thử nghiệp vụ.

Thử API hóa đơn điện tử

Trong nhóm API HDDT, chạy theo nhu cầu:

Request	Bước thực hiện
`01 - Sandbox connections`	Lấy kết nối; chọn đúng môi trường và lưu `connection_id`
`02 - Create draft`	Sửa dữ liệu hóa đơn, `external_ref`; lấy `invoice_id` từ response
`03 - submit_draft`	Gửi nháp sang nhà cung cấp nếu chưa gửi
`04 - publish`	Chỉ chạy khi muốn phát hành hóa đơn
`05 - detail`	Xem chi tiết/trạng thái
`06 - sync`	Đồng bộ trạng thái từ nhà cung cấp
`07 - files`	Lấy thông tin file hóa đơn

Nhóm HĐĐT có script cấp thư mục; giữ script này để tạo các header xác thực. Kiểm tra biến mà script đọc và dùng cùng bộ khóa tài khoản của bạn. Nếu tạo nháp với auto_submit: true, không cần gửi nháp thủ công thêm lần nữa.

Tên request có chữ Sandbox không tự chuyển môi trường: môi trường phụ thuộc kết nối được chọn. Không chạy toàn bộ collection bằng Runner khi chưa xem từng request, vì có thao tác hủy đơn và phát hành hóa đơn.

Chi tiết: API hóa đơn điện tử.

Các cấu hình bổ sung

Tax Lookup: nhập taxCode; request dùng GET /userapi/tax-lookup và pay2s-token. Xem API tra cứu mã số thuế.
OneQR: chạy Authentication trước để lưu oneqrToken. Nhập bankShortName, MID/TID và dữ liệu QR theo cấu hình được cấp. Các URL API dùng HTTPS; tra cứu giao dịch dùng transactionId.
Transactions: nhập account_number, begin, end theo tài liệu lịch sử giao dịch.
API HDDT: mẫu create dùng auto_submit: false để thử riêng bước gửi nháp. Đổi thành true nếu muốn gửi ngay và bỏ qua bước 03 - submit_draft.

Khi gặp lỗi

Lỗi	Kiểm tra
Thiếu khóa dù đã nhập Variables	Đã chọn Environment chưa; script đọc Environment hay đang dùng hằng số?
Body sửa rồi vẫn gửi dữ liệu cũ	Pre-request Script có ghi đè body bằng `pm.request.body.update()` không?
Sai chữ ký	Xem hướng dẫn Signature; không đổi body sau bước ký
Tài khoản ngân hàng không hợp lệ	Tài khoản đã liên kết, đúng mã ngân hàng, số tài khoản không có khoảng trắng
Không nhận IPN	`ipnUrl` có phải endpoint thật, truy cập được từ Internet không?
Hủy không tìm thấy đơn	Dùng đúng `orderId` và bộ khóa của đơn đã tạo
Request còn `{{variable}}`	Biến chưa được khai báo hoặc đang chọn nhầm Environment

Dùng Postman Console để xem lỗi script và request thực tế. Che khóa và thông tin khách hàng trước khi chia sẻ log hỗ trợ.