หากต้องการทดสอบ Sandbox Webhooks ของ PayPal บน localhost ให้เรียกใช้ Listener ของคุณในเครื่อง เปิดเผยเส้นทางผ่านอุโมงค์ HTTPS สาธารณะ ลงทะเบียน URL นั้นในแอป Sandbox และทริกเกอร์ธุรกรรม Sandbox จริงหรือเหตุการณ์จำลองใน Webhooks Simulator ของ PayPal เปิดใช้งานการตรวจสอบความถูกต้องของลายเซ็นไว้: เหตุการณ์จำลองและเหตุการณ์ Sandbox ที่เกี่ยวข้องกับแอปมีการอธิบายความแตกต่างในการตรวจสอบที่สำคัญ ด้านล่าง.
ทำไม PayPal ไม่สามารถส่งโดยตรงไปยัง localhost
PayPal ส่งการแจ้งเตือน webhook จากเซิร์ฟเวอร์ของตัวเอง ที่อยู่เช่น http://localhost:3000/api/paypal ชี้ไปที่เครื่องของ PayPal จากมุมมองของ PayPal ไม่ใช่ของคุณ localhost tunnel ให้ที่อยู่ HTTPS สาธารณะแก่กระบวนการในเครื่องในขณะที่ออกจากแอปพลิเคชันบนคอมพิวเตอร์ของคุณ
เอกสาร PayPal Webhooks Simulator อย่างเป็นทางการ ระบุว่า Listener จะต้องสามารถเข้าถึงได้ผ่าน HTTPS บนพอร์ต 443 อุโมงค์จะจัดการตำแหน่งข้อมูล TLS สาธารณะและส่งต่อคำขอไปยังพอร์ตในเครื่องใดๆ เช่น 3000 หรือ 8080
เลือกเส้นทางทดสอบ PayPal ที่ถูกต้อง
เหตุการณ์จำลองจำลองเพื่อการพัฒนาผู้ฟัง
เครื่องจำลองสามารถส่งเหตุการณ์ที่เป็นตัวแทน รวมถึงการเรียกเก็บเงิน การคืนเงิน และเหตุการณ์การเรียกเก็บเงิน โดยไม่ต้องสร้างธุรกรรม นี่เป็นวิธีที่เร็วที่สุดในการยืนยันการกำหนดเส้นทาง การแยกวิเคราะห์ JSON รหัสตอบกลับ และการจัดส่งกิจกรรม กิจกรรมจำลองไม่เชื่อมโยงกับแอป REST ไม่ปรากฏในโปรแกรมดูเหตุการณ์ webhook ของแอป ไม่สามารถส่งซ้ำได้ และไม่แสดงถึงธุรกรรมจริง
เหตุการณ์แซนด์บ็อกซ์จริงสำหรับพฤติกรรมตั้งแต่ต้นทางถึงปลายทาง
สำหรับการผสานรวมที่สมจริง ให้สร้างแอป REST ในแดชบอร์ดนักพัฒนาของ PayPal เพิ่มจุดสิ้นสุดทันเนลเป็นเว็บฮุค เลือกประเภทเหตุการณ์ที่ต้องการ และดำเนินการชำระเงินแบบแซนด์บ็อกซ์หรือการดำเนินการ API ให้เสร็จสิ้น กิจกรรมเหล่านั้นเป็นของแอป Sandbox และใช้ข้อมูลประจำตัวแอปเดียวกัน, Webhook ID, โปรแกรมดูเหตุการณ์ และส่งเวิร์กโฟลว์ที่คุณจะใช้ก่อนการผลิตอีกครั้ง
ตั้งค่าเว็บฮุค PayPal บน localhost
- เริ่มแอปพลิเคชันของคุณและยืนยันว่าเส้นทางใช้งานได้ในเครื่อง:
curl -i -X POST http://localhost:3000/api/webhooks/paypal -H 'content-type: application/json' -d '{"event_type":"LOCAL.PING"}'. - เรียกใช้
npx portpreview 3000และคัดลอก HTTPS URL ที่สร้างขึ้น - สร้างการติดต่อกลับแบบเต็ม เช่น
https://your-subdomain.portpreview.dev/api/webhooks/paypal. - สำหรับการทดสอบจำลอง ให้วางลงใน Webhooks Simulator และเลือกเหตุการณ์ สำหรับการทดสอบแอป ให้เพิ่มไว้ใต้การตั้งค่าเว็บฮุคของแอป Sandbox REST
- ส่งกิจกรรมและตรวจสอบวิธีการขาเข้า ส่วนหัวของ PayPal เนื้อความดิบ บันทึกของตัวจัดการ และการตอบกลับ HTTP
สมัครเฉพาะกิจกรรมที่แอปพลิเคชันของคุณจัดการเท่านั้น การสมัครรับข้อมูลแบบกว้างๆ จะสร้างเสียงรบกวนและทำให้ง่ายต่อการเรียกใช้ตรรกะทางธุรกิจโดยไม่ได้ตั้งใจสำหรับเหตุการณ์ที่คุณไม่เคยสร้างแบบจำลอง
A practical Express listener
import express from 'express';
const app = express();
app.use(express.json({ verify: (req, _res, buf) => {
req.rawBody = Buffer.from(buf);
}}));
app.post('/api/webhooks/paypal', async (req, res) => {
const event = req.body;
// Verify first; do not fulfill an order from untrusted JSON.
const verified = await verifyPayPal(req.headers, event);
if (!verified) return res.status(401).send('invalid signature');
// Claim the event ID atomically so retries cannot duplicate work.
const firstDelivery = await claimEvent(event.id);
if (!firstDelivery) return res.sendStatus(200);
if (event.event_type === 'PAYMENT.CAPTURE.COMPLETED') {
await markOrderPaid(event.resource.id);
}
return res.sendStatus(200);
});
app.listen(3000);ทำให้การรับทราบสั้นลง จัดเก็บกิจกรรม ส่งคืนการตอบกลับ 2xx และดำเนินการอีเมลหรือการดำเนินการตามคำสั่งซื้อที่ช้าในคิว รหัสเหตุการณ์คือคีย์ idempotency โดยธรรมชาติ บังคับใช้ข้อจำกัดฐานข้อมูลที่ไม่ซ้ำกันแทนที่จะอาศัยชุดในหน่วยความจำ
ตรวจสอบลายเซ็น PayPal อย่างถูกต้อง
PayPal ส่งข้อมูลเมตาการส่งข้อมูลในส่วนหัว ได้แก่ PAYPAL-AUTH-ALGO, PAYPAL-CERT-URL, PAYPAL-TRANSMISSION-ID, PAYPAL-TRANSMISSION-SIG และ PAYPAL-TRANSMISSION-TIME สำหรับเหตุการณ์ที่เกี่ยวข้องกับแอป คุณสามารถส่งค่าเหล่านั้น รหัส webhook และกิจกรรมไปยังแซนด์บ็อกซ์ /v1/notifications/verify-webhook-signature API การตอบสนอง HTTP ที่สำเร็จนั้นไม่เพียงพอ ต้องการ verification_status เท่ากับ SUCCESS PayPal ยังบันทึกการยืนยันการเข้ารหัสลับในพื้นที่ไว้ใน คู่มือการรวม webhook.
คำเตือนการจำลอง: จุดสิ้นสุดการยืนยัน postback ของ PayPal ไม่รองรับเหตุการณ์การจำลอง PayPal บันทึกรหัส webhook ตามตัวอักษร WEBHOOK_ID สำหรับการยืนยันลายเซ็นจำลองด้วยตนเอง อย่าสับสนระหว่างค่าพิเศษนั้นกับรหัส webhook จริงที่กำหนดให้กับแอปแซนด์บ็อกซ์ หากเป้าหมายเร่งด่วนของคุณคือการทดสอบ Postback API ให้สร้างธุรกรรมแซนด์บ็อกซ์จริงแทนเหตุการณ์จำลองจำลอง
ตรวจสอบว่า URL ใบรับรองใดๆ เป็นไปตามกฎที่บันทึกไว้ของ PayPal ก่อนที่จะดาวน์โหลด รักษาการแสดงเหตุการณ์ที่แน่นอนตามที่วิธีการตรวจสอบกำหนด และไม่บันทึกโทเค็นการเข้าถึง ข้อมูลลับของลูกค้า ลายเซ็น หรือเพย์โหลดการชำระเงินที่สมบูรณ์
ทดสอบกิจกรรมที่เปลี่ยนเงินหรือเข้าถึง
PAYMENT.CAPTURE.COMPLETED: ให้ดำเนินการหลังจากตรวจสอบตัวระบุคำสั่งซื้อ จำนวนเงิน สกุลเงิน และสถานะการจับที่คาดไว้เท่านั้นPAYMENT.CAPTURE.REFUNDED: ย้อนกลับการให้สิทธิ์อย่างปลอดภัยและสนับสนุนการคืนเงินบางส่วน- เหตุการณ์ใบสั่งชำระเงิน: แยกการอนุมัติจากการบันทึกที่เสร็จสมบูรณ์ การอนุมัติเพียงอย่างเดียวไม่ใช่ข้อพิสูจน์ว่าเงินถูกยึด
- เหตุการณ์การสมัครรับข้อมูล: ทดสอบการเปิดใช้งาน การระงับ การยกเลิก การชำระเงินล้มเหลว และการจัดส่งที่ไม่อยู่ในคำสั่งซื้อตามเครื่องสถานะการเรียกเก็บเงินของคุณ
เหตุการณ์ของผู้ให้บริการคือการแจ้งเตือน ไม่ใช่คำสั่งฐานข้อมูลที่ไม่ต้องสงสัย สำหรับการเปลี่ยนแปลงที่ละเอียดอ่อน ให้ดึงข้อมูลทรัพยากร PayPal ที่อ้างอิงด้วยข้อมูลประจำตัว API ที่ได้รับการรับรองความถูกต้อง และเปรียบเทียบกับบันทึกคำสั่งซื้อของคุณเอง
แก้ปัญหาการจัดส่งในพื้นที่ล้มเหลว
เครื่องจำลองไม่สามารถเชื่อมต่อ
ยืนยันว่า URL ขึ้นต้นด้วย https:// รวมเส้นทาง webhook ที่แน่นอน และยังคงชี้ไปยังอุโมงค์ที่กำลังทำงานอยู่ ทดสอบ URL สาธารณะด้วยตัวเองด้วย curl โดยทั่วไปแล้ว 404 หมายถึงเส้นทางหรือเส้นทางกรอบงานไม่ถูกต้อง โดยทั่วไป 502 หมายความว่าอุโมงค์ไม่สามารถเข้าถึงกระบวนการในเครื่องได้
ตัวจัดการส่งคืน 401
ขั้นแรกให้พิจารณาว่าเหตุการณ์มาจากโปรแกรมจำลองหรือแอปแซนด์บ็อกซ์ที่ลงทะเบียนไว้หรือไม่ ตรวจสอบรหัสเว็บฮุคและวิธีการยืนยันตามนั้น จากนั้นตรวจสอบว่าพรอกซีรักษาส่วนหัว PAYPAL-* ทั้งหมดไว้ และคุณไม่ได้ผสมข้อมูลประจำตัวแบบสดกับ api-m.sandbox.paypal.com.
PayPal ลองใหม่หรือทำเครื่องหมายว่าการจัดส่งล้มเหลว
คืน 2xx หลังจากที่กิจกรรมได้รับการยอมรับอย่างถาวรแล้วเท่านั้น หลีกเลี่ยงการเปลี่ยนเส้นทาง หน้าแสดงข้อผิดพลาด HTML มิดเดิลแวร์การตรวจสอบสิทธิ์ และงานซิงโครนัสที่ยาวบนเส้นทาง ใช้ตัวแสดงเหตุการณ์สำหรับเหตุการณ์แอปจริงและผลลัพธ์ของตัวจำลองสำหรับการวินิจฉัยการนำส่งจำลอง ดู คำแนะนำการลองซ้ำและ idempotency สำหรับรูปแบบการประมวลผลที่คงทน
รายการตรวจสอบความปลอดภัยก่อนถ่ายทอดสด
- ใช้แซนด์บ็อกซ์และข้อมูลประจำตัวไคลเอ็นต์ที่ใช้งานจริงแยกกัน ID เว็บฮุค และความลับปลายทาง
- ตรวจสอบทุกลายเซ็นก่อนแยกวิเคราะห์ฟิลด์ธุรกิจหรือเปลี่ยนสถานะ
- ทำซ้ำด้วยรหัสเหตุการณ์ของ PayPal และสร้างธุรกรรมตามคำสั่งซื้อแบบอะตอมมิก.
- อนุญาตเพียง
POST, ขนาดคำขอสูงสุด, ใช้ขีดจำกัดอัตรา และเก็บ URL ของช่องสัญญาณเป็นส่วนตัวเมื่อเป็นไปได้ - ปกปิดข้อมูลผู้ซื้อและข้อมูลรับรองจากบันทึก หมุนสิ่งที่เปิดเผยระหว่างการดีบัก
- แทนที่ URL ช่องสัญญาณชั่วคราวด้วยจุดสิ้นสุดการใช้งานจริงที่เสถียร และทำการทดสอบลายเซ็นซ้ำและลองอีกครั้ง
สำหรับกิจกรรมทั้งหมดและสคีมาการยืนยัน ให้ใช้ การอ้างอิง Webhooks API หลักของ PayPal สำหรับรายละเอียดที่ไม่ขึ้นอยู่กับเฟรมเวิร์กเกี่ยวกับเนื้อหาดิบและการเปรียบเทียบที่ปลอดภัย โปรดอ่าน คู่มือการตรวจสอบลายเซ็น webhook.