Cổng Thanh Toán Tự động Pay2S: Dùng SDK Node.js Và PHP Thế Nào?

Cổng thanh toán tự động Pay2S: Dùng SDK Node.js và PHP thế nào? - ảnh minh họa Pay2S

Tự viết hàm ký và mã hóa metadata làm tăng phần việc mà đội phát triển phải kiểm tra. SDK giúp đóng gói một số thao tác đó, nhưng không thay thế model đơn hàng hoặc transaction của ứng dụng. Muốn tích hợp nhanh mà vẫn kiểm soát được kết quả, cần biết thư viện làm đến đâu và phần nào vẫn thuộc backend merchant.

Bài viết trên hoadontudong.com.vn đi từ cài đặt đến tạo thanh toán, kiểm tra IPN và bàn giao vận hành. Giới thiệu API Pay2S mô tả phạm vi chung; phiên bản cùng cách sử dụng được đối chiếu tại tài liệu SDK Collection Link V2.

`SDK` trong cổng thanh toán tự động Pay2S

SDK hiện đóng gói tạo thanh toán V2 và kiểm tra IPN cho backend Node.js/TypeScript hoặc PHP. Đội triển khai có thể xem vị trí API trong hệ thống bán hàng trước khi chọn nơi gọi thư viện.

Hãy xem SDK như một dependency nằm sau lớp nghiệp vụ. Controller nhận yêu cầu mua, dịch vụ đơn hàng xác định dữ liệu, rồi lớp tích hợp gọi thư viện. Cách tách này giúp thay đổi transport hoặc nâng phiên bản mà không sửa toàn bộ quy tắc bán hàng.

Trước khi đưa SDK vào ứng dụng đang chạy, kiểm tra cách quản lý lỗi, môi trường và dependency của dự án. Một ví dụ độc lập hoạt động chưa chứng minh nó phù hợp cơ chế transaction hoặc queue hiện có. Tái sử dụng các phần nền đã ổn định thường giúp bàn giao dễ hơn.

SDK cũng cần được quản lý phiên bản như các dependency khác: biết file nào đã cài, lấy từ nguồn nào và cách quay lại bản đã thử. Không thay file trực tiếp trên server mà bỏ qua quy trình build, vì những môi trường khác nhau có thể vô tình dùng các bản khác nhau.

Phần SDK không hiểu chính sách giá hoặc nghĩa vụ kế toán của merchant. Dữ liệu đưa vào cần được tạo từ đơn đã kiểm tra, không lấy tổng tiền người dùng gửi lên rồi coi việc gọi thư viện là bước xác nhận tính đúng.

Cài `SDK` Node.js/TypeScript hoặc PHP

Tại thời điểm rà soát, SDK phiên bản 0.1.0 được phân phối qua file tải, chưa phát hành trên npm hoặc Packagist. Tài liệu nêu Node.js từ 20, PHP từ 8.1 cùng các extension cần thiết. Khi cài, dùng hướng dẫn của đúng phiên bản thay vì suy tên gói để tải từ nguồn khác.

Trước khi thử, chuẩn bị phạm vi credential của tài khoản: Access Key khác vai trò Secret Key. Không lưu chúng trong một object công khai dùng chung với frontend. Môi trường test và môi trường triển khai cần được quản lý rõ để tránh mang một cấu hình thử sang luồng khách thật.

Cấu hình bí mật: Secret Key được cung cấp tại backend bằng cơ chế cấu hình của dự án. Không commit giá trị thật hoặc đưa vào bundle trình duyệt.

Nếu sử dụng pipeline triển khai, đưa bước cài dependency và chạy bộ thử vào cùng quy trình build. Kiểm tra quyền đọc file cấu hình của tiến trình chạy ứng dụng, đồng thời bảo đảm lỗi khởi tạo không làm in khóa ra console.

Cấu hình credential backend

Khi khởi tạo SDK, ứng dụng cung cấp Partner Code, Access Key và Secret Key theo đúng bộ khóa. Không ghép khóa từ nhiều cửa hàng hoặc môi trường. Việc lựa chọn credential cần được kiểm soát bởi cấu hình backend, không do người mua truyền lên.

SDK không tự tạo credential, liên kết ngân hàng hoặc thiết lập hóa đơn cho tài khoản. Những điều kiện này phải được kiểm tra trước bài thử đầu. Nếu cấu hình nền chưa sẵn sàng, sửa code gọi lặp lại thường chỉ tạo thêm lỗi khó phân biệt.

Đối với metadata, SDK nhận object JSON chưa Base64 và tạo extraData theo contract V2. Vì vậy, lớp gọi không nên mã hóa sẵn rồi chuyển một chuỗi thay cho object. Quy tắc dữ liệu chi tiết được mô tả ở Collection Link V2.

Nên kiểm tra cấu hình khi ứng dụng khởi động và báo lỗi thiếu biến theo tên trường, không theo giá trị bí mật. Cách này giúp triển khai phát hiện sai cấu hình sớm, trước khi khách tạo đơn đầu tiên.

Tạo payment và lưu kết quả

Trước khi gọi SDK, lưu đơn cùng các mã cần thiết ở database. Tiền và dòng hàng lấy từ dữ liệu server; không dùng thư viện để thay bước tính tổng nghiệp vụ. extraData được dựng từ metadata, nhưng tổng thanh toán vẫn phải khớp dữ liệu của đơn.

Response tạo thanh toán cần được lưu trước khi trả link cho trình duyệt. Với V2, orderInfo thực tế từ response là dữ liệu dùng để đối chiếu; không mặc định nó bằng giá trị gửi trong request. Giữ payUrl cùng các tham chiếu để người hỗ trợ tìm lại lần thanh toán.

Nếu SDK báo lỗi transport hoặc timeout, trạng thái kết quả có thể chưa rõ. Giữ mã đơn gốc và kiểm tra theo luồng hỗ trợ; không tạo một lần mua mới chỉ để bỏ qua lỗi. Dữ liệu lỗi cần có loại, thời điểm và tham chiếu, không chỉ một thông báo chung cho khách.

Verify IPN và assertPaidIpn

verifyIpn trong SDK kiểm tra chữ ký và danh tính bộ khóa; assertPaidIpn kiểm tra thêm kết quả thành công, mã đơn, tiền và orderInfo khi cung cấp. Giá trị expected phải lấy từ database, không sao chép từ chính payload cần kiểm tra.

Ứng dụng vẫn phải tìm và khóa đúng đơn, cập nhật có điều kiện rồi ACK sau commit. SDK không lưu trạng thái hoặc chống replay bằng database. Hai thông báo giống nhau có thể cùng hợp lệ; transaction phía merchant quyết định tác động chỉ xảy ra một lần.

Đối chiếu luồng IPN đầy đủ và contract IPN khi nối handler. Những đoạn gọi hàm thư viện không tự cung cấp req/res, model đơn hay cơ chế phục hồi cho ứng dụng.

Tình huống giả định: chữ ký đúng nhưng số tiền khác nghĩa vụ đã lưu. Handler cần giữ hồ sơ kiểm tra và không cấp dịch vụ. Một hàm xác minh trả true chỉ giải quyết lớp toàn vẹn dữ liệu, chưa giải quyết toàn bộ điều kiện nghiệp vụ.

`SDK` không làm thay phần nào?

SDK không thay người thiết kế trạng thái đơn, quyền truy cập hoặc chính sách giao hàng. Những quyết định này nên nằm ở lớp nghiệp vụ để hệ thống còn giải thích được một đơn sau nhiều lần thử kết nối.

Cũng không để SDK trở thành lý do bỏ qua queue và theo dõi tác vụ. Nếu đơn đã trả nhưng dịch vụ hóa đơn tạm lỗi, cần thử lại việc còn thiếu mà không tạo thêm thanh toán. Dữ liệu tiền, giao hàng và hóa đơn có thể liên quan nhưng không nên dùng chung một nhãn hoàn tất.

Trước khi nâng SDK, chạy lại các fixture và bài thử tích hợp quan trọng. Có thể đọc các contract chữ ký để biết thay đổi nào cần kiểm tra. Giữ bản đã nghiệm thu giúp đội triển khai có phương án quay lại khi phát hiện khác biệt.

Ví dụ kỹ thuật an toàn cho Cổng thanh toán tự động Pay2S

Đoạn dưới minh họa lời gọi từ backend, không phải một chương trình độc lập. Các biến đầu vào, instance và dữ liệu đơn phải được ứng dụng cung cấp. Secret Key nằm trong cấu hình, không đi qua request từ người mua.

const result = await pay2s.createPayment({
  orderId, requestId, amount, bankAccounts, redirectUrl, ipnUrl, metadata
});
// Lưu result.payUrl và result.orderInfo trước khi trả URL cho browser

Trước lời gọi, lưu dữ liệu đối chứng của đơn. Sau lời gọi, kiểm tra và lưu kết quả, rồi mới đưa link cho frontend. Nếu đoạn ghi database lỗi, không báo người dùng rằng toàn bộ luồng đã sẵn sàng; cần giữ trạng thái phù hợp và cách tiếp tục xử lý.

Quy trình triển khai Cổng thanh toán tự động Pay2S

Thực hiện theo từng lớp: cài dependency, cấu hình backend, nối model đơn, tạo thanh toán và tiếp nhận IPN. Thử từng lớp với dữ liệu giả trước khi nối tác vụ thật. Kết quả cuối cần kiểm tra bằng database và nghiệp vụ, không chỉ bằng log của hàm tạo.

Với lỗi trả về, phân loại đầu vào, transport, response và kết quả nghiệp vụ để chọn hướng xử lý. Không thử lại dữ liệu invalid mà chưa sửa. Với kết quả chưa xác định, giữ tham chiếu và đối soát thay vì kết luận ngay rằng đơn chưa được tạo.

Câu hỏi thường gặp về Cổng thanh toán tự động Pay2S

`SDK` có chạy ở frontend không?

Không dùng ở frontend vì cần Secret Key. Trình duyệt gọi endpoint của merchant; backend quản lý cấu hình, dữ liệu đơn và việc gọi thư viện.

`SDK` có tự retry không?

Phiên bản được đối chiếu không tự retry. Ứng dụng phải quyết định theo loại lỗi và trạng thái đã biết, giữ mã đơn thay vì tạo mã mới tùy tiện.

verifyIpn có đủ để paid không?

Chưa. Còn bước đối chiếu nghĩa vụ, kiểm tra kết quả và transaction chống trùng. Không đặt việc giao hàng trực tiếp sau một kết quả xác minh chữ ký mà bỏ qua trạng thái đơn.

Có thể dùng PHP không?

Có bản PHP theo tài liệu. Cần kiểm tra runtime, extension và cách cài của dự án, sau đó chạy bộ thử phù hợp trước khi nối dữ liệu thật.

`SDK` có phát hành trên npm không?

Tài liệu phiên bản 0.1.0 nêu phân phối bằng file tải và chưa publish trên npm. Kiểm tra lại trang chính thức khi cài hoặc nâng phiên bản để dùng đúng hướng dẫn.

Kết luận

Thư viện giảm phần lặp của tích hợp, còn độ tin cậy đến từ cách ứng dụng giữ đơn, đối chiếu kết quả và phục hồi tác vụ. Dùng đúng ranh giới giúp đội phát triển nhận được lợi ích mà không bỏ sót trách nhiệm tại database.

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

Bộ tiêu chí nghiệm thu Cổng thanh toán tự động Pay2S

Kiểm tra create thành công, dữ liệu invalid, lỗi mạng và response không mong đợi. Với IPN, thử chữ ký sai, số tiền lệch và gửi đồng thời cùng kết quả. Điều kiện đạt là dữ liệu sai không gây tác động, bản hợp lệ chỉ tạo một nghiệp vụ và lỗi nội bộ còn đường phục hồi.

Thử thêm khi dịch vụ sau thanh toán gián đoạn. Đơn đã trả vẫn giữ đúng trạng thái; tác vụ còn thiếu được theo dõi riêng. Đây là bằng chứng quan trọng hơn việc chỉ chạy được một lời gọi trong ví dụ.

Bảng kiểm trước khi mở rộng Cổng thanh toán tự động Pay2S

Trước khi bật Production, lưu phiên bản dependency, nguồn file, cấu hình đã thử và hướng dẫn đổi khóa. Kiểm tra quyền xem log, quyền sửa cấu hình cùng đầu mối nhận cảnh báo. Người vận hành cần tìm được đơn từ mã khách cung cấp mà không đọc mã nguồn.

Khi bàn giao, yêu cầu đội tiếp nhận xử lý một lỗi mẫu và một IPN gửi lại. Nếu họ xác định được bước đang chờ và thao tác tiếp theo, tích hợp đã có khả năng vận hành ngoài môi trường của người viết code.

Leave your commentCancel reply

Bạn phải đăng nhập để gửi bình luận.