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。 |
mchId | Phải khớp với đơn vị kinh doanh sở hữu đơn trong hệ thống của bạn. |
platformOrderNo | Mã đơn của nền tảng, liên kết với bản ghi thanh toán nội bộ. |
outTradeNo | Mã đơn của đơn vị kinh doanh đã truyền khi tạo đơn. |
merchantOrderNo | Trường tương thích, giống outTradeNo. |
transactionId | Mã 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. |
amount | Số tiền tính bằng fen, ví dụ chuỗi 1000。 |
amountYuan | Số tiền tính bằng nhân dân tệ, giữ hai chữ số thập phân, ví dụ 10.00。 |
currencyCode | Loại tiền, ví dụ CNY。 |
orderStatus | Trạng thái đơn; ví dụ thông báo thành công dùng chuỗi 1。 |
tradeState | Thu hộ thành công là SUCCESS。 |
returnCode | 00 nghĩa là nghiệp vụ thành công. |
successTime | Thời gian thành công, định dạng yyyy-MM-dd HH:mm:ss。 |
notifyTime | Thời gian của lần thông báo này, cùng định dạng ở trên. |
sign | Chữ 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
- Đọc JSON, giữ nguyên giá trị các trường và lấy từ Body trường
sign。 - Ưu tiên dùng
CALLBACK_SECRET; nếu chưa cấu hình riêng thì dùngMD5_SECRET。 - 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. - 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.
- 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.
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
- 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.
- 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.
- 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.
- 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 ↗