Thông báo bất đồng bộ

Callback thanh toán: xác minh chữ ký, kiểm tra đơn và giao hàng lũy đẳng

Callback có thể đến muộn hoặc được gửi nhiều lần. Máy chủ của bạn cần nhận JSON, xác minh chữ ký, kiểm tra đơn và lưu trạng thái thành công một cách tin cậy, sau đó chuyển kết quả vào quy trình giao sản phẩm có thể thử lại an toàn.

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

Khi nào thông báo được gửi đến máy chủ của bạn

Sau khi nền tảng nhận thông báo thanh toán thành công từ kênh và cập nhật đơn thu hộ, hệ thống sẽ gửi đến notifyUrl bất đồng bộ POST,Content-Type là application/json. Nếu đơn không có địa chỉ thông báo thì dùng địa chỉ mặc định của đơn vị kinh doanh; khi tạo đơn bạn vẫn phải truyền notifyUrl。

Đầu nhận thông báo phải truy cập được từ Internet và không phụ thuộc trạng thái đăng nhập trên trình duyệt. Thông báo nhận được dùng định dạng thống nhất của 稳付pay, không cần phân tích tham số gốc từ kênh thượng nguồn. Trang thành công trên trình duyệt và ảnh chụp của khách hàng không thay thế được việc xác minh ở máy chủ.

15 trường của thông báo tiêu chuẩn

TrườngÝ nghĩa và cách kiểm tra
bizTypeĐối với thu hộ, giá trị cố định là collect。
mchIdPhải khớp với đơn vị kinh doanh sở hữu đơn trong hệ thống của bạn.
platformOrderNoMã đơn của nền tảng, liên kết với bản ghi thanh toán nội bộ.
outTradeNoMã đơn của đơn vị kinh doanh đã truyền khi tạo đơn.
merchantOrderNoTrường tương thích, giống outTradeNo.
transactionIdMã giao dịch của kênh; nếu kênh không trả về thì dùng mã đơn của nền tảng.
amountSố tiền tính bằng fen, ví dụ chuỗi 1000。
amountYuanSố tiền tính bằng nhân dân tệ, giữ hai chữ số thập phân, ví dụ 10.00。
currencyCodeLoại tiền, ví dụ CNY。
orderStatusTrạng thái đơn; ví dụ thông báo thành công dùng chuỗi 1。
tradeStateThu hộ thành công là SUCCESS。
returnCode00 nghĩa là nghiệp vụ thành công.
successTimeThời gian thành công, định dạng yyyy-MM-dd HH:mm:ss。
notifyTimeThời gian của lần thông báo này, cùng định dạng ở trên.
signChữ ký nghiệp vụ, không tham gia việc tính chữ ký của chính nó.

Trong ví dụ thông báo, tất cả trường đều dùng chuỗi. Giữ nguyên giá trị nhận được để xác minh chữ ký trước, đặc biệt là 00 và 10.00; không định dạng lại, bỏ số 0 hay ép thành số trước khi xác minh chữ ký.

Xác minh chữ ký trước, rồi kiểm tra đơn và kết quả thanh toán

  1. Đọc JSON, giữ nguyên giá trị các trường và lấy từ Body trường sign。
  2. Ưu tiên dùng CALLBACK_SECRET; nếu chưa cấu hình riêng thì dùng MD5_SECRET。
  3. Loại bỏ sign và trường rỗng, ghép theo tên trường tăng dần ASCII, thêm &key=KHÓA_BÍ_MẬT, tính MD5 dạng chữ thường rồi so sánh.
  4. Sau khi chữ ký hợp lệ, kiểm tra mã đơn vị kinh doanh, loại nghiệp vụ, mã đơn của đơn vị kinh doanh và mã đơn nền tảng để tìm đúng đơn thật trong hệ thống.
  5. Kiểm tra số tiền tính bằng fen, loại tiền và trạng thái thanh toán thành công rồi mới xử lý lũy đẳng.

Không được giao hàng chỉ vì thấy returnCode=00 hoặc orderStatus=1 . Chữ ký, danh tính đơn, số tiền, loại tiền và trạng thái thành công đều phải hợp lệ; nếu không khớp thì dừng giao hàng và ghi nhận bất thường.

Quy tắc cho header tương thích X-Plat-Signature được kỹ thuật viên xác nhận riêng. Trang này dùng chữ ký nghiệp vụ chuẩn trong Body, không băm MD5 trực tiếp toàn bộ văn bản JSON gốc.

Ví dụ Python xác minh chữ ký và luồng nghiệp vụ
import json
import os
from wenfupay_collect_sign import verify_collect_notification

try:
    notice = json.loads(raw_request_body)
except (ValueError, UnicodeDecodeError):
    return http_response(400, "INVALID_JSON")
if not isinstance(notice, dict):
    return http_response(400, "INVALID_JSON_OBJECT")
verified = verify_collect_notification(
    notice,
    api_secret=os.environ["MD5_SECRET"],
    callback_secret=os.environ.get("CALLBACK_SECRET"),
)
if not verified:
    return http_response(400, "INVALID_SIGNATURE")

# Business-specific pseudocode: implement these durable operations.
with database_transaction():
    order = lock_order(notice["outTradeNo"])
    match_merchant_currency_and_amount_in_cents(order, notice)
    require_documented_success_fields(notice)
    record_payment_once(order, notice["platformOrderNo"])
    enqueue_fulfillment_once(order)

# Only after successful durable acceptance:
return http_response(200, "OK", content_type="text/plain")

Các hàm xử lý nghiệp vụ chỉ minh họa quy trình, cần kết nối với đơn và cơ sở dữ liệu của đơn vị kinh doanh. Không phản hồi thành công trước khi lưu bền vững, hoặc khi chữ ký hay số tiền không khớp. Thông báo trùng đã được tiếp nhận tin cậy có thể trả trực tiếp sau khi kiểm tra: OK。

Mỗi đơn chỉ ghi nhận thanh toán và giao sản phẩm một lần

  1. Xác minh và tìm đơnXác minh chữ ký, kiểm tra số tiền và loại tiền, tìm cùng bản ghi thanh toán của đơn vị kinh doanh.
  2. Cập nhật trạng thái trong giao dịchKhóa đơn hoặc cập nhật có điều kiện; không ghi nhận thanh toán lặp lại khi đã thành công.
  3. Lưu tác vụ giao sản phẩm duy nhấtDùng khóa duy nhất của đơn để ghi tác vụ cấp mã, nạp tiền hoặc giao hàng.
  4. Xác nhận sau khi commitTrả về OK sau khi trạng thái và tác vụ được lưu tin cậy; việc giao sản phẩm có thể tiếp tục thử lại.
Nhận thông báo
  Chữ ký không hợp lệ: từ chối xử lý, không phản hồi xác nhận thành công
  Đơn vị kinh doanh, đơn, số tiền hoặc loại tiền không khớp: ghi bất thường, không giao sản phẩm
  Bắt đầu giao dịch cơ sở dữ liệu
    Truy vấn và khóa đơn nội bộ
    Nếu chưa thành công: cập nhật trạng thái thanh toán thành công
    Bảo đảm có tác vụ giao sản phẩm, khóa nghiệp vụ duy nhất = ID đơn nội bộ
  Commit giao dịch cơ sở dữ liệu
  Trả về HTTP 200, văn bản thuần OK

Tác vụ giao sản phẩm
  Nếu khóa nghiệp vụ duy nhất đã giao xong: kết thúc
  Nếu chưa, giao an toàn một lần và ghi kết quả
  Lỗi tạm thời: giữ tác vụ, thử lại theo quy tắc nghiệp vụ

Đây là mã giả nghiệp vụ, không phải giao dịch có thể chạy trực tiếp. Nếu không thể giao sản phẩm trong cùng một giao dịch, hãy dùng tác vụ được lưu bền vững và bản ghi giao sản phẩm duy nhất để tránh trường hợp thanh toán đã thành công nhưng không bao giờ giao hàng sau khi tiến trình khởi động lại.

Trả về OK đúng cách và xử lý thử lại

Để xác nhận thành công, đồng thời phải có HTTP 200 và Body phản hồi chứa success、ok hoặc OK. Nên trả trực tiếp dưới dạng văn bản thuần OK, không dùng trang đăng nhập, mẫu HTML hay lớp bọc JSON mặc định của framework.

Thông báo trùng đã được xác nhận xử lý cũng trả về OK. Khi cơ sở dữ liệu không hoạt động, chữ ký sai hoặc kiểm tra nghiệp vụ chưa đạt, không được xác nhận thành công chỉ để dừng thử lại.

Khi thông báo thất bại, hệ thống thử lại bất đồng bộ, tối đa 3 lần thông báo tổng cộng, bao gồm lần gửi đầu tiên; sau hai lần đầu thất bại, lần thử lại diễn ra sau khoảng 60 giây và 300 giây. Đây không phải thử lại vô hạn hay thêm ba lần ngoài lần gửi đầu tiên.

Chủ động tra cứu bù khi không nhận được thông báo

Quy chuẩn quy định rõ thông báo sau thanh toán thành công; không nên mặc định rằng trạng thái thất bại, đóng hoặc hết hiệu lực cũng chắc chắn được đẩy đến. Máy chủ cần chủ động tra cứu các đơn chờ thanh toán lâu, tạo đơn bị hết thời gian chờ hoặc xử lý thông báo bất thường.

Khi tra cứu xác nhận thành công, hãy dùng cùng quy trình giao sản phẩm lũy đẳng như callback, không tạo nhánh giao hàng bỏ qua kiểm tra số tiền. Xác nhận đơn vị số tiền truy vấn khi mở dịch vụ rồi mới chuyển đổi để so sánh; giữ kết quả chưa rõ ở trạng thái cần xác minh.

Khi kiểm thử tích hợp, ít nhất hãy thử thông báo trùng, tra cứu trước callback, callback trước tra cứu, lỗi cơ sở dữ liệu tạm thời và thử lại giao sản phẩm sau thành công. Kỹ thuật viên sẽ hỗ trợ xác nhận cấu hình và xử lý bất thường cụ thể.

Bài này được biên soạn theo quy chuẩn tích hợp 稳付pay. Trở về Tổng quan tích hợp hoặc xem Các trường tạo đơn và truy vấ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 ↗