# Pay2S là gì? API Pay2S hoạt động như thế nào trong hệ thống thanh toán

- Link: https://mail.hoadontudong.com.vn/pay2s-api-la-gi-va-cach-hoat-dong-bien-tap-20261015/
- Published: 2026-10-15T23:50:38+07:00
- Author: Hóa Đơn Tự Động

API thanh toán cần được hiểu như một cuộc trao đổi có trạng thái. Website gửi yêu
cầu tạo thanh toán, nhận đường dẫn cho khách và chờ kết quả từ server. Trong khoảng
chờ đó có thể xảy ra timeout, khách nhấn lại hoặc thông báo tới muộn. Thiết kế Pay2S
API tốt là thiết kế vẫn giải thích được đơn đang ở đâu khi một bước chưa có câu 
trả lời.

Theo [tài liệu API Pay2S](https://mail.hoadontudong.com.vn/tai-lieu-pay2s/), các
giao diện tạo link và gửi kết quả phục vụ những vai trò khác nhau. Trên hoadontudong.
com.vn, chúng được đặt vào kiến trúc của merchant: đơn giữ ở database, adapter thực
hiện giao tiếp và nghiệp vụ quyết định bước tiếp theo. Tách các trách nhiệm từ đầu
giúp thay đổi cách ký hoặc phiên bản dữ liệu mà không phải viết lại toàn bộ bán 
hàng.

## Pay2S API là gì trong kiến trúc thanh toán?

Phần request chỉ an toàn khi chữ ký được tạo đúng; xem thêm [cách ký HMAC cho giao dịch Pay2S](https://hoadontudong.com.vn/cong-thanh-toan-tu-dong-pay2s-chu-ky-hmac/).

![Pay2S API là gì trong kiến trúc thanh toán? - ảnh minh họa Pay2S](https://hoadontudong.
com.vn/wp-content/uploads/2026/10/pay2s-pay2s-api-la-gi-va-cach-hoat-dong-h2-01-
1.png)

Pay2S API là gì trong kiến trúc thanh toán?

Một luồng tối thiểu có ba cuộc trao đổi: backend tạo yêu cầu, trình duyệt mở checkout
và Pay2S gửi kết quả tới endpoint của merchant. Ba việc này không nằm trong một 
transaction duy nhất. Vì vậy, ứng dụng phải lưu trạng thái trung gian và có đường
phục hồi khi một cuộc trao đổi thất bại. Việc người mua nhìn thấy trang thành công
không thay thế được phần xác minh, lưu trữ ở server.

Endpoint tạo Collection Link là POST `https://payment.pay2s.vn/v1/gateway/api/create`.
Backend cần xây request từ đơn đã lưu, gồm định danh merchant, mã yêu cầu, mã đơn,
số tiền, thông tin tài khoản nhận và các URL theo đặc tả. Không lấy toàn bộ payload
từ trình duyệt rồi ký ngay. Giá và quyền thanh toán phải được kiểm tra tại server
để người mua không thể tự thay đổi số phải thu.

 * Service đơn hàng xác định mã đơn và số phải thu.
 * Adapter chịu trách nhiệm serialize, ký và giao tiếp HTTP.
 * Receiver xác minh message rồi đối chiếu database.
 * Tác vụ sau thanh toán xử lý từ một quyết định đã lưu bền vững.

![Pay2S API là gì trong kiến trúc thanh toán? - ảnh minh họa Pay2S](https://hoadontudong.
com.vn/wp-content/uploads/2026/10/pay2s-pay2s-api-la-gi-va-cach-hoat-dong-h2-02-
1.png)

Pay2S API là gì trong kiến trúc thanh toán?

Khi gọi `https://payment.pay2s.vn/v1/gateway/api/create`, lưu một bản ghi lần thử
trước khi gửi để giữ dấu vết nếu phản hồi bị mất. Bản ghi nên cho biết đơn gốc, 
cấu hình merchant, thời điểm, mã yêu cầu và trạng thái giao tiếp. Sau khi nhận response,
bổ sung kết quả thực tế thay vì ghi đè lịch sử. Nếu cần hỗ trợ, đội vận hành sẽ 
phân biệt được chưa gọi, gọi lỗi và đã tạo được link.

Mã `HTTP 200` chỉ nói về việc HTTP request được xử lý ở tầng giao tiếp. Backend 
còn phải đọc kết quả nghiệp vụ của thao tác create. Ngay cả khi create thành công,
trạng thái phù hợp vẫn là chờ khách trả, bởi payUrl là nơi để tiếp tục thanh toán.
Đưa đơn sang paid tại bước này sẽ khiến những đơn chưa chuyển tiền có thể được giao
hoặc cấp quyền.

## Những trường dữ liệu cần phân biệt

![Những trường dữ liệu cần phân biệt - ảnh minh họa Pay2S](https://hoadontudong.
com.vn/wp-content/uploads/2026/10/pay2s-pay2s-api-la-gi-va-cach-hoat-dong-h2-03-
1.png)

Những trường dữ liệu cần phân biệt

Đừng dùng `HTTP 200` làm một cờ chung cho toàn bộ vòng đời. orderId định danh đơn
merchant; requestId của request create giúp truy vết lần gọi theo contract. IPN 
có requestId nội bộ của Pay2S nên không được mặc định nó bằng mã đã gửi khi create.
Phần mapping kết quả cần dựa vào các trường được đặc tả và đơn đã lưu, đặc biệt 
là orderId có xác thực.

Phản hồi có thể cung cấp payUrl, dữ liệu QR và orderInfo thực tế cùng các trường
kết quả. Lưu những giá trị cần dùng cho xác nhận về sau, nhất là khi luồng V2 sinh
orderInfo phục vụ QR và IPN. Tách thời điểm gửi, thời điểm nhận response và thời
điểm nhận callback. Nhờ đó, một sự cố chậm được xác định ở đúng lớp thay vì quy 
mọi khoảng chờ thành lỗi ngân hàng.

**Điểm cần nhớ:** Giữ `Secret Key` trong module backend. Một kết quả create thành
công mới cung cấp đường thanh toán; receiver vẫn cần xác minh và đối chiếu trước
khi paid.

## Luồng create và trả payUrl

Sau khi tạo link, backend cần xử lý callback; tham khảo [cách tiếp nhận và xác minh IPN Pay2S](https://hoadontudong.com.vn/cong-thanh-toan-tu-dong-pay2s-ipn/).

Luồng create nên trả về cho frontend dữ liệu đủ để mở checkout, đồng thời giữ bản
đầy đủ cần thiết tại backend. Không tự chỉnh host, token hoặc query của payUrl. 
Khi response lỗi hoặc không nhận được, frontend cần hiển thị trạng thái có thể thử
lại theo chính sách của ứng dụng, còn backend kiểm tra hồ sơ cũ. Tự tạo orderId 
mới ngay sau timeout có thể làm một đơn phát sinh nhiều yêu cầu riêng.

Với Collection Link V2, `extraData` mang metadata đã mã hóa Base64 và tham gia chữ
ký V2. Xây dữ liệu một lần rồi dùng nguyên giá trị cho payload và tính chữ ký. Nếu
frontend dựng JSON còn adapter tự dựng lại theo cách khác, chuỗi thực gửi có thể
lệch chuỗi đã ký. Ranh giới rõ giữa dữ liệu nghiệp vụ và việc serialize giúp tránh
lỗi khó tái hiện này.

## redirectUrl, ipnUrl và trạng thái đơn

redirectUrl phục vụ hành trình quay lại của khách; ipnUrl phục vụ kết quả server
tới server. Dù `extraData` chứa thông tin chứng từ, hai kênh ấy vẫn giữ vai trò 
riêng. Trang kết quả nên đọc trạng thái đơn từ backend và cho phép trạng thái đang
kiểm tra. Người mua đóng tab không được làm mất cơ hội cập nhật thanh toán, và refresh
trang không được gây thêm tác động nghiệp vụ.

Chữ ký `HMAC` giúp kiểm tra các trường nằm trong công thức của từng loại thông báo.
Sau khi xác minh, backend vẫn phải kiểm tra kết quả, mã đơn và số tiền so với database.
Redirect có chữ ký không nên trở thành đường cập nhật paid độc lập. Nếu IPN đến 
trước browser, trang kết quả đọc được trạng thái đã lưu; nếu tới sau, giao diện 
có thể chờ hoặc tải lại trạng thái.

**Giới hạn:** HTTP, kết quả create và trạng thái thanh toán là ba lớp khác nhau.
Khi gỡ lỗi, ghi rõ kết luận nào đã có bằng chứng và lớp nào còn chờ.

## Thiết kế adapter Pay2S ở backend

Nếu muốn rút ngắn phần code tích hợp, xem [hướng dẫn dùng SDK Pay2S cho Node.js và PHP](https://hoadontudong.com.vn/cong-thanh-toan-tu-dong-pay2s-sdk-node-php/).

Adapter nên gom xử lý cấu hình kết nối, serialize, tính `HMAC`, gọi HTTP và đọc 
response theo contract. Nó trả về kết quả có cấu trúc cho service thanh toán, không
tự giao hàng hay phát hành hóa đơn. Nhờ vậy, khi thay phiên bản chữ ký hoặc sửa 
xử lý timeout, đội phát triển có thể kiểm tra lớp giao tiếp mà không chạm vào quyết
định nghiệp vụ của toàn bộ hệ thống.

`Access Key` và `Secret Key` cần được cấp theo môi trường và lưu trong hệ thống 
cấu hình có kiểm soát. Log nên chứa mã đơn, mã yêu cầu, kết quả giao tiếp và thời
gian, đồng thời che bí mật hoặc dữ liệu tài khoản không cần thiết. Tránh ghi toàn
bộ request vào công cụ quan sát mặc định: dữ liệu hữu ích cho truy vết không đồng
nghĩa mọi trường đều nên xuất hiện trong log.

## Checklist nghiệm thu API

Nghiệm thu cả đường cấp, thay và thu hồi `Access Key`, `Secret Key`. Một bản build
thử không được dùng nhầm bộ kết nối thật, còn endpoint production phải đọc đúng 
cấu hình đã phê duyệt. Kiểm tra thêm quyền truy cập trang log và công cụ gửi lại
thông báo. Những công cụ này có thể làm chạy lại luồng nhận tiền nên cần quyền phù
hợp cùng dấu vết người thao tác.

Bộ thử cho `https://payment.pay2s.vn/v1/gateway/api/create` cần bao gồm request 
hợp lệ, thiếu dữ liệu, chữ ký sai, timeout và người dùng nhấn lại. Ở chiều nhận,
thử sai đơn, lệch tiền, thông báo lặp và hai callback đồng thời. Kết quả cần được
kiểm tra trong database cùng tác vụ phía sau; một response đẹp ở công cụ gọi API
chưa chứng minh đơn không bị cập nhật hai lần.

## Ví dụ kỹ thuật an toàn cho Pay2S là gì

Mẫu dưới chỉ minh họa một phần request HTTP, chưa phải payload đầy đủ để gọi thành
công. `Secret Key` phải ở backend và chữ ký phải theo đúng phiên bản tài liệu. Khi
triển khai, bổ sung các trường bắt buộc từ cấu hình merchant cùng đơn đã kiểm tra.
Không sao chép phần minh họa rồi đoán trường còn thiếu bằng cách thử ngẫu nhiên 
trên môi trường thật.

    ```language-http
    POST https://payment.pay2s.vn/v1/gateway/api/create
    Content-Type: application/json; charset=UTF-8

    { "orderId": "ORDER_DEMO_001", "amount": 110000, "requestType": "pay2s", "signature": "<SIGNATURE>" }
    ```

Sau khi tạo link, receiver cần xác minh thông báo rồi cập nhật dưới transaction 
hoặc cơ chế tương đương để bảo vệ một lần xử lý. Nếu đơn đã được xác nhận bởi cùng
kết quả hợp lệ, trả ACK theo contract mà không phát sinh giao hàng nữa. Với tác 
vụ tốn thời gian, lưu yêu cầu bền vững rồi xử lý riêng; lỗi email không nên khiến
callback thanh toán bị thực hiện lại toàn bộ.

## Quy trình triển khai Pay2S là gì

 1. Vẽ `sequence` diagram từ checkout tới IPN.
 2. Chuẩn hóa orderId và requestId trong database.
 3. Tạo module ký request ở backend.
 4. Gọi create bằng dữ liệu server đã kiểm tra.
 5. Lưu payUrl và response trước khi trả kết quả cho frontend.
 6. Xác minh IPN và đối chiếu đơn trong transaction.
 7. ACK đúng JSON sau khi lưu bền vững.
 8. Theo dõi lỗi và retry bằng mã đơn gốc.

Thứ tự triển khai trong danh sách giúp giữ bằng chứng trước mỗi thao tác mạng. Khi
kiểm tra một đơn lỗi, bắt đầu từ mã đơn gốc và lần thử đã lưu, rồi theo request,
response tới callback. Không dựng lại dữ liệu đơn hiện tại để suy ra payload quá
khứ, bởi giá hoặc thông tin hàng có thể đã đổi. Dữ liệu audit cần phản ánh đúng 
thời điểm yêu cầu được tạo.

Tình huống giả định: create bị timeout nhưng hệ thống bên nhận đã tạo link. Nếu 
ứng dụng tự đổi mã đơn rồi gửi lại, khách có thể thấy hai luồng cho một lần mua.
Giữ mã gốc và tra cứu theo khả năng được tài liệu hoặc hỗ trợ xác nhận sẽ hạn chế
rủi ro này. Quy trình phục hồi cần phân biệt không có response với kết luận đơn 
chưa tồn tại.

## Câu hỏi thường gặp về Pay2S là gì

### Pay2S API có phải REST API không?

Các tài liệu sử dụng HTTP và dữ liệu JSON với phương thức quy định cho từng endpoint.
Khi viết client, tuân thủ contract cụ thể về header, kiểu dữ liệu và chữ ký. Tên
gọi REST không quyết định được một request đúng; payload thực gửi cùng phản hồi 
nghiệp vụ mới là những thứ cần đối chiếu khi gỡ lỗi.

### requestId có thay orderId không?

Không. Hai mã phục vụ hai phạm vi khác nhau. Giữ quan hệ giữa đơn và lần thử create
trong database, đồng thời đọc ý nghĩa requestId ở từng loại message. Đặc biệt, requestId
trong IPN là mã nội bộ phía Pay2S theo tài liệu hiện hành; đừng dùng phép so bằng
với requestId create để loại bỏ một thông báo đúng.

### Có nên lưu payUrl không?

Nên lưu payUrl cùng phản hồi cần thiết để hiển thị lại hoặc hỗ trợ tra cứu theo 
chính sách lưu trữ. Giữ nguyên URL được trả về và kiểm soát ai có thể xem. Không
xem việc có payUrl là bằng chứng đã trả, cũng không dùng nó thay các trường định
danh phục vụ xác minh callback.

### IPN có thể gửi lại không?

Có. Receiver cần chịu được cùng kết quả gửi lại và gửi đồng thời. Kiểm tra chống
trùng phải nằm ở dữ liệu bền vững hoặc transaction, bởi một biến trong bộ nhớ không
bảo vệ được nhiều tiến trình. Lần gửi hợp lệ đã xử lý vẫn cần được phản hồi theo
contract để tránh tiếp tục retry không cần thiết.

### Tài liệu có đủ để tích hợp `Production` ngay không?

Tài liệu xác định cách giao tiếp, còn khả năng chạy thật phải được xác nhận bằng
cấu hình và bộ thử của merchant. Kiểm tra quyền, credential, endpoint nhận, lưu 
trạng thái và đường phục hồi. Nên chạy phạm vi nhỏ trước rồi theo dõi đơn thật xuyên
suốt, thay vì xem một lần gọi demo thành công là nghiệm thu hoàn tất.

## Kết luận

Pay2S API dễ tích hợp hơn khi mỗi trao đổi có một vai trò rõ và mỗi lần thử có hồ
sơ riêng. Hãy giữ dữ liệu đơn ở server, lưu phản hồi thực tế và để receiver xác 
minh kết quả trước khi kích hoạt nghiệp vụ. Với nền tảng đó, đội phát triển có thể
sửa một lỗi giao tiếp mà vẫn bảo toàn lịch sử thanh toán và những tác động đã thực
hiện.

## Đọc tiếp theo nhu cầu trong cụm Pay2S

 * [Tổng quan giải pháp thanh toán trực tuyến tự động](https://hoadontudong.com.vn/pay2s-la-gi-tong-quan-giai-phap-thanh-toan/)
 * [Pay2S có phải là cổng thanh toán không?](https://hoadontudong.com.vn/pay2s-co-phai-cong-thanh-toan-khong/)
 * [Luồng thanh toán từ lúc tạo đơn đến khi xác nhận](https://hoadontudong.com.vn/pay2s-hoat-dong-nhu-the-nao/)
 * [Pay2S hỗ trợ thanh toán QR và ngân hàng như thế nào?](https://hoadontudong.com.vn/pay2s-ho-tro-thanh-toan-qr-ngan-hang/)
 * [Pay2S có an toàn không và cần bảo mật ra sao?](https://hoadontudong.com.vn/pay2s-co-an-toan-khong/)