เวอร์ชัน: ล่าสุด

Sources API

ภาพรวม

Sources API ช่วยให้คุณสามารถรับชำระเงินด้วยวิธีการชำระเงินทางเลือกนอกเหนือจากบัตรเครดิต Source แสดงถึงช่องทางการชำระเงิน เช่น PromptPay QR codes, โมบายแบงก์กิ้ง, อินเทอร์เน็ตแบงก์กิ้ง, แผนผ่อนชำระ และอื่นๆ

Source คืออะไร

Source คือออบเจ็กต์วิธีการชำระเงินที่แสดงถึง:

PromptPay QR codes - การชำระเงินแบบ QR แบบเรียลไทม์
โมบายแบงก์กิ้ง - การเปลี่ยนเส้นทางการชำระเงินในแอป (SCB Easy, Krungthai Next ฯลฯ)
อินเทอร์เน็ตแบงก์กิ้ง - การโอนเงินผ่านธนาคารออนไลน์
ร้านสะดวกซื้อ - การชำระด้วยเงินสดที่ 7-Eleven, ฟามิลี่มาร์ท ฯลฯ
แผนผ่อนชำระ - ตัวเลือกการชำระแบบผ่อนชำระ
อีวอลเล็ต - TrueMoney, Rabbit LINE Pay ฯลฯ

ฟีเจอร์หลัก

รองรับวิธีการชำระเงินที่หลากหลาย

การชำระด้วย QR - PromptPay, Alipay, WeChat Pay
การโอนเงินผ่านธนาคาร - โมบายแบงก์กิ้งและอินเทอร์เน็ตแบงก์กิ้ง
การผ่อนชำระ - แผนผ่อนชำระดอกเบี้ย 0%
การชำระด้วยเงินสด - การชำระเงินที่ร้านสะดวกซื้อ
อีวอลเล็ต - การบูรณาการกับกระเป๋าเงินดิจิทัล

เวิร์กโฟลว์ที่ยืดหยุ่น

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

การรองรับตามภูมิภาค

ไทย - PromptPay, SCB, Krungthai, BAY, BBL ฯลฯ
มาเลเซีย - FPX, Boost, GrabPay, Touch 'n Go
สิงคโปร์ - PayNow, GrabPay
ระดับนานาชาติ - Alipay, WeChat Pay

Source ทำงานอย่างไร

ฟลาวมาตรฐาน

┌─────────┐         ┌─────────┐         ┌─────────┐         ┌─────────┐
│ Your    │         │ Omise   │         │ Payment │         │ Customer│
│ Server  │         │ API     │         │ Provider│         │         │
└────┬────┘         └────┬────┘         └────┬────┘         └────┬────┘
     │                   │                   │                   │
     │ 1. Create source  │                   │                   │
     ├──────────────────>│                   │                   │
     │                   │                   │                   │
     │ 2. Return source  │                   │                   │
     │    (with QR/URL)  │                   │                   │
     │<──────────────────┤                   │                   │
     │                   │                   │                   │
     │ 3. Create charge  │                   │                   │
     ├──────────────────>│                   │                   │
     │                   │                   │                   │
     │ 4. Return charge  │                   │                   │
     │    (status:pending)                   │                   │
     │<──────────────────┤                   │                   │
     │                   │                   │                   │
     │ 5. Display QR     │                   │                   │
     │    or redirect    │                   │                   │
     ├──────────────────────────────────────────────────────────>│
     │                   │                   │                   │
     │                   │                   │ 6. Customer pays  │
     │                   │                   │<──────────────────┤
     │                   │                   │                   │
     │                   │ 7. Webhook notify │                   │
     │<──────────────────┤                   │                   │
     │                   │                   │                   │
     │ 8. Show success   │                   │                   │
     ├──────────────────────────────────────────────────────────>│
     │                   │                   │                   │

ขั้นตอนการใช้งาน

สร้าง Source - ระบุประเภทวิธีการชำระเงินและจำนวนเงิน
สร้าง Charge - ใช้ Source ID เพื่อสร้าง Charge (สถานะ: pending)
แสดง UI การชำระเงิน - แสดง QR code หรือเปลี่ยนเส้นทางลูกค้า
รอ Webhook - ลูกค้าทำการชำระเงินแบบอะซิงโครนัส
ตรวจสอบสถานะ - ตรวจสอบสถานะ Charge ผ่าน Webhook หรือ API
ดำเนินการคำสั่งซื้อ - ประมวลผลคำสั่งซื้อหลังจากชำระเงินสำเร็จ

ประเภทของ Source

การชำระเงินแบบ QR

Type	Description	Region
promptpay	การชำระเงินด้วย QR แห่งชาติของไทย	Thailand
alipay	อีวอลเล็ตชั้นนำของจีน	International
wechat_pay	WeChat Pay QR	International
paynow	การชำระเงินด้วย QR ของสิงคโปร์	Singapore

โมบายแบงก์กิ้ง

Type	Description	Region
mobile_banking_scb	แอป SCB Easy	Thailand
mobile_banking_kbank	แอป K PLUS	Thailand
mobile_banking_bbl	Bangkok Bank Mobile	Thailand
mobile_banking_bay	Krungsri Mobile	Thailand
mobile_banking_ktb	แอป Krungthai NEXT	Thailand

อินเทอร์เน็ตแบงก์กิ้ง

Type	Description	Region
internet_banking_scb	SCB ออนไลน์แบงก์กิ้ง	Thailand
internet_banking_bbl	Bangkok Bank ออนไลน์	Thailand
internet_banking_bay	Krungsri ออนไลน์	Thailand
fpx	ออนไลน์แบงก์กิ้งของมาเลเซีย	Malaysia

วิธีการชำระเงินอื่นๆ

Type	Description	Region
truemoney	TrueMoney Wallet	Thailand
rabbit_linepay	Rabbit LINE Pay	Thailand
installment_bay	การผ่อนชำระของ Krungsri	Thailand
installment_kbank	การผ่อนชำระของ Kasikornbank	Thailand
econtext	การชำระเงินที่ร้านสะดวกซื้อ	Japan

วงจรชีวิตของ Source

สถานะ

State	Description	Charge Status
pending	สร้าง Source แล้ว รอการชำระเงิน	pending
successful	ชำระเงินเสร็จสิ้น	successful
failed	การชำระเงินล้มเหลวหรือถูกปฏิเสธ	failed
expired	หมดเวลาการชำระเงิน	expired

กฎการหมดอายุ

วิธีการชำระเงินที่แตกต่างกันมีเวลาหมดอายุเริ่มต้นที่แตกต่างกัน:

การตรวจสอบเวลาหมดอายุ

เวลาหมดอายุที่ระบุด้านล่างขึ้นอยู่กับเอกสารที่มีอยู่และอาจมีการเปลี่ยนแปลง สำหรับเวลาหมดอายุที่แม่นยำและเป็นปัจจุบันที่สุดสำหรับวิธีการชำระเงินเฉพาะของคุณ โปรดดูเอกสารวิธีการชำระเงินแต่ละรายการ หรือติดต่อฝ่ายสนับสนุน Omise

Payment Method	Default Expiration	Custom Expiration
PromptPay	24 ชั่วโมง	ปรับแต่งได้ผ่าน `expires_in`
Mobile Banking (SCB/KBANK/BBL/BAY/KTB)	15-30 นาที*	ปรับแต่งได้ผ่าน `expires_in`
Internet Banking (SCB/BBL/BAY)	15-30 นาที*	ปรับแต่งได้ผ่าน `expires_in`
FPX (Malaysia)	30 นาที*	ปรับแต่งได้ผ่าน `expires_in`
PayNow (Singapore)	15-30 นาที*	ปรับแต่งได้ผ่าน `expires_in`
Alipay	15-30 นาที*	ปรับแต่งได้ผ่าน `expires_in`
WeChat Pay	15-30 นาที*	ปรับแต่งได้ผ่าน `expires_in`
TrueMoney Wallet	15-30 นาที*	ปรับแต่งได้ผ่าน `expires_in`
Rabbit LINE Pay	15-30 นาที*	ปรับแต่งได้ผ่าน `expires_in`
GrabPay	15-30 นาที*	ปรับแต่งได้ผ่าน `expires_in`
Boost	15-30 นาที*	ปรับแต่งได้ผ่าน `expires_in`
Touch 'n Go	15-30 นาที*	ปรับแต่งได้ผ่าน `expires_in`
Installment Plans (BAY/KBANK)	24-48 ชั่วโมง*	ปรับแต่งได้ผ่าน `expires_in`
Convenience Stores (Japan)	7 วัน*	ปรับแต่งได้ผ่าน `expires_in`

*ตรวจสอบกับเอกสารวิธีการชำระเงินเฉพาะหรือฝ่ายสนับสนุน Omise สำหรับค่าที่แน่นอน

การตั้งค่าการหมดอายุแบบกำหนดเอง:

const source = await omise.sources.create({
  type: 'promptpay',
  amount: 100000,
  currency: 'thb',
  expires_in: 1800  // 30 minutes (in seconds)
});

แนวทางปฏิบัติที่ดีที่สุด:

ตรวจสอบเอกสารวิธีการชำระเงินแต่ละรายการสำหรับเวลาหมดอายุที่แนะนำ
ตั้งเวลาหมดอายุสั้นกว่า (5-15 นาที) สำหรับการชำระด้วย QR เพื่อป้องกัน QR code ที่ล้าสมัย
ตั้งเวลาหมดอายุนานกว่า (24-48 ชั่วโมง) สำหรับการโอนเงินผ่านธนาคารเพื่อให้มีเวลาประมวลผล
จัดการกับเหตุการณ์ webhook source.expired เสมอเพื่ออัปเดตสถานะคำสั่งซื้อ

API Endpoints

Method	Endpoint	Description
POST	`/sources`	สร้าง Source ใหม่
GET	`/sources/:id`	เรียกข้อมูล Source

เริ่มต้นอย่างรวดเร็ว

ตัวอย่างการชำระเงินด้วย PromptPay QR

// 1. สร้าง PromptPay source
const source = await omise.sources.create({
  type: 'promptpay',
  amount: 100000,
  currency: 'thb'
});

// 2. สร้าง charge ด้วย source
const charge = await omise.charges.create({
  amount: 100000,
  currency: 'thb',
  source: source.id,
  return_uri: 'https://example.com/payment/complete'
});

// 3. แสดง QR code ให้ลูกค้า
const qrCodeUrl = charge.source.scannable_code.image.download_uri;
console.log('Show QR code:', qrCodeUrl);

// 4. รอการแจ้งเตือนผ่าน webhook
// เหตุการณ์ Webhook: charge.complete
// ตรวจสอบสถานะ charge เปลี่ยนเป็น "successful"

ตัวอย่างโมบายแบงก์กิ้ง

// 1. สร้าง mobile banking source
const source = await omise.sources.create({
  type: 'mobile_banking_scb',
  amount: 50000,
  currency: 'thb'
});

// 2. สร้าง charge
const charge = await omise.charges.create({
  amount: 50000,
  currency: 'thb',
  source: source.id,
  return_uri: 'https://example.com/payment/complete'
});

// 3. เปลี่ยนเส้นทางลูกค้าไปที่ authorize_uri
const redirectUrl = charge.authorize_uri;
// เปลี่ยนเส้นทางลูกค้าไปที่ URL นี้
window.location.href = redirectUrl;

// 4. ลูกค้าทำการชำระเงินในแอปธนาคาร
// 5. ลูกค้าถูกเปลี่ยนเส้นทางกลับไปที่ return_uri
// 6. ส่ง Webhook เมื่อการชำระเงินเสร็จสิ้น

ฟลาวการชำระเงิน

ฟลาว QR Code (PromptPay, Alipay, WeChat Pay)

สร้าง source → สร้าง charge
แสดง QR code ให้ลูกค้า
ลูกค้าสแกนด้วยแอปมือถือ
ลูกค้ายืนยันการชำระเงินในแอป
ส่งการแจ้งเตือนผ่าน Webhook
อัปเดตสถานะคำสั่งซื้อ

ฟลาวเปลี่ยนเส้นทาง (โมบายแบงก์กิ้ง, อินเทอร์เน็ตแบงก์กิ้ง)

สร้าง source → สร้าง charge
เปลี่ยนเส้นทางลูกค้าไปที่ authorize_uri
ลูกค้าทำการชำระเงินให้เสร็จสิ้น
ลูกค้าถูกเปลี่ยนเส้นทางไปที่ return_uri
ส่งการแจ้งเตือนผ่าน Webhook
ตรวจสอบสถานะการชำระเงิน

ฟลาวออฟไลน์ (ร้านสะดวกซื้อ)

สร้าง source → สร้าง charge
แสดงรหัสการชำระเงินให้ลูกค้า
ลูกค้าจ่ายเงินที่ร้านสะดวกซื้อ
ส่งการแจ้งเตือนผ่าน Webhook (หลายชั่วโมง/หลายวันต่อมา)
ดำเนินการคำสั่งซื้อ

กรณีการใช้งานทั่วไป

การชำระเงินครั้งเดียว

const source = await omise.sources.create({ type: 'promptpay', amount: 100000, currency: 'thb' });
const charge = await omise.charges.create({ amount: 100000, currency: 'thb', source: source.id });

การชำระแบบผ่อนชำระ

const source = await omise.sources.create({
  type: 'installment_kbank',
  amount: 300000,
  currency: 'thb',
  installment_term: 6  // 6 เดือน
});
const charge = await omise.charges.create({ amount: 300000, currency: 'thb', source: source.id });

การชำระเงินที่ร้านสะดวกซื้อ

const source = await omise.sources.create({
  type: 'econtext',
  amount: 50000,
  currency: 'jpy',
  name: 'TARO YAMADA',
  email: 'taro@example.com',
  phone_number: '+81312345678'
});
const charge = await omise.charges.create({ amount: 50000, currency: 'jpy', source: source.id });

แนวทางปฏิบัติที่ดีที่สุด

✅ ควรทำ

ตั้งค่า return_uri สำหรับการชำระเงินแบบเปลี่ยนเส้นทาง
ใช้งาน webhooks สำหรับการแจ้งเตือนแบบอะซิงโครนัส
แสดงคำแนะนำที่ชัดเจน สำหรับวิธีการชำระเงินแต่ละประเภท
ตั้งค่าการหมดอายุที่เหมาะสม ตามประเภทการชำระเงิน
ตรวจสอบสถานะการชำระเงิน ผ่าน webhooks ไม่ใช่การ polling
จัดการกับ timeout อย่างเหมาะสม (กรณีที่ลูกค้าไม่ได้ทำให้เสร็จ)
ทดสอบวิธีการชำระเงินแต่ละประเภท ก่อนเปิดใช้งานจริง
เก็บ Source ID สำหรับการติดตามและการสนับสนุน

❌ ไม่ควรทำ

อย่า poll บ่อยๆ (ใช้ webhooks)
อย่าสมมติว่าการชำระเงินเกิดขึ้นทันที (เป็นแบบอะซิงโครนัส)
อย่าข้าม return_uri (ลูกค้าต้องกลับมา)
อย่าเพิกเฉยต่อการหมดอายุ (Sources จะหมดอายุ)
อย่าใช้วิธีการชำระเงินปะปน (1 source = 1 ประเภทการชำระเงิน)
อย่าใช้ sources กับสกุลเงินที่ผิด (เฉพาะตามประเภท)

ข้อควรพิจารณาด้านความปลอดภัย

การตรวจสอบ Webhook

ตรวจสอบลายเซ็น webhook เสมอเพื่อให้แน่ใจว่าเป็นของแท้:

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  hmac.update(payload);
  const expectedSignature = hmac.digest('hex');
  return signature === expectedSignature;
}

การตรวจสอบสถานะ

อย่าเชื่อถือพารามิเตอร์ return_uri เพียงอย่างเดียว ตรวจสอบสถานะ charge เสมอ:

// ลูกค้ากลับมาจากการชำระเงิน
app.get('/payment/complete', async (req, res) => {
  const chargeId = req.query.charge_id;

  // ตรวจสอบสถานะ charge จริง
  const charge = await omise.charges.retrieve(chargeId);

  if (charge.status === 'successful') {
    // ยืนยันการชำระเงินแล้ว ดำเนินการคำสั่งซื้อ
  } else {
    // การชำระเงินยังไม่เสร็จสิ้น แสดงข้อผิดพลาด
  }
});

การทดสอบ

โหมดทดสอบ

ประเภท Source ทั้งหมดทำงานในโหมดทดสอบด้วย test secret key ของคุณ

การจำลองการชำระเงิน

ในโหมดทดสอบ คุณสามารถ:

สร้าง sources และ charges
รับ webhooks
ทดสอบฟลาวการเปลี่ยนเส้นทาง
สร้าง QR codes สำหรับทดสอบ

ทดสอบ Webhooks

ใช้เครื่องมือทดสอบ webhook หรือ ngrok สำหรับการพัฒนาในเครื่อง:

ngrok http 3000
# ตั้งค่า webhook URL ใน Omise Dashboard

การจัดการข้อผิดพลาด

ข้อผิดพลาด Source ทั่วไป:

Error Code	Description	Solution
`invalid_source_type`	วิธีการชำระเงินไม่รองรับ	ตรวจสอบประเภทที่ใช้ได้สำหรับสกุลเงินของคุณ
`amount_too_low`	จำนวนเงินต่ำกว่าขั้นต่ำ	ตรวจสอบจำนวนเงินขั้นต่ำสำหรับประเภทการชำระเงิน
`currency_not_supported`	สกุลเงินไม่ถูกต้อง	ตรวจสอบประเภทการชำระเงินรองรับสกุลเงิน
`expired_source`	Source หมดอายุ	สร้าง Source ใหม่

เอกสารอ้างอิง API

สร้าง Source - POST /sources
เรียกข้อมูล Source - GET /sources/:id

ทรัพยากรที่เกี่ยวข้อง

คู่มือวิธีการชำระเงิน

ต้องการความช่วยเหลือ? ตรวจสอบ คู่มือวิธีการชำระเงิน ของเรา หรือติดต่อ support@omise.co

ภาพรวม​

Source คืออะไร​

ฟีเจอร์หลัก​

รองรับวิธีการชำระเงินที่หลากหลาย​

เวิร์กโฟลว์ที่ยืดหยุ่น​

การรองรับตามภูมิภาค​

Source ทำงานอย่างไร​

ฟลาวมาตรฐาน​

ขั้นตอนการใช้งาน​

ประเภทของ Source​

การชำระเงินแบบ QR​

โมบายแบงก์กิ้ง​

อินเทอร์เน็ตแบงก์กิ้ง​

วิธีการชำระเงินอื่นๆ​

วงจรชีวิตของ Source​

สถานะ​

กฎการหมดอายุ​

API Endpoints​

เริ่มต้นอย่างรวดเร็ว​

ตัวอย่างการชำระเงินด้วย PromptPay QR​

ตัวอย่างโมบายแบงก์กิ้ง​

ฟลาวการชำระเงิน​

ฟลาว QR Code (PromptPay, Alipay, WeChat Pay)​

ฟลาวเปลี่ยนเส้นทาง (โมบายแบงก์กิ้ง, อินเทอร์เน็ตแบงก์กิ้ง)​

ฟลาวออฟไลน์ (ร้านสะดวกซื้อ)​

กรณีการใช้งานทั่วไป​

การชำระเงินครั้งเดียว​

การชำระแบบผ่อนชำระ​

การชำระเงินที่ร้านสะดวกซื้อ​

แนวทางปฏิบัติที่ดีที่สุด​

✅ ควรทำ​

❌ ไม่ควรทำ​

ข้อควรพิจารณาด้านความปลอดภัย​

การตรวจสอบ Webhook​

การตรวจสอบสถานะ​

การทดสอบ​

โหมดทดสอบ​

การจำลองการชำระเงิน​

ทดสอบ Webhooks​

การจัดการข้อผิดพลาด​

เอกสารอ้างอิง API​

ทรัพยากรที่เกี่ยวข้อง​

คู่มือวิธีการชำระเงิน​