สร้างและสอบถามรับชำระแทน: ช่องข้อมูล จำนวนเงิน และสถานะคำสั่งซื้อ
เซิร์ฟเวอร์คุณต้องบันทึกคำสั่งซื้อธุรกิจในระบบก่อน แล้วจึงสร้างคำสั่งซื้อรับชำระแทน หากเครือข่ายหมดเวลารอหรือผลชำระเงินไม่ชัด ให้สอบถามด้วยหมายเลขคำสั่งซื้อผู้ค้าเดิม การเรียกทั้งสองแบบต้องใช้หมายเลขผู้ค้า เวลาปัจจุบันหน่วยมิลลิวินาที และลายเซ็นจากเซิร์ฟเวอร์
สารบัญบทความ
API สร้างคำสั่งซื้อ: POST JSON
ที่อยู่ตัวอย่าง https://gateway.example.com/api/pay/collect/create วิธี POST ส่วนหัวคำขอ Content-Type: application/json ชุดอักขระ UTF-8 ให้แทนโดเมนตัวอย่างด้วยเกตเวย์จริงที่เปิดให้ใช้
| ช่องข้อมูล | จำเป็น | กฎการกรอก |
|---|---|---|
mchId | ใช่ | หมายเลขผู้ค้าของคุณ ตัวอย่างใช้สตริง |
wayCode | ใช่ | รหัสช่องทางหรือรหัสรวมที่เปิดใช้งานแล้ว ตัวอย่างใช้สตริง |
outTradeNo | ใช่ | หมายเลขคำสั่งซื้อผู้ค้า ไม่ซ้ำภายในผู้ค้ารายเดียวกัน และเชื่อมกับคำสั่งซื้อในระบบ |
amount | ใช่ | จำนวนเงินสร้างคำสั่งซื้อหน่วยเฟิน จำนวนเต็ม 1000 หมายถึง 10.00 หยวน |
currencyCode | ไม่ | สกุลเงิน ค่าเริ่มต้น CNY。 |
notifyUrl | ใช่ | ที่อยู่รับการแจ้งแบบอะซิงโครนัสของคุณ เช่น https://merchant.example.com/pay/notify。 |
subject | ไม่ | ชื่อสินค้า หากส่งค่ามาจะร่วมคำนวณลายเซ็น |
body | ไม่ | รายละเอียดสินค้า หากส่งค่ามาจะร่วมคำนวณลายเซ็น |
clientIp | ไม่ | IP ลูกค้า กรอกตามกรณีใช้งานจริง |
reqTime | ใช่ | เวลาปัจจุบันหน่วยมิลลิวินาที ตัวอย่างใช้จำนวนเต็ม |
sign | ใช่ | ลายเซ็น MD5 ตัวพิมพ์เล็กที่เซิร์ฟเวอร์สร้าง ไม่รวมตัวเองในการลงลายเซ็น |
เซิร์ฟเวอร์คุณต้องกำหนดจำนวนเงินจากบันทึกคำสั่งซื้อที่เชื่อถือได้ ไม่เชื่อราคาที่ส่งจากหน้าเว็บโดยตรง เก็บยอดสร้างคำสั่งซื้อเป็นจำนวนเต็มหน่วยเฟิน เพื่อไม่กรอก 10.00 หยวนเป็น 10 เฟิน และหลีกเลี่ยงนำเลขทศนิยมฐานสองที่ยังไม่จัดการมาคำนวณเงิน
สร้างคำสั่งซื้อ: ตัวอย่างช่องข้อมูล
ตัวตนและลายเซ็นทั้งหมดใน JSON เป็นค่าตัวอย่างแทนข้อมูลจริง reqTime ในคำขอจริงต้องเป็นจำนวนเต็มมิลลิวินาทีปัจจุบัน คำนวณลายเซ็นใหม่ก่อนส่ง
{
"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.jsonดาวน์โหลดฟังก์ชันลายเซ็น Python ที่ใช้ในตัวอย่าง ดูกฎคำนวณที่ ลงลายเซ็นและตรวจ MD5。
สอบถามคำสั่งซื้อ: ลงลายเซ็นก่อน แล้วเข้ารหัสสตริงคำถาม
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.เลือกรหัส Alipay, WeChat และช่องทางอย่างไร
80001 คือรหัสรวม Alipay ส่วน 90001 คือรหัสรวม WeChat หรือใช้รหัสช่องทางจริงที่ได้รับก็ได้ ระบบรวมเลือกเฉพาะช่องทางจริงที่เชื่อมโยง ผู้ค้าอนุญาต และเปิดใช้งานแล้ว ไม่ได้หมายความว่าผู้ค้าทุกรายใช้ได้โดยอัตโนมัติ
เซิร์ฟเวอร์จับคู่ตัวเลือกชำระเงินในสินค้ากับ wayCode ที่เปิดใช้แล้ว ฝ่ายเทคนิคยืนยันรหัสที่ใช้ได้ ข้อจำกัดช่องทาง และวิธีทดสอบ หน้าเว็บไม่ต้องรู้การตั้งค่าเส้นทางภายใน
เส้นทางรวมอาจลองช่องทางผู้สมัครถัดไปได้ก็ต่อเมื่อต้นน้ำยืนยันชัดว่ายังไม่รับรายการ เมื่อหมดเวลารอ เกิดข้อผิดพลาด หรือผลไม่แน่นอน จะไม่สลับอย่างสุ่ม ระบบคุณก็ควรสอบถามคำสั่งซื้อเดิมก่อน เพื่อไม่สร้างหลายคำสั่งซื้อที่อาจถูกชำระพร้อมกัน
เชื่อมผลตอบกลับสร้างคำสั่งซื้อเข้าหน้าชำระเงินของคุณ
ระดับบนสุดของ JSON ตอบกลับมี code、message、data และ sign ในตัวอย่างปกติ code เป็น 0;data มี duplicate、id、platformOrderNo、orderStatus、payUrl、channelErrorMessage。
เก็บหมายเลขคำสั่งซื้อแพลตฟอร์มเพื่อสอบถาม จับคู่การแจ้ง และกระทบยอด แสดงช่องทางชำระเงินเมื่อได้รับ payUrl ที่ใช้ได้จริงเท่านั้น ค่านี้อาจว่าง ห้ามประกอบ URL แคชเชียร์ขึ้นเอง ตรวจโปรโตคอลและโดเมนปลายทางของลิงก์ โดยกำหนดขอบเขตอนุญาตตอนเชื่อมต่อเทคนิค
code=0 ไม่ได้แปลว่าชำระเงินเข้าแล้ว ห้ามส่งรหัสหรือสินค้าโดยตรง แม้ได้หมายเลขคำสั่งซื้อแพลตฟอร์มแล้วก็ยังต้องรอผลชำระสำเร็จที่เชื่อถือได้ รายละเอียดรหัสข้อผิดพลาดและตรวจลายเซ็นตอบกลับให้ฝ่ายเทคนิคระบุตอนทดสอบ
API สอบถาม: GET ตรวจคำสั่งซื้อเดิม
ที่อยู่ตัวอย่าง https://gateway.example.com/api/pay/collect/query วิธี GET ลงลายเซ็นพารามิเตอร์สอบถามจริงก่อน แล้วใช้การเข้ารหัส URL มาตรฐานสร้างสตริงคำถาม
| ช่องข้อมูล | จำเป็น | กฎการกรอก |
|---|---|---|
mchId | ใช่ | หมายเลขผู้ค้าที่เป็นเจ้าของคำสั่งซื้อ |
outTradeNo | เลือกหนึ่งในสอง | หมายเลขคำสั่งซื้อผู้ค้า ระหว่างค่านี้กับ platform_order_no ให้เลือกเพียงค่าเดียว |
platform_order_no | เลือกหนึ่งในสอง | หมายเลขคำสั่งซื้อแพลตฟอร์ม ระวังใช้ชื่อแบบขีดล่าง |
reqTime | ใช่ | เวลาปัจจุบันหน่วยมิลลิวินาทีของการสอบถามครั้งนี้ |
sign | ใช่ | คำนวณใหม่ด้วยพารามิเตอร์ครั้งนี้ ไม่ใช้ลายเซ็นสร้างคำสั่งซื้อเดิม |
ในผลสอบถาม data ตัวอย่างมี platformOrderNo、merchantOrderNo、amount、currencyCode、orderStatus、payUrl ในคำขอ platform_order_no กับในผลตอบกลับ platformOrderNo เขียนต่างกัน อย่าใช้วัตถุพารามิเตอร์ร่วมกันโดยตรง
ในผลสอบถาม amount มีหน่วยและความละเอียดที่ฝ่ายเทคนิคยืนยันตอนเปิดบริการ แปลงเป็นหน่วยภายในระบบอย่างชัดเจนก่อนเทียบ อย่านำไปเทียบกับยอดสร้างคำสั่งซื้อหน่วยเฟินโดยตรง
สถานะคำสั่งซื้อและการทำงานธุรกิจที่เกี่ยวข้อง
| orderStatus | ความหมาย | วิธีจัดการในผลิตภัณฑ์ |
|---|---|---|
0 | รอชำระเงิน | แสดงว่ารอลูกค้าชำระ สอบถามตามแผน ยังไม่ส่งมอบ |
1 | ชำระเงินสำเร็จ | ตรวจผลที่เชื่อถือได้แล้วเข้าสู่กระบวนการส่งมอบแบบป้องกันผลซ้ำ |
2 | ชำระเงินล้มเหลว | บันทึกล้มเหลว ก่อนชำระใหม่ให้จัดการคำสั่งซื้อเดิมตามกฎ |
3 | ปิดแล้ว | หยุดรอ เก็บคำสั่งซื้อและบันทึกตรวจสอบ |
4 | หมดอายุแล้ว | แสดงหมดอายุ จัดการการซื้อใหม่และเงินเข้าผิดปกติตามข้อตกลง |
HTTP หมดเวลารอไม่ใช่สถานะคำสั่งซื้อ ให้บันทึกว่า “รอยืนยันผล” และสอบถามด้วยหมายเลขคำสั่งซื้อผู้ค้าเดิม ก่อนยืนยันผลอย่าตัดสินว่าคำขอเดิมล้มเหลวแน่นอน และอย่าเปลี่ยนหมายเลขเพื่อหลบการตรวจซ้ำ
Callback และการสอบถามใช้ฟังก์ชันประมวลผลการชำระเงินเดียวกัน
- ค้นหาคำสั่งซื้อเดิมอ่านบันทึกในระบบด้วยหมายเลขผู้ค้าและหมายเลขคำสั่งซื้อผู้ค้า ยืนยันลูกค้าที่เป็นเจ้าของและสภาพแวดล้อม
- ตรวจผลที่เชื่อถือได้ตรวจลายเซ็น callback ก่อน ส่วนการสอบถามใช้คำขอฝั่งเซิร์ฟเวอร์ที่ป้องกันแล้ว และตรวจผลตอบกลับตามข้อกำหนดทดสอบร่วม
- อัปเดตแบบป้องกันผลซ้ำร่วมกันบันทึกสถานะสำเร็จลงฐานข้อมูลครั้งเดียว งานส่งมอบใช้คีย์ธุรกิจเฉพาะ
- บันทึกข้อมูลไม่ตรงกันหยุดส่งมอบเมื่อจำนวนเงิน สกุลเงิน หรือสถานะไม่ตรง ให้ฝ่ายเทคนิคช่วยตรวจสอบ
อ่านต่อ กฎลายเซ็น และ รายละเอียดจัดการ callback บทความนี้เรียบเรียงตามข้อกำหนดการเชื่อมต่อ 稳付pay
ยืนยันการเชื่อมต่อให้ตรงธุรกิจของคุณ
แจ้งสินค้า ปริมาณคำสั่งซื้อ วิธีชำระเงิน และความต้องการชำระยอด เพื่อยืนยัน API เส้นทางเงิน และการจัดการปัญหาทีละข้อ
ติดต่อ 稳付pay ↗