Thử API bằng Postman
Nội dung Markdown đầy đủ của trang tài liệu.
# 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](https://docs.pay2s.vn/downloads/developer-pay2S.postman_collection.json)**
**[Tải Environment mẫu không chứa khóa](/downloads/pay2s-local.postman_environment.json)**
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ó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 |
::: info 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ế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 |
::: info 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](/api/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](/api/collection-link) và [chuỗi ký V1](/others/signature#tạo-đơn-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](/api/cancel-order) để 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](/api/simulate-payment) để 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](/others/signature#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ử](/hoa-don-dien-tu/api).
## 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ế](/hoa-don-dien-tu/api-tra-cuu-ma-so-thue).
- **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](/history-api/tai-lieu-ky-thuat).
- **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](/others/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ợ.