API รับชำระแทน

สร้างและสอบถามรับชำระแทน: ช่องข้อมูล จำนวนเงิน และสถานะคำสั่งซื้อ

เซิร์ฟเวอร์คุณต้องบันทึกคำสั่งซื้อธุรกิจในระบบก่อน แล้วจึงสร้างคำสั่งซื้อรับชำระแทน หากเครือข่ายหมดเวลารอหรือผลชำระเงินไม่ชัด ให้สอบถามด้วยหมายเลขคำสั่งซื้อผู้ค้าเดิม การเรียกทั้งสองแบบต้องใช้หมายเลขผู้ค้า เวลาปัจจุบันหน่วยมิลลิวินาที และลายเซ็นจากเซิร์ฟเวอร์

สารบัญบทความ

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 ในคำขอจริงต้องเป็นจำนวนเต็มมิลลิวินาทีปัจจุบัน คำนวณลายเซ็นใหม่ก่อนส่ง

ตัวอย่างช่องข้อมูล 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"
}
ประกอบข้อมูลฝั่งเซิร์ฟเวอร์ด้วย 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"
วิธีส่งด้วย cURL
curl --request POST "$API_BASE_URL/api/pay/collect/create" \
  --header "Content-Type: application/json; charset=UTF-8" \
  --data @collect-create.json

ดาวน์โหลดฟังก์ชันลายเซ็น Python ที่ใช้ในตัวอย่าง ดูกฎคำนวณที่ ลงลายเซ็นและตรวจ MD5。

สอบถามคำสั่งซื้อ: ลงลายเซ็นก่อน แล้วเข้ารหัสสตริงคำถาม

พารามิเตอร์ Python GET
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 และการสอบถามใช้ฟังก์ชันประมวลผลการชำระเงินเดียวกัน

  1. ค้นหาคำสั่งซื้อเดิมอ่านบันทึกในระบบด้วยหมายเลขผู้ค้าและหมายเลขคำสั่งซื้อผู้ค้า ยืนยันลูกค้าที่เป็นเจ้าของและสภาพแวดล้อม
  2. ตรวจผลที่เชื่อถือได้ตรวจลายเซ็น callback ก่อน ส่วนการสอบถามใช้คำขอฝั่งเซิร์ฟเวอร์ที่ป้องกันแล้ว และตรวจผลตอบกลับตามข้อกำหนดทดสอบร่วม
  3. อัปเดตแบบป้องกันผลซ้ำร่วมกันบันทึกสถานะสำเร็จลงฐานข้อมูลครั้งเดียว งานส่งมอบใช้คีย์ธุรกิจเฉพาะ
  4. บันทึกข้อมูลไม่ตรงกันหยุดส่งมอบเมื่อจำนวนเงิน สกุลเงิน หรือสถานะไม่ตรง ให้ฝ่ายเทคนิคช่วยตรวจสอบ

อ่านต่อ กฎลายเซ็น และ รายละเอียดจัดการ callback บทความนี้เรียบเรียงตามข้อกำหนดการเชื่อมต่อ 稳付pay

ยืนยันการเชื่อมต่อให้ตรงธุรกิจของคุณ

แจ้งสินค้า ปริมาณคำสั่งซื้อ วิธีชำระเงิน และความต้องการชำระยอด เพื่อยืนยัน API เส้นทางเงิน และการจัดการปัญหาทีละข้อ

ติดต่อ 稳付pay ↗