Stripe

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

What it does

Stripe รองรับการชำระเงินผ่านบัตรสำหรับการเติมเงินในวอลเล็ต ด้วยบัญชีเดียวกันคุณยังสามารถเปิดใช้งาน Apple Pay, Google Pay, Link และ Alipay รวมถึงให้ลูกค้า บันทึกบัตร สำหรับการ เติมเงินอัตโนมัติ ได้ ใช้เป็นช่องทางหลักสำหรับลูกค้าระหว่างประเทศ

ข้อกำหนด

Item	Requirement
บัญชี Stripe	บัญชี Stripe ที่สามารถรับชำระเงินเป็น USD ได้ Alipay จะถูกเรียกเก็บเงินเป็น JPY และต้องเปิดใช้งานโดย Stripe สำหรับบัญชีของคุณ
คีย์	ซีเคร็ตคีย์ (sk_live_... หรือ sk_test_...) และพับลิชเบิลคีย์ (pk_live_... หรือ pk_test_...) ฟอร์มจะยอมรับเฉพาะคีย์ที่มีคำนำหน้าเหล่านี้เท่านั้น
Network	แผงควบคุมของคุณต้องสามารถเข้าถึงได้ผ่าน HTTPS จากอินเทอร์เน็ต (Stripe จะเรียกเว็บฮุก) และต้องสามารถเข้าถึง api.stripe.com ที่พอร์ต 443 ได้
โดเมน (สำหรับวอลเล็ตเท่านั้น)	โดเมนฝั่งลูกค้าต้องให้บริการ /.well-known/apple-developer-merchantid-domain-association ซึ่ง NexCMP จะจัดการส่วนนี้ให้คุณ
Dependencies	ไม่มี

บัญชี Stripe ที่ใช้ร่วมกัน

NexCMP จะประมวลผลเหตุการณ์เว็บฮุกเฉพาะสำหรับการชำระเงินที่สร้างขึ้นเองเท่านั้น คุณจึงสามารถใช้บัญชี Stripe ที่ใช้งานร่วมกับแอปพลิเคชันอื่นได้

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

ฝั่ง Stripe:

1. ลงชื่อเข้าใช้ Stripe Dashboard สลับ Test mode เปิดหรือปิดเพื่อเลือกว่าคุณกำลังทดลองใช้งานหรือใช้งานจริง คีย์ของโหมดหนึ่งจะไม่สามารถใช้ร่วมกับอีกโหมดหนึ่งได้
2. เปิดไปที่ Developers › API keys คัดลอก Publishable key รวมถึงแสดงและคัดลอก Secret key เก็บซีเคร็ตคีย์ไว้เป็นความลับ
3. (ไม่บังคับ) เปิดไปที่ Settings › Payment methods และเปิดใช้งาน Alipay หากคุณต้องการให้บริการ
4. คุณ ไม่จำเป็น ต้องสร้างเว็บฮุกด้วยตนเอง เนื่องจาก NexCMP สามารถสร้างให้คุณได้ (ดูขั้นตอนที่ 5 ด้านล่าง) หากคุณต้องการทำด้วยตนเอง ให้สร้างเอนด์พอยต์ใน Developers › Webhooks ด้วย URL และเหตุการณ์ที่ระบุไว้ใน Webhook

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

1. เปิดไปที่ Finance › Payment channels › Stripe (/payments/stripe)
2. ในการ์ด API keys ให้เลือก Mode (live หรือ test) วาง Secret key และ Publishable key
3. คลิก Save คีย์จะถูกเขียนลงในไฟล์กำหนดค่าบนเซิร์ฟเวอร์ซึ่งบัญชีบริการของ NexCMP เท่านั้นที่สามารถอ่านได้ โดยจะไม่ถูกส่งกลับไปยังเบราว์เซอร์อีก หลังจากนั้นหน้าเว็บจะแสดงเพียง 4 ตัวอักษรสุดท้ายเท่านั้น
4. คลิก Check กล่องข้อความจะรายงานสถานะการเชื่อมต่อ โหมด ยอดเงินคงเหลือและยอดเงินรอดำเนินการ รหัสบัญชี สถานะการเปิดใช้งานการชำระเงิน การมีอยู่ของเว็บฮุก และความพร้อมใช้งานของ Alipay เส้นสีแดงหมายถึงส่วนนั้นต้องได้รับการตรวจสอบ
5. ในการ์ด Webhook คลิก Create webhook และยืนยัน NexCMP จะขอให้ Stripe สร้างเอนด์พอยต์พร้อมทุกเหตุการณ์ที่จำเป็นและเติมข้อมูลใน Webhook signing secret (whsec_...) โดยอัตโนมัติ URL ที่กรอกไว้ล่วงหน้าในฟิลด์คือ https://<your-domain>/v1/billing/stripe/webhook เช่น https://cloud.example.com/v1/billing/stripe/webhook
6. เปิดไปที่ Fees & limits (/payments/fees) เปิดใช้งาน Card (Stripe) กำหนดค่า Stripe fee % และ Stripe fixed fee (cents) ตามอัตราค่าธรรมเนียมจริงของคุณ แล้วคลิก Save channels & fees ดูเพิ่มเติมที่ Payment channels

Webhook

แถบแบนเนอร์สีแดง "Missing webhook_secret" จะยังคงแสดงอยู่จนกว่าจะบันทึก signing secret หากไม่มีค่านี้ การเติมเงินผ่าน Stripe จะไม่ถูกบันทึก แม้ว่า Stripe จะตัดเงินไปแล้วก็ตาม

Item	ค่า
URL	https://<your-domain>/v1/billing/stripe/webhook
Events	checkout.session.completed, payment_intent.succeeded, payment_intent.payment_failed, charge.refunded, charge.dispute.created, charge.dispute.closed, radar.early_fraud_warning.created, refund.updated, refund.failed
Signature	ส่วนหัว Stripe Stripe-Signature, HMAC-SHA256, ค่าความคลาดเคลื่อน 300 วินาที คำขอที่มีลายเซ็นไม่ถูกต้องจะได้รับ HTTP 400
Idempotency	แต่ละ event ID จะถูกจัดเก็บเพียงครั้งเดียว การส่งข้อมูลซ้ำจะไม่เพิ่มเครดิตเป็นสองเท่า

หากคุณอัปเกรดจากเวอร์ชันที่มีการลงทะเบียนอีเวนต์น้อยกว่า ให้คลิก Create webhook อีกครั้ง — ระบบจะยังคงเก็บเอนด์พอยต์เดิมไว้ ดังนั้นให้ลบออกด้วยตนเองใน Stripe Dashboard ในภายหลัง

แถว 24h events และ Latest event ในการ์ด Webhook จะบอกว่า Stripe สามารถติดต่อแผงควบคุมได้หรือไม่ อีเวนต์แต่ละรายการจะแสดงอยู่ใน Payment channels › Gateway events (/payments/events แท็บ Stripe) ซึ่งแต่ละอีเวนต์สามารถดูข้อมูลได้ (Payload) หรือส่งซ้ำได้ (Replay)

Apple Pay, Google Pay และ Link

1. ในการ์ด Wallets (Apple Pay · Google Pay · Link) & Alipay ช่อง Customer app Domain registered with Stripe จะถูกกรอกล่วงหน้าด้วยชื่อโฮสต์ของไซต์คุณ (เช่น cloud.example.com)
2. คลิก Register / verify domain แล้วยืนยัน NexCMP จะลงทะเบียนโดเมนในโดเมนวิธีการชำระเงินของ Stripe และขอให้ Stripe ตรวจสอบความถูกต้อง
3. ผลลัพธ์จะแสดงสถานะของ Apple Pay, Google Pay และ Link โดย Apple Pay จะแสดงขึ้นก็ต่อเมื่อสถานะเป็น active เท่านั้น
4. ใน Fees & limits ให้เปิด Apple Pay · Google Pay · Link ไว้

Apple Pay ยังคงไม่ทำงาน

Apple Pay ต้องใช้ไฟล์เชื่อมโยงโดเมนเพื่อตอบกลับ HTTP 200 บนโดเมนสาธารณะของคุณ หากคุณวาง Cloudflare หรือพร็อกซีอื่นไว้ด้านหน้า อย่าบล็อก /.well-known/

Alipay

Alipay เป็นตัวเลือกเสริม เปิดใช้งานใน Stripe Dashboard › Settings › Payment methods คลิก Check แล้วรอจนกว่ากล่องข้อความจะแสดงว่า Alipay พร้อมใช้งาน จากนั้นเปิด Alipay (Stripe, JPY display) ใน Fees & limits ตั้งค่า Alipay fee %, Alipay fixed fee, ¥/USD rate (50–500) และ FX spread % (0–20) อัปเดตอัตรา ¥/USD อย่างสม่ำเสมอ โดยหน้านี้จะแจ้งเตือนเมื่อข้อมูลมีอายุเกิน 7 วัน

ตรวจสอบ

1. ในโหมดทดสอบ ให้ลงชื่อเข้าใช้พอร์ทัลในฐานะลูกค้าทดสอบ เปิด Billing คลิก Deposit เลือก Card และชำระเงินตามจำนวนขั้นต่ำด้วยบัตรทดสอบของ Stripe 4242 4242 4242 4242 (วันที่ใดก็ได้ในอนาคต CVC ใดก็ได้)
2. ยอดคงเหลือจะเพิ่มขึ้นภายในไม่กี่วินาที และรายการชำระเงินจะปรากฏใต้ Finance › Billing › Top-ups พร้อมสถานะ Completed
3. เปิด Payment channels › Gateway events › Stripe: คุณควรเห็น checkout.session.completed หรือ payment_intent.succeeded พร้อมเวลาที่ประมวลผล
4. เมื่อกลับไปที่หน้า Stripe ค่า 24h events จะมากกว่า 0

ก่อนเริ่มใช้งานจริง ให้เปลี่ยน Mode เป็น live วางคีย์สำหรับใช้งานจริง และคลิก Create webhook อีกครั้ง (เว็บฮุกของโหมดทดสอบและโหมดใช้งานจริงจะแยกจากกัน)

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

• จำนวนเงินและสกุลเงิน กระเป๋าเงินอยู่ในสกุล USD การชำระเงินผ่านบัตร วอลเล็ต และลิงก์จะถูกเรียกเก็บเป็น USD ส่วน Alipay จะแสดงให้ลูกค้าเห็นในสกุล JPY และแปลงตามอัตราแลกเปลี่ยนของคุณ
• ค่าธรรมเนียม ระบบจะไม่อ่านค่าธรรมเนียมจริงของ Stripe กลับมาโดยอัตโนมัติ เปอร์เซ็นต์ค่าธรรมเนียมที่คุณตั้งไว้จะเป็นตัวกำหนดสิ่งที่ลูกค้าเห็นและยอดเงินที่เข้ากระเป๋าเงิน เลือก Customer pays top-up fee ใน Fees & limits เพื่อเรียกเก็บค่าธรรมเนียมเพิ่มเติมจากยอดเงิน
• บัตรที่บันทึกไว้ เมื่อลูกค้าทำเครื่องหมายที่ Save card for auto top-up บัตรจะถูกจัดเก็บไว้ที่ Stripe ไม่ใช่บนเซิร์ฟเวอร์ของคุณ ดูที่ Saved payment methods
• การคืนเงิน การคืนเงินเข้าบัตรเป็นกระบวนการแบบ 2 ขั้นตอน: ผู้ดูแลระบบจะสร้างคำขอคืนเงินสำหรับการชำระเงินที่เสร็จสมบูรณ์ (Finance › Billing › Top-ups การดำเนินการคืนเงินในรายการชำระเงิน) จากนั้นจึงอนุมัติที่ Finance › Payouts › Card refunds (/billing/payouts) การคืนเงินของ Alipay จะเป็นแบบอะซิงโครนัส หากรายการล้มเหลว (refund.failed) ระบบจะคืนเงินจำนวนที่ระงับไว้กลับเข้ากระเป๋าเงิน
• ข้อพิพาท (Disputes): เมื่อ charge.dispute.created NexCMP จะบล็อกบัญชีของลูกค้า ระงับบริการแบบชำระเงินล่วงหน้า (ไม่มีการลบข้อมูลใดๆ) และส่งการแจ้งเตือนไปยังผู้ดูแลระบบ หากคุณชนะ (charge.dispute.closed) จำนวนเงินจะถูกคืนเข้ากระเปเงิน
• การรอการชำระเงิน: หากเว็บฮุกไม่มาถึง NexCMP จะตรวจสอบการชำระเงินที่ค้างอยู่เกิน 10 นาทีกับ Stripe ด้วยตนเองและทำรายการให้เสร็จสมบูรณ์ การชำระเงินที่เก่ากว่า 7 วันจะถูกละเว้น
• Resellers สามารถเชื่อมต่อบัญชี Stripe ของตนเองได้ (webhook https://<their-domain>/v1/billing/stripe/webhook/r/<id>) ดูที่ Resellers

การแก้ Problme

อาการ	สาเหตุ	วิธีแก้ปัญหา
"Secret key ต้องขึ้นต้นด้วย sk_live_ หรือ sk_test_"	วางรหัสลับผิด	วางรหัสลับจาก Developers › API keys
"Secret key ไม่ตรงกับโหมด live/test"	โหมดและรหัสไม่ตรงกัน	ทำให้ Mode ตรงกับคำนำหน้าของรหัส
"Publishable key ต้องขึ้นต้นด้วย pk_"	Wrong key	ใช้คีย์ที่เผยแพร่ได้ (Publishable key)
การตรวจสอบระบุว่าการเชื่อมต่อล้มเหลว	คีย์ไม่ถูกต้อง ถูกเพิกถอน หรือเซิร์ฟเวอร์ไม่สามารถเข้าถึง api.stripe.com ได้	วางคีย์ใหม่อีกครั้ง ทดสอบด้วย curl -I https://api.stripe.com จากเซิร์ฟเวอร์
แบนเนอร์สีแดง "Missing webhook_secret"	ไม่ได้บันทึกรหัสลับสำหรับการลงชื่อ (Signing secret)	คลิก Create webhook หรือวางความลับ whsec_... จากแดชบอร์ด Stripe และ Save
หักเงินแล้วแต่ยอดเงินในบัญชีไม่เปลี่ยนแปลง	เว็บฮุกไม่ถูกส่งหรือลายเซ็นล้มเหลว	ตรวจสอบว่า URL ลงท้ายด้วย /v1/billing/stripe/webhook, รหัสลับตรงกับปลายทาง และเล่นเหตุการณ์ซ้ำใน Gateway events ใน Stripe ให้เปิดปลายทางและดูความพยายามในการส่ง (HTTP 400 หมายถึงรหัสลับการลงชื่อไม่ถูกต้อง)
"Create webhook" fails	URL ไม่ใช่ HTTPS หรือไม่สามารถเข้าถึงได้	ใช้โดเมนสาธารณะ https:// ของคุณ
สถานะ Apple Pay ไม่ใช้งาน	Domain not validated	คลิก Register / verify domain อีกครั้งหลังจากไฟล์เชื่อมโยงโดเมนตอบกลับสถานะ 200
Alipay ไม่พร้อมใช้งานในกล่องโต้ตอบ Check	Not activated at Stripe	เปิดใช้งานในแดชบอร์ด Stripe จากนั้นคลิก Check
ลูกค้าไม่เห็นฟอร์มบัตร	Card (Stripe) ปิดอยู่หรือไม่มีคีย์ลับ	เปิดใช้งานใน Fees & limits และบันทึกคีย์