Pay2S

Appearance

Thử API bằng Postman ​

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

  1. Tải file JSON ở liên kết trên.
  2. Mở Postman, chọn Import, chọn file vừa tải.
  3. 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ómDùng để
Order APITạo Collection Link, hủy đơn, mô phỏng Return URL và IPN
TransactionsTruy vấn lịch sử giao dịch
Recipient NameTra cứu tên chủ tài khoản
WebhooksGửi payload mẫu tới webhook của bạn
QR PaymentCác request OneQR và VietQR
API HDDTLấ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

Chọn đúng nhóm API

Collection chứa nhiều cơ chế xác thực khác nhau. Không dùng chữ ký Collection Link thay cho token giao dịch, xác thực OneQR hoặc chữ ký header HĐĐT. Đối chiếu trang tài liệu của từng API trước khi gửi.

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ếnGiá trị
accessKeyAccess Key của bạn
partnerCodePartner Code tương ứng
secretKeySecret Key cùng bộ khóa; giữ riêng, không chia sẻ bản export chứa khóa
orderIdMã đơn đã tạo, dùng khi thử hủy
connection_idID kết nối trả về từ API HĐĐT
invoice_idID hóa đơn trả về sau khi tạo nháp
external_refMã 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:

js
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 ​

  1. Mở Order API → Collection Link Create Order → Create.
  2. 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.
  3. Sửa amount, redirectUrl, ipnUrl và dữ liệu người mua/hàng hóa theo tình huống thử.
  4. Chọn Body dạng raw → JSON, gửi request.
  5. 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 ​

  1. 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.
  2. Mở request Cancel trong nhóm Order API.
  3. 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:

RequestBước thực hiện
01 - Sandbox connectionsLấy kết nối; chọn đúng môi trường và lưu connection_id
02 - Create draftSửa dữ liệu hóa đơn, external_ref; lấy invoice_id từ response
03 - submit_draftGửi nháp sang nhà cung cấp nếu chưa gửi
04 - publishChỉ chạy khi muốn phát hành hóa đơn
05 - detailXem chi tiết/trạng thái
06 - syncĐồng bộ trạng thái từ nhà cung cấp
07 - filesLấ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ỗiKiể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 IPNipnUrl có phải endpoint thật, truy cập được từ Internet không?
Hủy không tìm thấy đơnDùng đúng orderId và bộ khóa của đơn đã tạo
Request còn 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ợ.