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

Customers API

ภาพรวม

Customers API ช่วยให้คุณสามารถสร้างและจัดการโปรไฟล์ลูกค้าพร้อมวิธีการชำระเงินที่บันทึกไว้ เก็บบัตรเครดิตอย่างปลอดภัย เรียกเก็บเงินจากลูกค้าประจำได้ง่าย และจัดการข้อมูลลูกค้าอย่างมีประสิทธิภาพ

Customer คือะไร

Customer เป็นออบเจ็กต์ที่แสดงถึงผู้ซื้อและประกอบด้วย:

ข้อมูลลูกค้า - อีเมล ชื่อ คำอธิบาย
บัตรที่บันทึกไว้ - วิธีการชำระเงินที่เก็บไว้อย่างปลอดภัย
บัตรเริ่มต้น - วิธีการชำระเงินหลักสำหรับการเรียกเก็บเงิน
เมตาดาต้า - ข้อมูลที่กำหนดเองสำหรับบันทึกของคุณ
ประวัติการเรียกเก็บเงิน - ติดตามการชำระเงินต่อลูกค้า

ฟีเจอร์หลัก

การเก็บบัตรอย่างปลอดภัย

PCI-compliant - Omise เก็บบัตรอย่างปลอดภัย
หลายบัตร - บันทึกวิธีการชำระเงินหลายรายการต่อลูกค้า
บัตรเริ่มต้น - ตั้งค่าวิธีการชำระเงินหลัก
ไม่มีข้อมูลที่ละเอียดอ่อน - เก็บเฉพาะโทเค็นบัตรเท่านั้น ไม่ใช่หมายเลขบัตรจริง

การชำระเงินซ้ำที่ง่ายดาย

การเรียกเก็บเงินคลิกเดียว - เรียกเก็บเงินจากลูกค้าโดยไม่ต้องทำโทเค็นใหม่
การสมัครสมาชิก - เหมาะสำหรับการเรียกเก็บเงินซ้ำ
วิธีการชำระเงินที่บันทึกไว้ - ลูกค้าไม่ต้องกรอกรายละเอียดบัตรอีกครั้ง
โปรไฟล์ลูกค้า - ติดตามประวัติการชำระเงินต่อลูกค้า

การจัดการที่ยืดหยุ่น

อัปเดตข้อมูลลูกค้า - เปลี่ยนอีเมล คำอธิบาย เมตาดาต้า
จัดการบัตร - เพิ่ม อัปเดต ลบวิธีการชำระเงิน
ตั้งค่าบัตรเริ่มต้น - เลือกบัตรที่จะเรียกเก็บเงิน
แสดงรายการลูกค้าทั้งหมด - แบ่งหน้าฐานข้อมูลลูกค้า

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

ขั้นตอนมาตรฐาน

┌─────────┐         ┌─────────┐         ┌─────────┐
│ Client  │         │ Your    │         │ Omise   │
│ Browser │         │ Server  │         │ API     │
└────┬────┘         └────┬────┘         └────┬────┘
     │                   │                   │
     │ 1. Enter card     │                   │
     ├──────────────────>│                   │
     │                   │                   │
     │ 2. Create token   │                   │
     │   (Omise.js)      │                   │
     ├──────────────────────────────────────>│
     │                   │                   │
     │ 3. Return token   │                   │
     │<──────────────────────────────────────┤
     │                   │                   │
     │ 4. Send token     │                   │
     ├──────────────────>│                   │
     │                   │                   │
     │                   │ 5. Create customer│
     │                   │   (with token)    │
     │                   ├──────────────────>│
     │                   │                   │
     │                   │ 6. Return customer│
     │                   │   (card saved)    │
     │                   │<──────────────────┤
     │                   │                   │
     │ 7. Future charges │                   │
     │   (no new token)  │                   │
     │                   ├──────────────────>│
     │                   │                   │

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

ครั้งแรก: ทำโทเค็นบัตร → สร้าง Customer ด้วยโทเค็น
บันทึกบัตร: สร้างโปรไฟล์ Customer พร้อมบัตรที่แนบมา
การชำระเงินในอนาคต: เรียกเก็บเงิน Customer ID โดยตรง (ไม่ต้องใช้โทเค็นใหม่)

API Endpoints

เมธอด	Endpoint	คำอธิบาย
POST	`/customers`	สร้าง Customer ใหม่
GET	`/customers/:id`	เรียกดูรายละเอียด Customer
PATCH	`/customers/:id`	อัปเดตข้อมูล Customer
DELETE	`/customers/:id`	ลบ Customer
GET	`/customers`	แสดงรายการ Customer ทั้งหมด
POST	`/customers/:id/cards`	เพิ่มบัตรให้กับ Customer
GET	`/customers/:id/cards/:card_id`	เรียกดูรายละเอียดบัตร
PATCH	`/customers/:id/cards/:card_id`	อัปเดตข้อมูลบัตร
DELETE	`/customers/:id/cards/:card_id`	ลบบัตรจาก Customer

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

สร้าง Customer พร้อมบัตร

// Client-side: ทำโทเค็นบัตร
Omise.setPublicKey('pkey_test_YOUR_PUBLIC_KEY');
Omise.createToken('card', cardData, async (status, response) => {
  if (status === 200) {
    // Server-side: สร้าง customer
    const customer = await omise.customers.create({
      email: 'john@example.com',
      description: 'John Doe',
      card: response.id  // โทเค็นจาก Omise.js
    });

    console.log('Customer created:', customer.id);
    console.log('Card saved:', customer.default_card);
  }
});

เรียกเก็บเงินจาก Customer ที่มีอยู่

// ไม่ต้องใช้โทเค็น - เรียกเก็บเงินจากลูกค้าโดยตรง
const charge = await omise.charges.create({
  customer: 'cust_test_5xuy4w91xqz7d1w9u0t',
  amount: 100000,
  currency: 'thb',
  description: 'Order #5678'
});

console.log('Charged customer:', charge.customer);
console.log('สถานะ:', charge.status);

เพิ่มบัตรเพิ่มเติม

// ทำโทเค็นบัตรใหม่
Omise.createToken('card', newCardData, async (status, response) => {
  if (status === 200) {
    // เพิ่มบัตรให้กับ customer ที่มีอยู่
    const card = await omise.customers.update('cust_test_5xuy4w91xqz7d1w9u0t', {
      card: response.id
    });

    console.log('Card added:', card.id);
  }
});

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

การเรียกเก็บเงินแบบสมัครสมาชิก

สร้าง Customer ครั้งเดียว เรียกเก็บเงินรายเดือนโดยอัตโนมัติ

// ตั้งค่าครั้งเดียว
const customer = await omise.customers.create({
  email: 'subscriber@example.com',
  card: tokenId
});

// การเรียกเก็บเงินรายเดือน (อัตโนมัติ)
setInterval(async () => {
  await omise.charges.create({
    customer: customer.id,
    amount: 99900,  // $9.99/เดือน
    currency: 'usd',
    description: 'Monthly subscription'
  });
}, 30 * 24 * 60 * 60 * 1000);  // 30 วัน

บันทึกบัตรเพื่อใช้ภายหลัง

ลูกค้าบันทึกบัตร ตัดสินใจซื้อในภายหลัง

// ชำระเงิน: บันทึกบัตร
const customer = await omise.customers.create({
  email: 'shopper@example.com',
  card: tokenId,
  metadata: { loyalty_id: '12345' }
});

// ภายหลัง: ชำระเงินอย่างรวดเร็ว
const charge = await omise.charges.create({
  customer: customer.id,
  amount: 250000,
  currency: 'thb'
});

วิธีการชำระเงินหลายรายการ

ลูกค้าจัดการบัตรหลายใบ

// เพิ่มหลายบัตร
await omise.customers.update(customerId, { card: token1 });
await omise.customers.update(customerId, { card: token2 });

// แสดงรายการบัตรของลูกค้า
const customer = await omise.customers.retrieve(customerId);
console.log('Cards:', customer.cards.data);

// เรียกเก็บเงินจากบัตรที่ระบุ
await omise.charges.create({
  customer: customerId,
  card: customer.cards.data[1].id,  // บัตรที่สอง
  amount: 100000
});

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

สถานะ

สถานะ	คำอธิบาย	สามารถเรียกเก็บเงินได้?
Active	Customer ที่มีบัตรที่ใช้งานได้	✅ ใช่
No Cards	Customer ที่ไม่มีวิธีการชำระเงิน	❌ ไม่ได้
Deleted	Customer ที่ถูกลบ	❌ ไม่ได้

การจัดการบัตร

เพิ่มบัตร: สร้างโทเค็น → อัปเดต Customer ด้วยโทเค็น
ตั้งค่าเริ่มต้น: อัปเดต Customer ด้วยพารามิเตอร์ default_card
ลบบัตร: ลบบัตรจาก Customer
อัปเดตบัตร: อัปเดตวันหมดอายุ ชื่อ ฯลฯ

แนวทางปฏิบัติที่ดีด้านความปลอดภัย

✅ ทำสิ่งนี้

ใช้โทเค็น เพื่อเพิ่มบัตร (ไม่ส่งข้อมูลบัตรจริง)
เก็บ Customer ID ในฐานข้อมูลของคุณ
ตรวจสอบความเป็นเจ้าของของลูกค้า ก่อนอนุญาตให้เรียกเก็บเงิน
ใช้เมตาดาต้า สำหรับการติดตามภายในของคุณ
ใช้การรับรองความถูกต้อง เพื่อปกป้องข้อมูลลูกค้า
จัดการข้อผิดพลาดของบัตร อย่างเหมาะสม (หมดอายุ ถูกปฏิเสธ)
ลบ Customer เก่า เมื่อไม่จำเป็นอีกต่อไป

❌ อย่าทำสิ่งนี้

อย่าส่งหมายเลขบัตร ไปยังเซิร์ฟเวอร์ของคุณ
อย่าเปิดเผย Customer ID สู่สาธารณะ
อย่าข้ามการอนุญาต (ตรวจสอบว่าผู้ใช้เป็นเจ้าของ Customer)
อย่าเก็บข้อมูลที่ละเอียดอ่อน ในเมตาดาต้า
อย่าเรียกเก็บเงินโดยไม่ได้รับอนุญาต (ข้อกำหนด PCI)
อย่าเก็บ Customer ที่ไม่ใช้งาน ไว้ไม่มีกำหนด

ความเป็นส่วนตัวของข้อมูล

ลบ Customer เมื่อมีการร้องขอ
ส่งออกข้อมูลลูกค้า ตามคำร้องขอ
ใช้เมตาดาต้าน้อยที่สุด (เฉพาะสิ่งที่จำเป็น)
รักษาความปลอดภัย Customer ID (อย่าเปิดเผยใน URL)

การปฏิบัติตาม PCI

ห้ามเก็บ หมายเลขบัตรจริง
ใช้โทเค็น สำหรับการดำเนินการทั้งหมดของบัตร
จำกัดการเข้าถึง ข้อมูลลูกค้า
ตรวจสอบ การเข้าถึงข้อมูลลูกค้า

การทดสอบ

ทดสอบ Customer

สร้าง Customer ทดสอบด้วยโทเค็นทดสอบ

// Customer โหมดทดสอบ
const customer = await omise.customers.create({
  email: 'test@example.com',
  card: 'tokn_test_no1t4tnemucod0e51mo'
});

// Customer ID เริ่มต้นด้วย cust_test_
console.log(customer.id);  // cust_test_...

บัตรทดสอบ

ใช้หมายเลขบัตรทดสอบ

4242424242424242 - Visa (สำเร็จ)
4000000000000002 - Visa (ถูกปฏิเสธ)
5555555555554444 - Mastercard (สำเร็จ)

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

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

รหัสข้อผิดพลาด	คำอธิบาย	วิธีแก้ไข
`used_token`	โทเค็นถูกใช้แล้ว	สร้างโทเค็นใหม่
`invalid_card`	บัตรไม่ถูกต้อง	ตรวจสอบรายละเอียดบัตร
`customer_not_found`	Customer ID ไม่มีอยู่	ตรวจสอบ Customer ID
`card_not_found`	บัตรไม่ได้เป็นของ Customer	ตรวจสอบ Card ID

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

สร้าง Customer - POST /customers
เรียกดู Customer - GET /customers/:id
อัปเดต Customer - PATCH /customers/:id
ลบ Customer - DELETE /customers/:id
แสดงรายการ Customer - GET /customers

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

คู่มือการผสานรวม

ต้องการความช่วยเหลือ? ดูคู่มือการจัดการลูกค้าของเรา หรือติดต่อ support@omise.co

ภาพรวม​

Customer คือะไร​

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

การเก็บบัตรอย่างปลอดภัย​

การชำระเงินซ้ำที่ง่ายดาย​

การจัดการที่ยืดหยุ่น​

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

ขั้นตอนมาตรฐาน​

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

API Endpoints​

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

สร้าง Customer พร้อมบัตร​

เรียกเก็บเงินจาก Customer ที่มีอยู่​

เพิ่มบัตรเพิ่มเติม​

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

การเรียกเก็บเงินแบบสมัครสมาชิก​

บันทึกบัตรเพื่อใช้ภายหลัง​

วิธีการชำระเงินหลายรายการ​

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

สถานะ​

การจัดการบัตร​

แนวทางปฏิบัติที่ดีด้านความปลอดภัย​

✅ ทำสิ่งนี้​

❌ อย่าทำสิ่งนี้​

ความเป็นส่วนตัวของข้อมูล​

การปฏิบัติตาม GDPR​

การปฏิบัติตาม PCI​

การทดสอบ​

ทดสอบ Customer​

บัตรทดสอบ​

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

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

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

คู่มือการผสานรวม​