ข้ามไปยังเนื้อหาหลัก
เวอร์ชัน: ล่าสุด

Cards API

ภาพรวม​

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

บัตรเป็นทรัพยากรของลูกค้า

บัตรใน Omise API จะเชื่อมโยงกับลูกค้าเสมอ ในการจัดการบัตร ใช้ Customer Cards endpoints

Endpoints ที่ใช้ได้​

การดำเนินการกับบัตรทั้งหมดอยู่ภายใต้ Customers API:

สิ่งที่คุณสามารถทำได้​

  • บันทึกบัตร - แนบบัตรที่ tokenize แล้วกับลูกค้า
  • แสดงรายการบัตรลูกค้า - ดูบัตรทั้งหมดของลูกค้า
  • อัปเดตรายละเอียดบัตร - แก้ไข metadata บัตร (ชื่อ, วันหมดอายุ, ที่อยู่สำหรับเรียกเก็บเงิน)
  • ตั้งค่าบัตรเริ่มต้น - เลือกบัตรที่จะใช้สำหรับ charges
  • ลบบัตร - ลบบัตรออกจากโปรไฟล์ลูกค้า
  • จัดการหลายบัตร - เก็บวิธีการชำระเงินหลายวิธีต่อลูกค้า

วิธีการทำงานของบัตร​

1. Tokenize ข้อมูลบัตร​

ขั้นแรก สร้าง token โดยใช้ public key ของคุณ (ฝั่ง client):

// Client-side with Omise.js
Omise.setPublicKey('pkey_test_...');
Omise.createToken('card', {
  name: 'JOHN DOE',
  number: '4242424242424242',
  expiration_month: 12,
  expiration_year: 2025,
  security_code: '123'
}, (status, response) => {
  if (status === 200) {
    // Send token to server
    sendTokenToServer(response.id);
  }
});

2. แนบบัตรกับลูกค้า​

จากนั้นแนบ token กับลูกค้า (ฝั่ง server):

// Server-side
const customer = await omise.customers.update('cust_test_...', {
  card: 'tokn_test_...'
});

console.log('Card added:', customer.cards.data[0].id);

3. ใช้บัตรที่บันทึกไว้​

เรียกเก็บเงินจากบัตรเริ่มต้นของลูกค้า:

const charge = await omise.charges.create({
  amount: 100000,
  currency: 'thb',
  customer: 'cust_test_...'
});

หรือระบุบัตรเฉพาะ:

const charge = await omise.charges.create({
  amount: 100000,
  currency: 'thb',
  customer: 'cust_test_...',
  card: 'card_test_...'
});

โครงสร้าง Card Object​

{
  "object": "card",
  "id": "card_test_5xuy4w91xqz7d1w9u0t",
  "livemode": false,
  "location": "/customers/cust_test_.../cards/card_test_...",
  "country": "th",
  "city": "Bangkok",
  "postal_code": "10320",
  "financing": "",
  "bank": "Bank of Ayudhya",
  "brand": "Visa",
  "fingerprint": "XK2FJbz+kQFvd/kLLRm1BVXR1kbwJpQp+lkFZyqP0u8=",
  "last_digits": "4242",
  "name": "JOHN DOE",
  "expiration_month": 12,
  "expiration_year": 2025,
  "security_code_check": true,
  "created_at": "2025-02-07T00:00:00Z"
}

ความปลอดภัยและ PCI Compliance​

แนวปฏิบัติที่ปลอดภัย​

  • อย่าส่งข้อมูลบัตรดิบ ไปยัง server ของคุณ
  • tokenize เสมอ โดยใช้ Omise.js (public key)
  • เก็บเฉพาะ tokens หรือ card IDs
  • อย่า log หมายเลขบัตร หรือรหัส CVV
  • ใช้ HTTPS สำหรับ API requests ทั้งหมด
  • ตรวจสอบที่ client ก่อน tokenization

การจัดเก็บข้อมูลบัตร​

เมื่อคุณบันทึกบัตรกับลูกค้า:

  • Omise จัดเก็บข้อมูลบัตรที่เข้ารหัส
  • คุณได้รับ card ID (card_test_...)
  • คุณสามารถดู 4 หลักสุดท้าย, แบรนด์, วันหมดอายุ
  • คุณจะไม่ได้รับหมายเลขบัตรเต็ม
  • CVV ไม่ถูกจัดเก็บ (ต้องการเสมอสำหรับ charges)

Use Cases​

Subscriptions และการเรียกเก็บเงินซ้ำ​

บันทึกบัตรลูกค้าสำหรับการเรียกเก็บเงินซ้ำ:

// Save card
const customer = await omise.customers.create({
  email: 'subscriber@example.com',
  card: 'tokn_test_...'
});

// Charge monthly
async function chargeMonthly() {
  const charge = await omise.charges.create({
    amount: 99900, // $999 subscription
    currency: 'thb',
    customer: customer.id,
    description: 'Monthly subscription'
  });
}

One-Click Checkout​

ให้ลูกค้าชำระเงินโดยไม่ต้องกรอกรายละเอียดบัตรอีก:

// Customer selects saved card at checkout
const cards = await omise.customers.listCards('cust_test_...');

// Display cards to customer
cards.data.forEach(card => {
  console.log(`${card.brand} ending in ${card.last_digits}`);
});

// Charge selected card
const charge = await omise.charges.create({
  amount: 150000,
  currency: 'thb',
  customer: 'cust_test_...',
  card: selectedCardId
});

อัปเดตบัตรที่หมดอายุ​

อัปเดตวันหมดอายุบัตร:

const updatedCard = await omise.customers.updateCard(
  'cust_test_...',
  'card_test_...',
  {
    expiration_month: 12,
    expiration_year: 2026,
    name: 'JOHN DOE'
  }
);

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

ควรทำ​

  • Tokenize ที่ฝั่ง client โดยใช้ Omise.js
  • ตั้งค่าบัตรเริ่มต้น เพื่อการเรียกเก็บเงินที่ง่ายขึ้น
  • อัปเดตวันหมดอายุ ล่วงหน้า
  • ลบบัตรเก่า เพื่อให้โปรไฟล์สะอาด
  • ตรวจสอบบัตร ด้วยการ authorization เล็กน้อย
  • จัดการการอัปเดตบัตร อย่างราบรื่นใน UI ของคุณ

ไม่ควรทำ​

  • อย่าส่งข้อมูลบัตรดิบ ไปยัง server ของคุณ
  • อย่าเก็บรหัส CVV (ผิดกฎหมายและไม่จำเป็น)
  • อย่าเรียกเก็บเงินจากบัตรที่ถูกลบ (ตรวจสอบว่าบัตรมีอยู่ก่อน)
  • อย่าเพิกเฉยต่อวันหมดอายุ (ตรวจสอบก่อนเรียกเก็บเงิน)
  • อย่าแชร์บัตร ระหว่างลูกค้า

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

ดูเพิ่มเติม​

พร้อมจัดการบัตร? เริ่มต้นด้วย แสดงรายการบัตร หรือเรียนรู้เกี่ยวกับ การสร้างลูกค้า