Tài liệu nhà phát triển

Hướng dẫn tích hợp cho nhà phát triển: đưa 稳付pay vào sản phẩm của bạn

Website, nền tảng bán mã hoặc ứng dụng của bạn chịu trách nhiệm tạo đơn nghiệp vụ và giao sản phẩm; 稳付pay phụ trách tích hợp kênh thanh toán và thông báo kết quả. Hướng dẫn này trình bày theo thứ tự thực tế cần cấu hình gì, gọi gì và khi nào có thể chuyển đơn thành đã thanh toán.

Mục lục bài viết

Xác nhận dịch vụ cần tích hợp trước

Bộ tài liệu này trình bày các chức năng của kênh thanh toán đã mở: tạo đơn thu hộ, truy vấn đơn và thông báo thanh toán thành công. Chi hộ hiện chưa mở. Kỹ thuật viên 稳付pay sẽ xác nhận với bạn các kênh khả dụng, gateway chính thức, thỏa thuận quyết toán và quyền của đơn vị kinh doanh khi mở dịch vụ.

Quyết toán sau thu hộ và giám sát on-chain khi khách hàng trả trực tiếp vào ví USDT riêng của đơn vị kinh doanh là hai luồng nghiệp vụ khác nhau. Các API thu hộ trong bộ tài liệu này không phải API nhận USDT trực tiếp trên blockchain.

Địa chỉ web, mã đơn và thông tin xác thực trong bài đều là ví dụ. Hãy hoàn tất trao đổi kỹ thuật và nhận cấu hình riêng của bạn trước, không dùng trực tiếp tham số minh họa cho môi trường thật.

Bước 1: xin cấu hình đơn vị kinh doanh

Mục cấu hìnhNơi sử dụngNội dung cần xác nhận
API_BASE_URLMáy chủ của đơn vị kinh doanhGateway thực tế được cấp; bài này dùng https://gateway.example.com để minh họa.
MERCHANT_IDMáy chủ của đơn vị kinh doanhMã đơn vị kinh doanh của bạn, tên trường yêu cầu là mchId。
MD5_SECRETBiến môi trường hoặc hệ thống quản lý khóaKhóa API dùng khi tạo và tra cứu đơn.
CALLBACK_SECRETQuản lý khóa ở máy chủKhóa callback được cấu hình riêng; nếu chưa cấu hình thì dùng khóa API dự phòng.
wayCodeÁnh xạ phương thức thanh toánMã kênh thực tế hoặc mã tổng hợp được mở cho đơn vị kinh doanh này.
notifyUrlAPI máy chủ HTTPS công khaiVí dụ https://merchant.example.com/pay/notify。

Chỉ lưu khóa ở máy chủ; giao diện chỉ nhận đơn nghiệp vụ và liên kết thanh toán được phép hiển thị. Tách cấu hình kiểm thử và chính thức; che khóa và phần chứa khóa trong chuỗi ký khi ghi log.

Bước 2: nối đầy đủ luồng thanh toán

  1. Tạo đơn kinh doanhMáy chủ xác định sản phẩm, số tiền, loại tiền, mã đơn duy nhất của đơn vị kinh doanh và lưu bản ghi chờ thanh toán.
  2. Ký và tạo đơn ở máy chủTạo dấu thời gian mili giây hiện tại, tính chữ ký và gọi API tạo đơn thu hộ.
  3. Hiển thị liên kết thanh toán hợp lệKiểm tra payUrl thực tế được trả về rồi mới hướng dẫn thanh toán; nếu không có liên kết thì chuyển sang tra cứu hoặc xử lý bất thường.
  4. Xác minh thông báo thành côngMáy chủ xác minh chữ ký, kiểm tra đơn vị kinh doanh, đơn, loại tiền và số tiền; không dựa vào chuyển trang trên trình duyệt để xác định tiền đã đến.
  5. Cập nhật và giao sản phẩm lũy đẳngLưu bền vững trạng thái thanh toán, dùng bản ghi giao sản phẩm duy nhất để tránh cấp mã, nạp tiền hoặc giao hàng trùng.
  6. Tra cứu và kiểm traChủ động tra cứu đơn bị hết thời gian chờ, thiếu thông báo hoặc chờ thanh toán lâu và giữ bản ghi xử lý.
Tạo đơn thành công không đồng nghĩa thanh toán thành công; việc giao sản phẩm phải được kích hoạt bằng kết quả thanh toán đáng tin cậy từ máy chủ.

Bước 3: chuẩn bị bốn vị trí tích hợp trong sản phẩm

Vị trí trong hệ thốngTrách nhiệm tích hợpBản ghi cần giữ
Dịch vụ tạo đơnKiểm tra đơn nghiệp vụ, ký và gọi API tạo đơn.Mã đơn của đơn vị kinh doanh, số tiền fen, loại tiền, mã đơn nền tảng.
Trang hiển thị thanh toánHiển thị liên kết thanh toán thật và trạng thái nội bộ.Liên kết đơn với quyền truy cập của khách hàng.
API thông báo bất đồng bộXác minh chữ ký, kiểm tra và lưu bền vững kết quả thành công theo cách lũy đẳng.Tóm tắt thông báo, kết quả kiểm tra và thời điểm nhận.
Tác vụ tra cứuBổ sung kết quả chưa rõ và dùng cùng quy trình giao sản phẩm.Kết quả truy vấn, số lần và thời điểm kiểm tra cuối.

Khi dùng nền tảng bán mã có sẵn, tích hợp các logic này vào plugin thanh toán hoặc phần mở rộng phía máy chủ. Xác nhận nền tảng lưu được mã đơn riêng của đơn vị kinh doanh, xác minh chữ ký theo tham số gốc và hỗ trợ giao sản phẩm lũy đẳng; chỉ thêm một liên kết chuyển trang chưa phải hoàn thành tích hợp.

Danh sách nghiệm thu trước khi đưa vào vận hành

  • Hoàn thành đơn kiểm thử đã thỏa thuận, truyền số tiền tạo đơn bằng fen và liên kết được đúng đơn nền tảng cùng đầu vào thanh toán.
  • Chữ ký đúng được chấp nhận; thiếu trường, sửa số tiền và chữ ký sai đều được phát hiện và ghi nhận.
  • Sau khi người dùng đóng trình duyệt, máy chủ vẫn cập nhật được trạng thái qua thông báo hoặc tra cứu.
  • Thông báo lặp lại, hoặc thông báo và tra cứu cùng xác nhận thành công, đều chỉ giao sản phẩm một lần.
  • Nếu tạo đơn hết thời gian chờ, tra cứu đơn gốc trước, không đổi mã rồi tạo lại mù quáng; giữ kết quả chưa rõ ở trạng thái chờ xác minh.
  • Khi thanh toán thành công nhưng giao sản phẩm thất bại, có thể thử lại an toàn và lưu cả bản ghi thanh toán lẫn giao sản phẩm.
  • API thông báo truy cập được từ Internet; khóa không xuất hiện trong mã nguồn trang, tệp công khai hay log.

Kỹ thuật viên xác nhận với bạn hạn mức kiểm thử, quyền kênh và cách xử lý bất thường. Khi cần hỗ trợ, chỉ cung cấp mã đơn đã che dữ liệu nhạy cảm, thời gian yêu cầu và tóm tắt lỗi; không để lộ khóa trong ảnh chụp.

Tiếp tục hoàn tất tích hợp API

Đọc lần lượt Tạo và truy vấn đơn thu hộ、Quy tắc ký yêu cầu và Xác minh callback và giao sản phẩm lũy đẳng. Kỹ thuật viên hỗ trợ tích hợp theo framework phát triển, hệ thống bán mã và các kênh đã mở của bạn.

Bài này được biên soạn theo quy chuẩn tích hợp 稳付pay. Ví dụ giải thích vị trí gọi và cấu trúc tham số; khi kiểm thử tích hợp chính thức, dùng cấu hình được cấp cho bạn.

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 ↗