Thực hành tích hợp

Quy trình tích hợp nền tảng bán mã chi tiết: từ cấu hình sản phẩm đến nghiệm thu callback thanh toán và giao hàng tự động

Sau khi chuẩn bị sản phẩm, tên miền và phần mềm bán mã, làm thế nào để khách hàng nhận đúng mã cấp phép của mình sau khi trả tiền? Bài này trình bày chuẩn bị, phát triển, kiểm thử tích hợp và triển khai theo trình tự một lần tích hợp đầy đủ. Ví dụ dành cho hàng số do bạn sở hữu hoặc được phép phân phối; tên trường và mã giả chỉ giải thích quan hệ ánh xạ, không phải tài liệu API thực tế của 稳付pay.

Chuẩn bị tích hợp 稳付pay: Vui lòng xem Tài liệu phát triển thu hộ và dùng các trường thực tế để hoàn tất ký MD5, tạo đơn, tra cứu và xử lý callback. Gateway và khóa của đơn vị kinh doanh được kỹ thuật viên cung cấp riêng; API chi hộ hiện chưa mở.
Mục lục bài viết

Bước 1: làm rõ trách nhiệm riêng của sản phẩm, thanh toán và giao hàng

Trước hết hãy vạch ba ranh giới: nền tảng bán mã quản lý sản phẩm, đơn và giao hàng; dịch vụ thanh toán nhận diện giao dịch và thông báo; quy trình quyết toán chuyển khoản phải trả cho đơn vị kinh doanh theo thỏa thuận. Thanh toán thành công, sản phẩm đã giao và tiền quyết toán đã nhận là ba sự kiện, không dùng chung một nút “hoàn thành”.

  1. Chuẩn bị sản phẩmXác định SKU, tồn kho và quy tắc hậu mãi
  2. Tạo thanh toánMáy chủ cố định số tiền đơn và lần thử thanh toán
  3. Xác minh thanh toánKết hợp callback đáng tin cậy với tra cứu từ máy chủ
  4. Giao sản phẩm tự độngCấp hàng bằng giao dịch và thử lại tác vụ bền vững
Giao sản phẩm dựa trên kết quả thanh toán đáng tin cậy; tiến độ quyết toán cho đơn vị kinh doanh được ghi nhận và kiểm tra riêng.

Ví dụ khi bán mã kích hoạt phần mềm do mình phát triển, đơn có thể đã thanh toán, đang chờ giao hàng, đồng thời chưa vào đợt quyết toán hiện tại. Nếu khách đã trả tiền nhưng mãi không nhận được hàng vì hàng đợi quyết toán chưa xong, hệ thống thường đã gắn sai các luồng này với nhau.

Bước 2: chuẩn bị sản phẩm, tồn kho và môi trường vận hành

Cấp mã sản phẩm ổn định cho từng biến thể, làm rõ thời hạn cấp phép, phiên bản áp dụng, số lượng mua tối đa, hình thức giao và liên hệ hậu mãi. Giá hiển thị trên nền tảng và giá tính ở máy chủ phải dùng cùng nguồn dữ liệu đáng tin cậy; không để trình duyệt tự quyết số tiền phải trả.

Phân biệt tồn kho có thể bán, đã giữ, đã cấp và đã giao. Việc giữ hàng phải có hạn dùng và điều kiện giải phóng nguyên tử; thời gian chờ thanh toán cần phối hợp với thời gian giữ hàng. Không được chỉ vì tác vụ hết hạn chạy mà đổi đơn đã xác nhận thanh toán thành chưa trả tiền rồi giải phóng hàng vô điều kiện.

Môi trường vận hành ít nhất cần HTTPS hợp lệ, cấu hình kiểm thử riêng, cơ sở dữ liệu đáng tin cậy, tiến trình tác vụ bền vững và phương án sao lưu, khôi phục. Chỉ người có quyền với đơn tương ứng được xem mã; log truy cập và stack trace không được ghi đầy đủ mã, khóa riêng hay khóa thanh toán.

Bước 3: xác nhận khả năng tích hợp trước rồi lập bảng đối chiếu trường

Xác nhận lần lượt quy chuẩn thực tế: xác thực danh tính, nội dung được ký, yêu cầu giữ thông điệp gốc, khả năng truy vấn, trạng thái thanh toán, phản hồi thông báo, cách thử lại, múi giờ và độ chính xác số tiền. Nếu plugin có sẵn không phù hợp, hãy sửa lớp thích ứng; đổi mẫu trang không thay thế được tích hợp thanh toán.

Thông tin nghiệp vụ nội bộĐiểm kiểm tra khi tích hợpMục đích lưu
Mã đơn của đơn vị kinh doanhĐộ dài, ký tự và phạm vi duy nhấtKết nối xuyên suốt sản phẩm, thanh toán và giao hàng
Mã lần thử thanh toánCách nhận diện thử lại trong cùng đơnTránh tạo đơn trùng sau khi hết thời gian chờ
Số tiền phải trả, loại tiềnĐơn vị, độ chính xác và trạng thái cho phépNgăn trả thiếu hoặc sai loại tiền
Mã giao dịch kênh, mã sự kiệnCó hay không, phạm vi và cách truy vấnGán thanh toán và loại bỏ thông báo trùng
Địa chỉ callback, địa chỉ quay vềKhác biệt giữa thông báo máy chủ và chuyển trang trình duyệtTách xác nhận nghiệp vụ khỏi hiển thị tiến độ
Mạng, tài sản, địa chỉ nhậnMạng và định danh tài sản tương ứng với USDTTránh nhận nhầm giao dịch khác chuỗi hoặc token cùng tên

Tên trong bảng chỉ là khái niệm nghiệp vụ; trường và cách ký cuối cùng theo tài liệu thực tế do hai bên xác nhận. Không sao chép bài này làm định dạng yêu cầu.

Bước 4: tạo đơn ở máy chủ, lưu từng lần thử thanh toán

Sau khi người dùng chọn sản phẩm, máy chủ đọc lại giá, kiểm tra tồn kho và giới hạn mua, tạo mã đơn của đơn vị kinh doanh rồi lưu bản chụp số tiền, loại tiền và hạn dùng. Lưu bản ghi lần thử thanh toán trước khi gọi dịch vụ để vẫn tìm được “lần yêu cầu này” sau khi mạng gián đoạn.

Yêu cầu tạo đơn hết thời gian chờ chỉ có nghĩa chưa nhận được câu trả lời rõ ràng, không có nghĩa dịch vụ thanh toán chưa tạo thành công. Ưu tiên kiểm tra bằng mã đơn gốc của đơn vị kinh doanh hoặc điều kiện truy vấn đã thỏa thuận; chỉ thử lại an toàn với cùng nội dung nghiệp vụ và định danh lũy đẳng đã thống nhất nếu quy chuẩn của nhà cung cấp hỗ trợ. Tham khảo Giải thích về yêu cầu lũy đẳng của Stripe để hiểu cơ chế này, không mặc định mọi kênh đều hỗ trợ cùng một header yêu cầu.

Khi khách chọn lại phương thức thanh toán, giữ quan hệ sở hữu của lần thử cũ để thông báo cũ không bị gán sang đơn kênh mới. Nếu có hai khoản thanh toán thật, ghi nhận riêng và xử lý trả tiền trùng; không giao hai phần hàng để che vấn đề.

Bước 5: hiển thị hướng dẫn thanh toán, trang quay về chỉ hiển thị tiến độ

Chuyển liên kết thanh toán hoặc tham số cần thiết do máy chủ nhận được cho giao diện, hiển thị mã đơn, số tiền phải trả, hạn dùng và đầu mối hậu mãi. Khi tích hợp USDT, còn cần hiển thị đúng mạng và địa chỉ nhận, không chỉ ghi “USDT” rồi để khách đoán mạng.

Khách quay lại website sau thanh toán, đóng trang hay đổi thiết bị đều không được làm thay đổi quy trình xác nhận của máy chủ. Trang quay về chỉ tra cứu tiến độ đơn từ máy chủ của mình, không giao sản phẩm dựa trực tiếp vào tham số success trong URL. Trang chi tiết đơn và tra cứu mã cần xác minh đăng nhập hoặc thông tin xác thực truy cập đơn đủ mạnh.

Hướng dẫn tích hợp thanh toán bên thứ ba của OWASP nhấn mạnh xác minh ở máy chủ và đối chiếu số tiền. Các lời nhắc “đã gửi”, “đang xác nhận” cũng phải phân biệt với “đã thanh toán”, tránh báo nhầm giao dịch chưa được xác nhận thành thành công.

Bước 6: xác minh chữ ký, tra cứu và kiểm tra trường nghiệp vụ ở máy chủ

Khi nhận thông báo, xác minh chữ ký theo quy chuẩn thực tế và kiểm tra đơn vị kinh doanh sở hữu, đơn, số tiền, loại tiền cùng trạng thái thành công. Với quy chuẩn yêu cầu request body nguyên bản, phải giữ byte gốc trước khi phân tích hoặc viết lại. Chữ ký hợp lệ vẫn không thay thế kiểm tra trường nghiệp vụ.

Tùy phương án tích hợp, dùng tra cứu được xác thực từ máy chủ để xác nhận thanh toán, đặc biệt khi thiếu callback, tạo đơn hết thời gian chờ hoặc xung đột trạng thái. Nếu truy vấn tạm không dùng được, giữ trạng thái chờ xác nhận và lên lịch thử lại; không coi lỗi mạng là “đã thất bại” hay tự động giao hàng theo ảnh chụp thanh toán.

Tài liệu Webhook của Stripe trình bày xác minh thông báo, gửi trùng và sai thứ tự. Việc xác nhận đã nhận thông báo phải tuân thủ quy chuẩn và chỉ thực hiện sau khi sự kiện cùng trách nhiệm xử lý tiếp theo đã được lưu bền vững. Nếu phản hồi trước rồi chỉ giữ tác vụ trong bộ nhớ, khởi động lại tiến trình có thể làm mất đơn.

Bước 7: ghi nhận thanh toán và tồn kho trong giao dịch, giao hàng bất đồng bộ sau commit

Sự kiện thanh toán, cấp tồn kho và tác vụ giao hàng phải được lưu cùng nhau. Dùng khóa hàng hoặc cập nhật nguyên tử có điều kiện trạng thái cho cùng đơn; đặt ràng buộc duy nhất với phạm vi thích hợp cho sự kiện, giao dịch và giao sản phẩm. Cấp hàng cũng cần quan hệ sở hữu duy nhất theo dòng đơn và số lượng mua; xử lý lặp phải trả về kết quả cấp ban đầu, không lấy thêm mã chỉ vì tác vụ giao chưa xong. Chỉ “kiểm tra đã có chưa rồi ghi” không ngăn được tranh chấp đồng thời.

# Protocol mapping example, not a runnable payment integration.
event = verify_using_confirmed_protocol(raw_request)
payment = query_and_match_payment(event)
with database_transaction():
    lock_order(payment.order_id)
    persist_verified_event_once(event)
    record_payment_once(payment)
    if not fulfillment_exists(payment.order_id):
        if allocate_or_reuse_stock_once(payment.order_id):
            create_outbox_job_once(payment.order_id, "deliver")
        else:
            mark_paid_awaiting_stock(payment.order_id)
            create_outbox_job_once(payment.order_id, "stock_review")
return acknowledgement_required_by_protocol()

Giải thích giao dịch của PostgreSQL giúp hiểu việc commit đồng thời; Cơ chế khóa hàng giúp phối hợp các thao tác cạnh tranh. Đặt truy vấn bên ngoài và gửi email ngoài giao dịch ngắn; Outbox là bản ghi tác vụ được lưu cùng dữ liệu nghiệp vụ, do worker thực hiện sau commit. Ví dụ bỏ qua bắt ngoại lệ; triển khai thực tế vẫn phải xử lý khóa trùng, deadlock và thử lại sau lỗi.

Bước 8: bổ sung nhánh hết hàng, thanh toán đến muộn và hoàn tiền

Nếu hết hàng sau khi xác nhận thanh toán, lưu “đã trả tiền, chờ xử lý”, báo quản trị viên bổ sung hàng, thỏa thuận giao hoặc hoàn tiền, không đổi lại “chưa thanh toán”. Đơn hết hạn nhận khoản thanh toán muộn hợp lệ cũng phải ghi nhận tiền trước, rồi xử lý theo tồn kho hiện tại và quy tắc đã thống nhất, không bỏ qua.

Gửi email hết thời gian chờ không có nghĩa email chưa được gửi. Giữ mã tác vụ giao hàng ổn định; khi gọi dịch vụ cấp phép bên ngoài có hỗ trợ lũy đẳng, dùng lại định danh tương ứng; nếu không hỗ trợ thì tra cứu hoặc kiểm tra thủ công trước. Gửi lại mã của đơn gốc và cấp một mã mới là hai thao tác khác nhau; gửi lại không được trừ tồn kho lần nữa.

Hoàn tiền cần các trạng thái riêng: yêu cầu, đang xử lý, thành công hoặc thất bại, và liên kết với giao dịch gốc. Mã cấp phép đã hiển thị hoặc sử dụng không thể đơn giản trả về hàng có thể bán; nếu có thể thu hồi cấp phép, phải xác minh kết quả thu hồi trước. Ghi người thao tác, lý do và mã liên quan khi hoàn tiền hoặc cấp bù.

Bước 9: dùng ma trận nghiệm thu chứng minh khả năng xử lý bất thường

Không chỉ kiểm thử một thanh toán bình thường. Với mỗi tình huống, lưu mã đơn, mã lần thử thanh toán, kết quả xác minh, bản ghi thanh toán, cấp tồn kho và trạng thái tác vụ để người bảo trì khác cũng kiểm tra lại được.

Đầu vào kiểm thửKết quả đơn dự kiếnNghiệm thu giao sản phẩm
Thanh toán thật thành côngĐã trả tiền, giao dịch có thể đối chiếuĐúng số lượng, chỉ giao một lần
Chữ ký hoặc số tiền saiKhông xác nhận thành công, ghi lý doKhông cấp hàng tồn
Cùng thông báo đến đồng thờiChỉ gán cùng khoản thanh toán một lầnChỉ có một lần cấp hợp lệ
Tạo đơn hết thời gian chờ, callback tạm thiếuTra cứu để khôi phục trạng thái rõ ràngKhông trả tiền trùng hoặc bỏ sót giao hàng
Nhiều khách đồng thời mua phần tồn cuốiLưu riêng từng sự kiện thanh toánKhông bán vượt tồn; đơn thiếu hàng có thể xử lý
Thanh toán đến muộn, trang đã đóngGiữ sự kiện đã thanh toánGiao bù hoặc hậu mãi theo quy tắc
Tiến trình khởi động lại sau commitBản ghi bền vững còn nguyênKhôi phục tác vụ, không giao dư
Hoàn tiền và giao hàng diễn ra đồng thờiCác trạng thái độc lập có thể truy vếtXử lý xung đột theo quy tắc phối hợp

Nếu nhà cung cấp có môi trường kiểm thử, ưu tiên dùng; nếu không, thống nhất trước quy tắc thanh toán thật số tiền nhỏ, hoàn tiền và chi phí. Quy trình trong bài không thay thế kiểm thử kênh thực tế và không phải bằng chứng “đã vượt nghiệm thu”.

Bước 10: triển khai trong phạm vi nhỏ, tiếp tục xử lý đơn cũ khi hoàn tác

Trước phát hành, giữ bản sao lưu có thể khôi phục, bộ thích ứng cũ cùng cấu hình và xác nhận cấu trúc dữ liệu sau thay đổi có thể hoàn tác hay không. Ban đầu giới hạn phạm vi tích hợp, theo dõi số đơn chờ xác nhận, lỗi xác minh chữ ký, đã trả chưa giao, tác vụ tồn đọng và lỗi tra cứu.

Khi phát hiện bất thường, có thể tạm dừng lần thử thanh toán mới nhưng vẫn phải nhận và kiểm tra thông báo của đơn cũ, giữ tương thích quy chuẩn gốc và kế hoạch luân chuyển khóa. Không “hoàn tác” bằng cách xóa địa chỉ callback hoặc làm rỗng hàng đợi, vì khoản thanh toán cũ có thể mất liên kết mãi mãi.

稳付pay hỗ trợ tích hợp Alipay, WeChat và các kênh khác; quyết toán USDT sau thu hộ qua kênh thực hiện theo thỏa thuận hai bên, còn giám sát địa chỉ USDT riêng nghĩa là khách trả trực tiếp vào ví đơn vị kinh doanh. Hiện dịch vụ giám sát hỗ trợ Tron (TRC20) và Ethereum (ERC20), gửi callback nghiệp vụ trong vài giây sau khi đạt điều kiện xác nhận đã cấu hình, không có nghĩa xác nhận khối chỉ mất vài giây. Bảng quản trị đơn vị kinh doanh vẫn đang phát triển; trước tiên hãy Liên hệ xác nhận quy chuẩn, điều kiện quyết toán và phạm vi kiểm thử tích hợp rồi mới viết lớp thích ứng tương ứng.

Nguồn tham khảo và tài liệu kỹ thuật

Tài liệu chính thức dùng để kiểm tra nguyên lý kỹ thuật chung. Ví dụ cần được xác minh theo tài liệu API thực tế và môi trường vận hành.

  1. OWASP: tích hợp thanh toán bên thứ ba an toàn
  2. Stripe: xác minh webhook, thử lại và sự kiện trùng
  3. Stripe: yêu cầu lũy đẳng
  4. PostgreSQL: giao dịch
  5. PostgreSQL: khóa hàng và xử lý đồng thời
  6. PostgreSQL: ràng buộc duy nhất

Xác nhận tích hợp theo tình huống kinh doanh của bạn

Trình bày sản phẩm, số lượng đơn, phương thức thanh toán và nhu cầu quyết toán; lần lượt xác nhận API, dòng tiền và xử lý bất thường.

Liên hệ 稳付pay ↗