อธิบายคีย์ API ของ Stripe: Test กับ Live, Publishable กับ Secret และ Restricted Keys

ทุกการเชื่อมต่อกับ Stripe เริ่มต้นด้วยคำถามเดียวกัน: คีย์ไหนไปไว้ที่ไหน? Stripe มอบ publishable key, secret key และตัวเลือกในการสร้าง restricted key โดยแต่ละแบบมีทั้งเวอร์ชัน test และ live ถ้าคุณใส่คีย์ผิดตัวผิดที่ คุณอาจรั่วความสามารถในการเคลื่อนย้ายเงินหรือเสียเวลาทั้งบ่ายไปกับ error 401 คู่มือนี้จะอธิบายว่า Stripe API key แต่ละแบบทำอะไรได้บ้าง อยู่ที่ไหน วิธีส่งคำขอโหมด test ครั้งแรก และวิธีเก็บ live key ไว้ห่างจากสิ่งที่แชร์ออกไป สำหรับแนวคิดทั่วไปก่อนอื่น เริ่มจาก what an API key is ทุกอย่างด้านล่างนี้อ้างอิงตาม เอกสาร API keys ของ Stripe ตรวจสอบเมื่อเดือนกันยายน 2026

Stripe API key ของคุณอยู่ที่ไหนใน Dashboard

เปิดหน้า API keys ที่ dashboard.stripe.com/apikeys หน้านี้อยู่ภายใต้ Developers ใน Dashboard และแสดงคีย์ของบัญชีหรือ sandbox ที่คุณกำลังดูอยู่ สวิตช์หนึ่งตัวใช้สลับระหว่างโหมด sandbox และโหมด live โดยรายการคีย์จะเปลี่ยนตามโหมด

หน้านี้มีสองรายการ:

• Standard keys เก็บ publishable key และ secret key ของคุณ
• Restricted keys เก็บคีย์ใด ๆ ที่คุณสร้างขึ้นพร้อมสิทธิ์แบบจำกัดขอบเขต

การมองเห็นข้อมูลแตกต่างกันตามโหมด ใน sandbox คุณสามารถเปิดเผยคีย์ทุกตัวได้ทุกเมื่อ ในโหมด live secret key ที่คุณสร้างเองจะแสดงเพียงครั้งเดียว ณ ตอนสร้าง คัดลอกลงใน vault ของคุณก่อนปิดกล่องโต้ตอบ ถ้าทำหายก็ต้องหมุนคีย์ใหม่ เฉพาะคีย์เริ่มต้นที่ Stripe สร้างให้เท่านั้นที่สามารถเปิดเผยอีกครั้งได้ในโหมด live

สิ่งหนึ่งที่หน้านี้ไม่แสดง: webhook signing secrets สิ่งเหล่านั้นอยู่ภายใต้ Webhooks แยกตามแต่ละ endpoint และไม่ใช่ API key เลย

Publishable กับ secret key

ชื่อของมันบ่งบอกถึงขอบเขตความเชื่อถือ

Publishable key ควรอยู่ในเบราว์เซอร์หรือแอปบนมือถือ มันแปลงหมายเลขบัตรเป็น token และแทบไม่มีอะไรนอกเหนือจากนั้น มันไม่สามารถสร้าง charge หรืออ่านข้อมูลบัญชีได้ ดังนั้นการส่งมันไปในโค้ดฝั่ง front-end จึงเป็นเรื่องที่คาดหมายได้

Secret key ควรอยู่บนเซิร์ฟเวอร์ของคุณเท่านั้น คำแนะนำของ Stripe ได้เปลี่ยนแปลงไป: เอกสารตอนนี้ระบุว่าพวกเขา "ไม่แนะนำให้ใช้ secret key สำหรับกรณีการใช้งานใหม่" และชี้ให้ใช้ restricted key แทน secret key แบบไม่จำกัดสิทธิ์ยังใช้งานได้ แต่ให้มองว่ามันเป็นทางเลือกฉุกเฉิน ไม่ใช่ค่าเริ่มต้น

คีย์โหมด test กับ live

Stripe ทำงานแยกเป็นสองโลก โดยแต่ละโลกมีชุดคีย์ของตัวเอง Test keys (เอกสารใหม่เรียกฝั่ง test ว่า sandbox แม้ว่าคำนำหน้ายังคงเป็น _test_) จะคืนค่าอ็อบเจ็กต์จำลอง: ลูกค้าปลอม PaymentIntents ปลอม บัตรทดสอบที่สำเร็จหรือถูกปฏิเสธได้ตามสั่ง ไม่มีเงินจริง ส่วน live keys จะเชื่อมต่อกับเครือข่ายบัตรและเคลื่อนย้ายเงินจริง

การแยกกันนั้นเข้มงวด ลูกค้าที่สร้างด้วย sk_test_ จะไม่มีอยู่จริงในมุมมองของ sk_live_ และกลับกัน รหัสข้อผิดพลาดของ Stripe สำหรับการข้ามโหมดกันคือ livemode_mismatch ซึ่งบอกตรง ๆ ว่า "Test and live mode API keys, requests, and objects are only available within the corresponding mode."

มีกฎในทางปฏิบัติสองข้อตามมา:

• พัฒนาและทดสอบกับ sk_test_ หรือ rk_test_ ทั้งหมด Stripe แนะนำให้ใช้ sandbox ทั่วไปแยกต่างหากสำหรับการเชื่อมต่อใหม่ เพื่อให้การตั้งค่าและข้อมูลของมันแยกออกจากกัน
• การเปลี่ยนไปใช้ live เป็นการเปลี่ยนการตั้งค่า ไม่ใช่เปลี่ยนโค้ด เซิร์ฟเวอร์ของคุณอ่านคีย์จาก environment variable หรือ vault และการไป live หมายถึงการเปลี่ยนค่านั้น

ทุกการตอบกลับจาก API จะมีค่าบูลีน livemode จงตรวจสอบมันในเทสต์ของคุณ นี่คือเกราะป้องกันที่ถูกที่สุดต่อการ deploy ด้วยคีย์ผิด

Restricted keys และหลักการสิทธิ์น้อยที่สุด

Restricted API key (Stripe ย่อว่า RAK) คือ secret key ที่มีหน้ากากสิทธิ์ เมื่อคุณสร้างมันขึ้นมา คุณเลือกสิทธิ์สำหรับแต่ละกลุ่มทรัพยากร: None, Read หรือ Write ทุกอย่างมีค่าเริ่มต้นเป็น None โดย Write ครอบคลุม Read และการจับคู่กับ HTTP นั้นง่าย: GET ต้องใช้ Read ส่วน POST และ DELETE ต้องใช้ Write

หากต้องการสร้าง ให้คลิก Create restricted key บนหน้า API keys เลือกชุดสิทธิ์ที่ตั้งค่าไว้ล่วงหน้าหรือเริ่มจากศูนย์ ตั้งชื่อ กำหนดสิทธิ์ และทำตามขั้นตอนยืนยันตัวตนแบบสองปัจจัยให้เสร็จ เหมือนกับ secret key ที่สร้างเองในโหมด live คุณจะเห็นค่าของมันเพียงครั้งเดียว

คู่มือ restricted keys แนะนำให้ใช้หนึ่งคีย์ต่อหนึ่งบริการ: บริการเรียกเก็บเงินได้ Write บน Invoices และ Customers งานรายงานได้ Read บน Charges และ Disputes ถ้าบริการใดถูกเจาะระบบ ผู้โจมตีจะติดอยู่ในสิทธิ์ของคีย์นั้น คีย์ disputes แบบอ่านอย่างเดียวไม่สามารถสร้าง charge หรือแตะต้อง payout ได้

ให้สิทธิ์กว้าง ๆ กับคีย์ใหม่ใน sandbox รันชุดเทสต์ของคุณ จากนั้นเปิด request logs ของคีย์นั้น (เมนู overflow, View request logs) แล้วตัดสิทธิ์ทุกอย่างที่ไม่มีการใช้งานออกไป Stripe ยังให้คุณติดแท็กคีย์ที่ตั้งใจไว้สำหรับ AI agent อัตโนมัติ เพื่อให้อยู่ภายใต้กฎการอนุมัติสำหรับ payouts และ refunds ใช้เส้นทางนั้นแทนการใช้ secret key ธรรมดา

คำขอแรกของคุณด้วย curl และ Python

Stripe ยืนยันตัวตนด้วย HTTP Basic Auth: คีย์คือ username และ password จะเว้นว่างไว้ เครื่องหมายทวิภาค (colon) ที่ต่อท้ายบอก curl ว่าจะไม่ถามรหัสผ่าน:

export STRIPE_API_KEY=sk_test_...   # your sandbox secret key

curl https://api.stripe.com/v1/payment_intents \
  -u "$STRIPE_API_KEY:" \
  -d amount=2000 \
  -d currency=usd \
  -d "automatic_payment_methods[enabled]=true"

ผลลัพธ์ที่ได้คือ PaymentIntent ที่มี id เริ่มต้นด้วย pi_, status: "requires_payment_method" และ livemode: false ฟิลด์สุดท้ายยืนยันว่าคุณใช้คีย์ทดสอบ

Stripe ยังรับรูปแบบ -H "Authorization: Bearer $STRIPE_API_KEY" ซึ่งเป็นรูปแบบที่ Apidog และ HTTP client ส่วนใหญ่ใช้ ทั้งสองแบบพาคีย์เดียวกันไป ถ้าคุณไม่แน่ใจว่าแบบไหนเข้ากับ stack ของคุณ การเปรียบเทียบ API keys กับ bearer tokens ของเราครอบคลุมข้อดีข้อเสียไว้แล้ว คำขอต้องส่งผ่าน HTTPS ส่วน HTTP ธรรมดาจะล้มเหลวทันที ตาม เอกสารอ้างอิงการยืนยันตัวตน

ใน Python รูปแบบ SDK ปัจจุบันคือ StripeClient ที่อ่านคีย์จาก environment:

import os
import stripe

client = stripe.StripeClient(os.environ["STRIPE_API_KEY"])

intent = client.v1.payment_intents.create({
    "amount": 2000,
    "currency": "usd",
    "automatic_payment_methods": {"enabled": True},
})
print(intent.id, intent.livemode)  # pi_..., False

ไม่มีสตริงคีย์ปรากฏอยู่ในไฟล์ โค้ดเดียวกันนี้รันกับ test หรือ live ได้ ขึ้นอยู่กับว่าสภาพแวดล้อมให้อะไรมา

ให้ coding agent ของคุณทดสอบ Stripe key ด้วย Apidog CLI

Curl พิสูจน์ได้แค่ว่าคีย์ใช้งานได้ครั้งเดียว coding agent ของคุณสามารถเปลี่ยนมันให้เป็นการตรวจสอบที่รันซ้ำได้ผ่าน Apidog CLI และเก็บคีย์ออกจากโปรเจกต์ที่แชร์กัน ตั้งค่าครั้งเดียว (token อยู่ภายใต้ Account Settings, API Access Token):

npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
npx -y skills add https://apidog.com   # pick your agent when prompted

จากนั้นให้พรอมป์ต์กับ agent หนึ่งครั้ง:

Use Apidog CLI on project <id>. Create a "Stripe Test" environment with base URL
https://api.stripe.com. Add POST /v1/payment_intents with Bearer auth from
{{stripe_secret_key}} and a form-urlencoded body: amount=2000, currency=usd.
Create a test case asserting status 200, an id starting with pi_ and
livemode false, then run it and summarize any failures.

คำสั่งที่มันรัน ตรวจสอบกับ Apidog CLI 2.2.7:

apidog environment create "Stripe Test" --project <id> --base-url https://api.stripe.com
apidog cli-schema get endpoint-create
apidog endpoint create --project <id> --file payment-intents.json
apidog cli-schema validate test-case-create --file pi-case.json
apidog test-case create --project <id> --file pi-case.json
apidog run --test-case <caseId> --project <id> -e <envId> \
  --env-var "stripe_secret_key=$STRIPE_API_KEY" -r cli,json

พรอมป์ต์ระบุการเข้ารหัสแบบ form เพราะ endpoint v1 ของ Stripe ไม่รับ JSON การตรวจสอบ livemode คือกับดักของคุณ: ถ้ามีใครรันเคสนี้ด้วย live key มันจะล้มเหลวก่อนที่คำขอที่สองจะถูกส่งออกไป ใน CI บรรทัด apidog run เดียวกันนี้จะอ่านคีย์จากที่เก็บความลับของ pipeline ของคุณ คู่มือ Apidog CLI CI/CD pipeline ของเรามีเวอร์ชันที่คัดลอกวางได้เลย นิยามคำขอถูกแชร์ แต่ข้อมูลรับรองแบบ live ไม่เคยถูกแชร์

การหมุนคีย์และสิ่งที่ต้องทำถ้าคีย์รั่ว

คู่มือการจัดการคีย์ของ Stripe เองนั้นตรงไปตรงมา: ให้สันนิษฐานว่าทุกสิ่งที่ commit ลง repo วางไว้ในแชท หรือพิมพ์ออกมาใน log นั้นรั่วไหลแล้ว แม้ว่าคุณจะไม่แน่ใจว่ามีใครเห็นมันหรือไม่

การหมุนคีย์มีมาให้ในตัวใน Dashboard จากเมนู overflow ของคีย์ เลือก Rotate key ตั้งวันหมดอายุของคีย์เก่า และคัดลอกคีย์ใหม่ ทั้งสองใช้งานได้ในช่วงผ่อนผัน นานสุดถึง 7 วัน ดังนั้นคุณสามารถทยอยเปลี่ยนได้และเฝ้าดู request logs เพื่อหาส่วนที่ยังค้างอยู่ Now จะเพิกถอนคีย์เก่าทันที

ถ้า secret หรือ restricted key รั่ว:

• หมุนคีย์ทันทีด้วยวันหมดอายุที่สั้น
• อัปเดตทุกเซิร์ฟเวอร์ที่ใช้คีย์นั้น ยืนยันการรับส่งข้อมูลใน request logs แล้วปล่อยให้คีย์เก่าหมดอายุ
• ตรวจสอบกิจกรรมล่าสุดใน Workbench เพื่อหาสิ่งที่การเชื่อมต่อของคุณไม่น่าจะทำ: connected accounts ที่ไม่รู้จัก, payouts ที่คุณไม่ได้ริเริ่ม, บัญชีธนาคารใหม่
• หยุด payouts ที่น่าสงสัย ช่วยย้อนกลับรายการที่ส่งไปแล้ว และคืนเงิน charges ที่เป็นการฉ้อโกงอย่างรวดเร็วเพื่อตัดปัญหาข้อโต้แย้ง
• หมุนคีย์อื่น ๆ ของคุณด้วย ถ้าคีย์หนึ่งรั่ว ให้สันนิษฐานว่าช่องทางที่ทำให้มันรั่วนั้นเห็นข้อมูลอื่น ๆ ไปด้วย

Stripe สแกนหาคีย์ที่ถูกเปิดเผยและจะแจ้งเตือนคุณ บางครั้งก็ปิดใช้งานคีย์นั้นไปก่อน แต่การตรวจจับไม่ได้รับประกัน การค้นหาใน repo และ CI config ของคุณหา sk_live_ และ rk_live_ เป็นการตรวจสอบที่ใช้เวลาแค่ห้านาที และ secret scanner ใน pre-commit hook จะหยุดการรั่วครั้งถัดไป Stripe ไม่เคยขอ secret key ของคุณ ดังนั้นข้อความใดที่ร้องขอสิ่งนั้นคือการฟิชชิ่ง

ข้อผิดพลาด Stripe API key ที่พบบ่อย

กรณี 401 และ 403 จับคู่กับ stripe.AuthenticationError และ stripe.PermissionError ใน Python SDK ตาม เอกสารอ้างอิงข้อผิดพลาด ดังนั้นคุณสามารถดักจับมันได้โดยเฉพาะ อีกกรณีที่ชัดเจนน้อยกว่า: live key ที่ไม่ได้สร้าง transfers หรือ payouts มาเป็นเวลา 180 วันจะถูกจำกัดการกระทำเหล่านั้น โดยมีตัวเลือก Restore access บนคีย์นั้น

คำถามที่พบบ่อย

การวาง Stripe publishable key ในโค้ด frontend ปลอดภัยหรือไม่?

ปลอดภัย คีย์ pk_ ใช้แปลงรายละเอียดบัตรเป็น token แต่ไม่สามารถสร้าง charge อ่านข้อมูลลูกค้า หรือเคลื่อนย้ายเงินได้ มีแค่ secret และ restricted key เท่านั้นที่ต้องอยู่ฝั่งเซิร์ฟเวอร์

ใช้ restricted key ในโหมด test ได้ไหม?

ได้ Restricted keys มีอยู่ทั้งสองโหมด (rk_test_ และ rk_live_) Stripe แนะนำให้ปรับจูนเวอร์ชัน test ก่อน จากนั้นจึงสร้าง live key ที่มีสิทธิ์ตรงกัน

webhook signing secret เหมือนกับ API key ของฉันไหม?

ไม่ Signing secrets ออกให้แยกตามแต่ละ webhook endpoint และใช้เพียงยืนยันว่าเหตุการณ์ที่เข้ามานั้นมาจาก Stripe มันอยู่ภายใต้ Webhooks ไม่ใช่หน้า API keys ถ้าคุณกำลังตั้งค่าสิ่งเหล่านี้ ดูวิธีทดสอบ Stripe webhooks ใน CI

จะเกิดอะไรขึ้นถ้าฉันใช้ test key ในโปรดักชัน?

คำขอจะสำเร็จแต่ไม่มีการเรียกเก็บเงินจากบัตรและไม่มีเงินเคลื่อนย้าย เนื่องจาก livemode จะคืนค่าเป็น false บนทุกอ็อบเจ็กต์ การตรวจสอบฟิลด์นั้นจะจับความผิดพลาดได้ก่อนที่ลูกค้าจะเจอ

สรุปสั้น ๆ

Publishable keys อยู่ในฝั่ง client, secret และ restricted keys อยู่บนเซิร์ฟเวอร์, test และ live ไม่ผสมกัน และ restricted ดีกว่า secret ทุกครั้งที่คุณจำกัดขอบเขตได้ เก็บ live key ไว้ใน vault ส่ง test key ให้ Apidog CLI ตอนรัน และเก็บการตรวจสอบ livemode ไว้ในทุกเทสต์เคสที่ agent ของคุณเขียน