Customers API

ภาพรวม

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

ลูกค้าคืออะไร?

ลูกค้าเป็น objects ที่แทนผู้ซื้อของคุณและประกอบด้วย:

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

คุณสมบัติหลัก

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

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

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

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

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

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

การทำงานของลูกค้า

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

┌─────────┐         ┌─────────┐         ┌─────────┐
│ Client  │         │ Your    │         │ Omise   │
│ Browser │         │ Server  │         │ API     │
└────┬────┘         └────┬────┘         └────┬────┘
     │                   │                   │
     │ 1. กรอกบัตร       │                   │
     ├──────────────────>│                   │
     │                   │                   │
     │ 2. สร้าง token    │                   │
     │   (Omise.js)      │                   │
     ├──────────────────────────────────────>│
     │                   │                   │
     │ 3. ส่งคืน token   │                   │
     │<──────────────────────────────────────┤
     │                   │                   │
     │ 4. ส่ง token      │                   │
     ├──────────────────>│                   │
     │                   │                   │
     │                   │ 5. สร้างลูกค้า    │
     │                   │   (พร้อม token)   │
     │                   ├──────────────────>│
     │                   │                   │
     │                   │ 6. ส่งคืนลูกค้า   │
     │                   │   (บัตรบันทึกแล้ว) │
     │                   │<──────────────────┤
     │                   │                   │
     │ 7. เรียกเก็บเงินในอนาคต │              │
     │   (ไม่ต้อง token ใหม่)  │              │
     │                   ├──────────────────>│
     │                   │                   │

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

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

API Endpoints

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

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

สร้างลูกค้าพร้อมบัตร

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

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

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

// ไม่ต้อง token - เรียกเก็บเงินจากลูกค้าโดยตรง
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('Status:', charge.status);

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

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

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

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

การเรียกเก็บเงิน Subscription

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

// ตั้งค่าครั้งเดียว
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 วัน

บันทึกบัตรไว้ใช้ภายหลัง

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

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

// ภายหลัง: Checkout ด่วน
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
});

วงจรชีวิตลูกค้า

สถานะ

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

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

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

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

ทำสิ่งนี้

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

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

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

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

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

• ลบลูกค้า เมื่อได้รับคำขอ
• ส่งออกข้อมูลลูกค้า ตามคำขอ
• ใช้ metadata น้อยที่สุด (เฉพาะสิ่งที่จำเป็น)
• รักษา customer IDs อย่างปลอดภัย (อย่าเปิดเผยใน URLs)

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

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

การทดสอบ

ลูกค้าทดสอบ

สร้างลูกค้าทดสอบด้วย tokens ทดสอบ:

// ลูกค้าโหมดทดสอบ
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 (สำเร็จ)

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

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

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

API Reference

• Create Customer - POST /customers
• Retrieve Customer - GET /customers/:id
• Update Customer - PATCH /customers/:id
• Delete Customer - DELETE /customers/:id
• List Customers - GET /customers

แหล่งข้อมูลที่เกี่ยวข้อง

• Create Charge
• Create Token
• Cards API
• Omise.js Guide

คู่มือการรวมระบบ

• Subscription Billing
• Saved Payment Methods
• Customer Management

---

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