Tạo và tra cứu đơn thu hộ: trường, số tiền và trạng thái đơn
Máy chủ của bạn lưu đơn nghiệp vụ nội bộ trước rồi mới tạo đơn thu hộ; nếu mạng hết thời gian chờ hoặc chưa rõ kết quả thanh toán, hãy tra cứu bằng mã đơn ban đầu của đơn vị kinh doanh. Cả hai loại gọi đều cần mã đơn vị kinh doanh, dấu thời gian mili giây hiện tại và chữ ký do máy chủ tạo.
Mục lục bài viết
API tạo đơn: POST JSON
Địa chỉ ví dụ https://gateway.example.com/api/pay/collect/create, phương thức POST, header yêu cầu Content-Type: application/json, bộ ký tự UTF-8. Thay tên miền minh họa bằng gateway thực tế đã được mở.
| Trường | Bắt buộc | Quy tắc điền |
|---|---|---|
mchId | Có | Mã đơn vị kinh doanh của bạn; ví dụ dùng chuỗi. |
wayCode | Có | Mã kênh hoặc mã tổng hợp đã được mở; ví dụ dùng chuỗi. |
outTradeNo | Có | Mã đơn của đơn vị kinh doanh, duy nhất trong cùng đơn vị và liên kết với đơn nội bộ. |
amount | Có | Số tiền tạo đơn tính bằng fen; số nguyên 1000 biểu thị 10.00 nhân dân tệ. |
currencyCode | Không | Loại tiền, mặc định CNY。 |
notifyUrl | Có | Địa chỉ thông báo bất đồng bộ của bạn, ví dụ https://merchant.example.com/pay/notify。 |
subject | Không | Tên sản phẩm; tham gia tính chữ ký nếu được gửi. |
body | Không | Mô tả sản phẩm; tham gia tính chữ ký nếu được gửi. |
clientIp | Không | IP của khách hàng, điền theo tình huống thực tế. |
reqTime | Có | Dấu thời gian mili giây hiện tại; ví dụ dùng số nguyên. |
sign | Có | Chữ ký MD5 chữ thường do máy chủ tạo, không tham gia việc tính chữ ký của chính nó. |
Số tiền được máy chủ của bạn xác định từ bản ghi đơn đáng tin cậy, không tin trực tiếp giá do giao diện gửi lên. Lưu số tiền tạo đơn bằng số nguyên fen để tránh nhập 10.00 nhân dân tệ thành 10 fen, đồng thời tránh đưa số dấu phẩy động nhị phân chưa xử lý vào phép tính tiền.
Tạo đơn: ví dụ các trường
Mọi thông tin định danh và chữ ký trong JSON đều là giá trị giữ chỗ; reqTime trong yêu cầu thực tế phải là số nguyên mili giây hiện tại, hãy tính lại chữ ký rồi mới gửi.
{
"mchId": "MERCHANT_ID",
"wayCode": "80001",
"outTradeNo": "DEMO_COLLECT_001",
"amount": 1000,
"currencyCode": "CNY",
"notifyUrl": "https://merchant.example.com/pay/notify",
"subject": "DEMO_PRODUCT",
"reqTime": "CURRENT_UNIX_MILLISECONDS",
"sign": "RECOMPUTE_ON_YOUR_SERVER"
}import os
import time
from wenfupay_collect_sign import sign_collect
payload = {
"mchId": os.environ["MERCHANT_ID"],
"wayCode": "80001", # Use a code enabled for your merchant.
"outTradeNo": "YOUR_UNIQUE_ORDER_NO",
"amount": 1000, # 1000 cents = CNY 10.00.
"currencyCode": "CNY",
"notifyUrl": "https://merchant.example.com/pay/notify",
"reqTime": int(time.time() * 1000),
}
payload["sign"] = sign_collect(payload, os.environ["MD5_SECRET"])
# Send payload as JSON from your server to:
# API_BASE_URL + "/api/pay/collect/create"curl --request POST "$API_BASE_URL/api/pay/collect/create" \
--header "Content-Type: application/json; charset=UTF-8" \
--data @collect-create.jsonTải hàm ký Python được dùng trong ví dụ; xem quy tắc tính tại Ký và xác minh MD5。
Truy vấn đơn: ký trước, mã hóa chuỗi truy vấn sau
import os
import time
from urllib.parse import urlencode
from wenfupay_collect_sign import sign_collect
params = {
"mchId": os.environ["MERCHANT_ID"],
"outTradeNo": "YOUR_EXISTING_ORDER_NO",
"reqTime": int(time.time() * 1000),
}
# Alternative lookup: replace outTradeNo with platform_order_no.
params["sign"] = sign_collect(params, os.environ["MD5_SECRET"])
query_url = (
os.environ["API_BASE_URL"].rstrip("/")
+ "/api/pay/collect/query?" + urlencode(params)
)
# Send a server-side GET. Do not create another order on a timeout.Chọn Alipay, WeChat và mã kênh thế nào
80001 là mã tổng hợp Alipay, 90001 là mã tổng hợp WeChat; cũng có thể dùng mã kênh thực tế được cấp. Định tuyến tổng hợp chỉ chọn trong các kênh thực tế ứng viên đã liên kết, được đơn vị kinh doanh cấp quyền và bật, không có nghĩa mọi đơn vị đều tự động sử dụng được.
Máy chủ ánh xạ tùy chọn thanh toán trong sản phẩm tới wayCode đã được mở. Kỹ thuật viên xác nhận mã khả dụng, giới hạn kênh và cách kiểm thử; giao diện không cần biết cấu hình định tuyến nội bộ.
Định tuyến tổng hợp chỉ có thể thử ứng viên tiếp theo khi thượng nguồn xác nhận rõ chưa tiếp nhận. Khi hết thời gian chờ, có lỗi hoặc kết quả chưa chắc chắn, hệ thống không chuyển kênh mù quáng; hệ thống của bạn cũng phải tra cứu đơn gốc trước để tránh tạo nhiều đơn có thể đồng thời được thanh toán.
Nối phản hồi tạo đơn vào trang thanh toán của bạn
JSON phản hồi có các trường cấp cao nhất code、message、data và sign. Trong ví dụ bình thường, code là 0;data chứa duplicate、id、platformOrderNo、orderStatus、payUrl、channelErrorMessage。
Lưu mã đơn nền tảng để truy vấn, đối chiếu thông báo và đối soát. Chỉ hiển thị đầu vào thanh toán khi đã nhận payUrl thực sự hợp lệ; giá trị có thể rỗng, không tự ghép URL trang thu ngân. Kiểm tra giao thức và tên miền đích của liên kết; cấu hình phạm vi cho phép khi tích hợp kỹ thuật.
code=0 không có nghĩa tiền đã được thanh toán, không được cấp mã hoặc giao hàng ngay. Dù đã nhận mã đơn nền tảng, vẫn phải chờ kết quả thanh toán thành công đáng tin cậy. Kỹ thuật viên cung cấp cách xử lý đầy đủ mã lỗi và chi tiết xác minh phản hồi khi kiểm thử tích hợp.
API truy vấn: GET để tra cứu đơn gốc
Địa chỉ ví dụ https://gateway.example.com/api/pay/collect/query, phương thức GET. Ký các tham số truy vấn thực tế trước, sau đó dùng mã hóa URL tiêu chuẩn để tạo chuỗi truy vấn.
| Trường | Bắt buộc | Quy tắc điền |
|---|---|---|
mchId | Có | Mã đơn vị kinh doanh sở hữu đơn. |
outTradeNo | Chọn một trong hai | Mã đơn của đơn vị kinh doanh; chọn một trong hai cùng với platform_order_no . |
platform_order_no | Chọn một trong hai | Mã đơn nền tảng, lưu ý tên dùng dấu gạch dưới. |
reqTime | Có | Dấu thời gian mili giây hiện tại của lần truy vấn này. |
sign | Có | Tính lại theo các tham số lần này, không dùng lại chữ ký tạo đơn. |
Trong phản hồi truy vấn, data có ví dụ gồm platformOrderNo、merchantOrderNo、amount、currencyCode、orderStatus、payUrl. Trường trong yêu cầu platform_order_no và trường trong phản hồi platformOrderNo viết khác nhau; không dùng chung trực tiếp một đối tượng tham số.
Trong phản hồi truy vấn, amount có đơn vị và độ chính xác được kỹ thuật viên xác nhận khi mở dịch vụ. Chuyển đổi tường minh sang đơn vị tiền nội bộ rồi kiểm tra; không so sánh trực tiếp với số tiền fen khi tạo đơn.
Trạng thái đơn và hành động nghiệp vụ tương ứng
| orderStatus | Ý nghĩa | Cách sản phẩm xử lý |
|---|---|---|
0 | Chờ thanh toán | Hiển thị đang chờ thanh toán, tra cứu theo lịch, chưa giao sản phẩm. |
1 | Thanh toán thành công | Sau khi kiểm tra kết quả đáng tin cậy, chuyển vào quy trình giao sản phẩm lũy đẳng. |
2 | Thanh toán thất bại | Ghi nhận thất bại; xử lý đơn gốc theo quy tắc trước khi thanh toán lại. |
3 | Đã đóng | Kết thúc chờ, giữ bản ghi đơn và kiểm tra. |
4 | Đã hết hiệu lực | Hiển thị hết hiệu lực, xử lý mua lại và tiền đến bất thường theo thỏa thuận. |
HTTP hết thời gian chờ không phải trạng thái đơn. Ghi nhận “chờ xác nhận kết quả” và tra cứu bằng mã đơn gốc của đơn vị kinh doanh; trước khi xác nhận kết quả, không kết luận yêu cầu gốc chắc chắn thất bại và không đổi mã đơn để né kiểm tra trùng.
Callback và truy vấn dùng cùng hàm xử lý thanh toán
- Tìm đơn gốcĐọc bản ghi nội bộ theo mã đơn vị kinh doanh và mã đơn của đơn vị đó, xác nhận khách hàng sở hữu và môi trường.
- Kiểm tra kết quả đáng tin cậyCallback phải xác minh chữ ký trước; truy vấn dùng yêu cầu máy chủ được bảo vệ và xác minh phản hồi theo quy chuẩn tích hợp.
- Cập nhật lũy đẳng thống nhấtChỉ ghi trạng thái thành công vào cơ sở dữ liệu một lần; tác vụ giao sản phẩm dùng khóa nghiệp vụ duy nhất.
- Ghi nhận sai lệchKhi số tiền, loại tiền hoặc trạng thái không khớp, dừng giao sản phẩm để kỹ thuật viên hỗ trợ kiểm tra.
Đọc tiếp Quy tắc chữ ký và Chi tiết xử lý callback. Bài này được biên soạn theo quy chuẩn tích hợp 稳付pay.
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 ↗