API thu hộ

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ườngBắt buộcQuy tắc điền
mchIdCóMã đơn vị kinh doanh của bạn; ví dụ dùng chuỗi.
wayCodeCóMã kênh hoặc mã tổng hợp đã được mở; ví dụ dùng chuỗi.
outTradeNoCó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ộ.
amountCó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ệ.
currencyCodeKhôngLoại tiền, mặc định CNY。
notifyUrlCóĐịa chỉ thông báo bất đồng bộ của bạn, ví dụ https://merchant.example.com/pay/notify。
subjectKhôngTên sản phẩm; tham gia tính chữ ký nếu được gửi.
bodyKhôngMô tả sản phẩm; tham gia tính chữ ký nếu được gửi.
clientIpKhôngIP của khách hàng, điền theo tình huống thực tế.
reqTimeCóDấu thời gian mili giây hiện tại; ví dụ dùng số nguyên.
signCó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.

Ví dụ trường JSON
{
  "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"
}
Ghép tham số phía máy chủ bằng Python
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"
Phương thức truyền bằng cURL
curl --request POST "$API_BASE_URL/api/pay/collect/create" \
  --header "Content-Type: application/json; charset=UTF-8" \
  --data @collect-create.json

Tả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

Tham số GET bằng Python
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ườngBắt buộcQuy tắc điền
mchIdCóMã đơn vị kinh doanh sở hữu đơn.
outTradeNoChọn một trong haiMã đơn của đơn vị kinh doanh; chọn một trong hai cùng với platform_order_no .
platform_order_noChọn một trong haiMã đơn nền tảng, lưu ý tên dùng dấu gạch dưới.
reqTimeCóDấu thời gian mili giây hiện tại của lần truy vấn này.
signCó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ĩaCách sản phẩm xử lý
0Chờ thanh toánHiển thị đang chờ thanh toán, tra cứu theo lịch, chưa giao sản phẩm.
1Thanh toán thành côngSau 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.
2Thanh toán thất bạiGhi nhận thất bại; xử lý đơn gốc theo quy tắc trước khi thanh toán lại.
3Đã đóngKết thúc chờ, giữ bản ghi đơn và kiểm tra.
4Đã hết hiệu lựcHiể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

  1. 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.
  2. 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.
  3. 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.
  4. 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 ↗