PayPal

ตำแหน่งในส่วนผู้ดูแล: Finance › Payment channels › PayPal (/payments/paypal) สวิตช์เปิด/ปิดและค่าธรรมเนียมอยู่ที่ Finance › Payment channels › Fees & limits (/payments/fees)

What it does

ช่วยให้ลูกค้าสามารถเติมเงินในกระเปเงิน USD ด้วยยอดคงเหลือใน PayPal, บัญชีธนาคาร หรือบัตรที่ผูกไว้กับ PayPal ได้ ลูกค้ายังสามารถให้ NexCMP จดจำบัญชี PayPal สำหรับการ เติมเงินอัตโนมัติ ใช้ควบคู่ไปกับ Stripe สำหรับลูกค้าที่ชื่นชอบ PayPal

ข้อกำหนด

Item	Requirement
PayPal account	บัญชี PayPal แบบ Business ที่สามารถรับเงินสกุล USD ได้
REST app	แอป REST หนึ่งแอปในแดชบอร์ดนักพัฒนา PayPal (Apps & Credentials) ซึ่งให้ Client ID และ Client secret ใช้แท็บ Sandbox สำหรับการทดสอบ และ Live สำหรับการใช้งานจริง
Network	HTTPS สามารถเข้าถึงได้จากอินเทอร์เน็ต (PayPal เรียกเว็บฮุก) และการเข้าถึงขาออกไปยัง api-m.paypal.com (ใช้งานจริง) หรือ api-m.sandbox.paypal.com (แซนด์บ็อกซ์) พอร์ต 443
สิทธิ์การใช้งาน	แอป REST ต้องการความสามารถในการคืนเงิน (Refund) และเว็บฮุก กล่องโต้ตอบ Check จะแสดงว่ามีขอบเขต (Scopes) ทั้งสองครบถ้วนหรือไม่
Dependencies	ไม่มี

เตรียมโครงสร้างพื้นฐาน

1. ลงชื่อเข้าใช้ developer.paypal.com ด้วยบัญชีธุรกิจของคุณและเปิด Apps & Credentials
2. เลือก Sandbox (ทดสอบ) หรือ Live แล้วคลิก Create App ตั้งชื่อ เช่น "NexCMP"
3. คัดลอก Client ID และ Secret ของแอป
4. สำหรับการทดสอบ ให้ใช้ Testing Tools › Sandbox Accounts เพื่อค้นหาหรือสร้างบัญชีแซนด์บ็อกซ์ประเภท Personal (ผู้ซื้อ)
5. คุณไม่จำเป็นต้องสร้างเว็บฮุกด้วยตัวเอง; NexCMP จะสร้างให้ด้วยปุ่ม Create webhook

เชื่อมต่อใน NexCMP

1. เปิด Finance › Payment channels › PayPal (/payments/paypal)
2. ใน API keys ให้เลือก Mode: live (เงินจริง, api-m.paypal.com) หรือ sandbox (api-m.sandbox.paypal.com)
3. วาง Client ID (อย่างน้อย 20 ตัวอักษร) และ Client secret
4. คลิก Check โดยระบบจะทดสอบข้อมูลประจำตัวที่คุณพิมพ์ (ไม่ต้องบันทึก) และรายงานผลการเชื่อมต่อ, App ID, โหมด, ขอบเขตสิทธิ์ refund และ webhooks ว่ามีอยู่หรือไม่ รวมถึงอายุของโทเค็น
5. คลิก Save
6. ในการ์ด Webhook ให้ยืนยันว่า URL คือ https://<your-domain>/v1/billing/paypal/webhook (ต้องเป็น https) จากนั้นคลิก Create webhook และยืนยัน NexCMP จะร้องขอให้ PayPal สร้างหรืออัปเดตเว็บฮุกด้วยเหตุการณ์ 11 รายการและจัดเก็บ Webhook ID ที่ส่งกลับมา ปุ่มนี้จะใช้คีย์ที่ บันทึกไว้ ดังนั้นควรบันทึกก่อนหากคุณเพิ่งแก้ไข
7. คลิก Check อีกครั้ง: แถว Webhook ควรแสดงข้อความ "exists, 11 events"
8. เปิด Fees & limits เปิดใช้งาน PayPal ตั้งค่า PayPal fee % (ค่าเริ่มต้น 4.4) และ PayPal fixed fee (cents) (ค่าเริ่มต้น 30) ตามอัตราค่าบริการของคุณ แล้วคลิก Save channels & fees

Webhook events

NexCMP จะลงทะเบียนเหตุการณ์ 11 รายการเหล่านี้: CHECKOUT.ORDER.APPROVED, PAYMENT.CAPTURE.COMPLETED, PAYMENT.CAPTURE.PENDING, PAYMENT.CAPTURE.DECLINED, PAYMENT.CAPTURE.REFUNDED, PAYMENT.CAPTURE.REVERSED, CUSTOMER.DISPUTE.CREATED, CUSTOMER.DISPUTE.UPDATED, CUSTOMER.DISPUTE.RESOLVED, RISK.DISPUTE.CREATED, CHECKOUT.PAYMENT-APPROVAL.REVERSED

เว็บฮุกแต่ละรายการจะถูกตรวจสอบโดยการเรียก API ตรวจสอบลายเซ็นของ PayPal จัดเก็บไว้หนึ่งครั้ง และประมวลผลแบบไอเด็มโพเทนต์ NexCMP จะไม่เชื่อถือยอดเงินในเนื้อหาเว็บฮุก: ก่อนที่จะเติมเงินจากการจับภาพ จะทำการดึงข้อมูลการจับภาพนั้นจาก PayPal ก่อน

ตรวจสอบ

1. คงค่า Mode ไว้ที่ sandbox ในพอร์ทัล ให้เปิด Billing › Deposit เลือก PayPal คลิก Continue on PayPal (หรือปุ่ม PayPal) แล้วเข้าสู่ระบบด้วยบัญชีผู้ซื้อ sandbox
2. อนุมัติการชำระเงิน คุณจะกลับมาที่พอร์ทัล ยอดเงินคงเหลือจะเพิ่มขึ้น และการชำระเงินจะปรากฏภายใต้ Finance › Billing › Top-ups ในสถานะ Completed
3. เปิด Payment channels › Gateway events › PayPal & USDT: เหตุการณ์ PAYMENT.CAPTURE.COMPLETED จะแสดงอยู่ในรายการ
4. เมื่อทุกอย่างทำงานได้ ให้สลับ Mode เป็น live กรอกข้อมูลประจำตัวจริง Save จากนั้นคลิก Create webhook อีกครั้ง (เว็บฮุกของ sandbox และ live จะแยกออกจากกัน)

ขีดจำกัดและหมายเหตุ

• การชำระเงินเสร็จสมบูรณ์อย่างไร คำสั่งซื้อจะถูกสร้างขึ้นในสกุลเงิน USD หลังจากที่ลูกค้าอนุมัติแล้ว เซิร์ฟเวอร์ จะทำการจับภาพ (รหัสคำสั่งซื้อแบบไอเด็มโพเทนต์) และเติมเงินเข้ากระเป๋าเงินให้พอดีหนึ่งครั้ง เว็บฮุกและงานตรวจสอบความถูกต้องที่ทำงานทุกๆ 10 นาทีจะเป็นระบบสำรองความปลอดภัยในกรณีที่ลูกค้าปิดเบราว์เซอร์
• คำสั่งซื้อที่รอดำเนินการและถูกยกเลิก คำสั่งซื้อสามารถเปิดค้างไว้ได้ 12 ชั่วโมง ลูกค้าสามารถมีคำสั่งซื้อที่รอดำเนินการได้สูงสุด 5 รายการ (เซิร์ฟเวอร์จะตอบกลับด้วย too_many_pending, HTTP 429) คำสั่งซื้อที่ยังไม่ถูกจับภาพหลังจากผ่านไป 24 ชั่วโมงจะถูกทำเครื่องหมายว่าล้มเหลว
• ไม่ได้กำหนดค่าเว็บฮุก แผงควบคุมจะตอบกลับด้วย HTTP 503 สำหรับเว็บฮุกทุกรายการของ PayPal จนกว่าจะมีการบันทึก Webhook ID การจับภาพที่ทำผ่านพอร์ทัลและการตรวจสอบความถูกต้องทุกๆ 10 นาทีจะยังคงเติมเงินเข้ากระเป๋าเงิน แต่เหตุการณ์ใดๆ ที่ PayPal รายงานผ่านเว็บฮุก (ข้อพิพาท, การเรียกคืนเงิน, การจับภาพล่าช้า) จะไม่ถูกนำมาใช้ — ให้คลิก Create webhook
• บันทึกบัญชี PayPal แล้ว เมื่อลูกค้าเลือกที่จะบันทึก PayPal (หรือทำการฝากเงินครั้งแรก ซึ่งจะเปิดใช้งาน automatic top-up) PayPal จะจัดเก็บโทเค็นการชำระเงินไว้ในห้องนิรภัย NexCMP จะเก็บบันทึกเพียงตัวระบุและอีเมล PayPal เท่านั้น ดูข้อมูลเพิ่มเติมที่ Saved payment methods
• การคืนเงินและข้อพิพาท จะได้รับการจัดการเช่นเดียวกับ Stripe: คำขอคืนเงินจะได้รับการอนุมัติภายใต้ Finance › Payouts › Card refunds และข้อพิพาทจะบล็อกบัญชีของลูกค้าพร้อมระงับบริการแบบชำระเงินล่วงหน้าจนกว่าคุณจะแก้ไขเสร็จสิ้น
• ค่าธรรมเนียม ค่าธรรมเนียมของ PayPal จะไม่ถูกอ่านกลับ ค่าเปอร์เซ็นต์และค่าธรรมเนียมคงวัลที่คุณกำหนดจะเป็นตัวกำหนดสิ่งที่ลูกค้าเห็นและยอดเงินที่จะได้รับเครดิต อัตราค่าบริการที่แท้จริงจะขึ้นอยู่กับประเทศของคุณ (แบบฟอร์มแนะนำ 4.4% สำหรับเวียดนามและ 3.49% สำหรับสหรัฐอเมริกา)

การแก้ Problme

อาการ	สาเหตุ	วิธีแก้ปัญหา
"Client ID สั้นเกินไป"	มีการวางข้อความน้อยกว่า 20 ตัวอักษร	คัดลอก Client ID เต็ม
"Webhook URL ต้องเป็น https"	พิมพ์ URL โดยมี http://	ใช้โดเมนสาธารณะ https:// ของคุณ
การตรวจสอบรายงานข้อผิดพลาดในการเชื่อมต่อ	โหมดไม่ถูกต้อง (คีย์ใช้งานจริงในแซนด์บ็อกซ์หรือกลับกัน), รหัสลับไม่ถูกต้อง, ไม่มีสิทธิ์เข้าถึงขาออก	จับคู่ Mode กับประเภทคีย์; ทดสอบ curl -I https://api-m.paypal.com จากเซิร์ฟเวอร์
สโคปการคืนเงิน / webhook แสดง "no"	แอป REST ขาดฟีเจอร์ดังกล่าว	เปิดใช้งานฟีเจอร์บนแอปใน PayPal Developer Dashboard
แบนเนอร์ "ตั้งค่าคีย์ PayPal แล้ว แต่ไม่มี webhook"	11: ไม่พบ Webhook ID	คลิก Create webhook
"ไม่พบ Webhook" ในการตรวจสอบ	Webhook ถูกลบที่ PayPal หรือเป็นของแอปอื่น	คลิก Create webhook อีกครั้ง
ลูกค้าได้รับแจ้งว่า PayPal ปฏิเสธการชำระเงิน	PayPal ปฏิเสธแหล่งเงินทุนนั้น	ขอให้ลูกค้าเลือกแหล่งชำระเงินอื่น
ลูกค้าเห็นข้อความ "คำขอรอดำเนินการมากเกินไป"	5 คำคนที่ยังไม่ปิด	รอให้หมดอายุหรือดำเนินการให้เสร็จสิ้น
ปุ่ม PayPal หายไป	ปิด PayPal ไว้ใน Fees & limits หรือยังไม่ได้กำหนดค่า	เปิดใช้งานและบันทึกข้อมูลรับรอง