Tokens API

ภาพรวม

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

Token คืออะไร

Token เป็นการนำเสนอข้อมูลบัตรเครดิตแบบชั่วคราวและใช้ครั้งเดียวที่มีคุณสมบัติดังนี้

• หมดอายุหลังการใช้งาน - แต่ละ Token สามารถใช้ได้เพียงครั้งเดียวในการสร้าง Charge หรือแนบกับลูกค้า
• ป้องกันข้อมูลบัตร - เซิร์ฟเวอร์ของคุณไม่เคยจัดการรายละเอียดบัตรแบบดิบ
• เปิดใช้งานการปฏิบัติตาม PCI - ลดขอบเขตการปฏิบัติตาม PCI ของคุณอย่างมาก
• ตรวจสอบทันที - รายละเอียดบัตรได้รับการตรวจสอบระหว่างการแปลงเป็นโทเค็น

ฟีเจอร์หลัก

ความปลอดภัยเป็นอันดับแรก

• การยืนยันตัวตนด้วย Public Key - ใช้ public key ของคุณ (ปลอดภัยที่จะเปิดเผยในโค้ดฝั่งไคลเอนต์)
• Token ใช้ครั้งเดียว - Token ไม่สามารถนำมาใช้ซ้ำหลังจากสร้าง Charge
• ไม่มีการจัดเก็บข้อมูลที่ละเอียดอ่อน - ข้อมูลบัตรไม่เคยสัมผัสเซิร์ฟเวอร์ของคุณ
• สอดคล้องกับ PCI DSS - ตรงตามมาตรฐานความปลอดภัยที่เข้มงวดที่สุด

การผสานรวมที่ง่าย

• การแปลงเป็นโทเค็นฝั่งไคลเอนต์ - สร้าง Token โดยตรงจากเบราว์เซอร์/แอปมือถือ
• ไลบรารี Omise.js - ไลบรารี JavaScript ที่สร้างไว้ล่วงหน้าเพื่อการผสานรวมที่ง่าย
• Mobile SDK - มี Native iOS และ Android SDK ให้ใช้งาน
• การสื่อสารระหว่างเซิร์ฟเวอร์ - API พร้อมใช้งานสำหรับการแปลงเป็นโทเค็นฝั่งเซิร์ฟเวอร์เมื่อจำเป็น

ความยืดหยุ่น

• ทำงานกับบัตรทุกประเภท - Visa, Mastercard, JCB และอื่นๆ
• รองรับ 3D Secure - การจัดการ 3DS อัตโนมัติ
• การตรวจสอบบัตร - ตรวจสอบหมายเลขบัตร, CVV, วันหมดอายุ
• รองรับระดับสากล - ประมวลผลบัตรจากทุกประเทศ

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

กระบวนการมาตรฐาน

┌─────────┐         ┌─────────┐         ┌─────────┐         ┌─────────┐
│ Client  │         │ Omise.js│         │ Your    │         │ Omise   │
│ Browser │         │ Library │         │ Server  │         │ API     │
└────┬────┘         └────┬────┘         └────┬────┘         └────┬────┘
     │                   │                   │                   │
     │ 1. Enter card     │                   │                   │
     ├──────────────────>│                   │                   │
     │                   │                   │                   │
     │                   │ 2. Create token   │                   │
     │                   │   (with public key)                   │
     │                   ├──────────────────────────────────────>│
     │                   │                   │                   │
     │                   │ 3. Return token   │                   │
     │                   │<──────────────────────────────────────┤
     │                   │                   │                   │
     │ 4. Send token ID  │                   │                   │
     ├──────────────────────────────────────>│                   │
     │                   │                   │                   │
     │                   │                   │ 5. Create charge  │
     │                   │                   │   (with secret key)
     │                   │                   ├──────────────────>│
     │                   │                   │                   │
     │                   │                   │ 6. Charge result  │
     │                   │                   │<──────────────────┤
     │                   │                   │                   │
     │ 7. Show result    │                   │                   │
     │<──────────────────────────────────────┤                   │
     │                   │                   │                   │

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

1. ฝั่งไคลเอนต์: รวบรวมรายละเอียดบัตรในฟอร์มการชำระเงินของคุณ
2. ฝั่งไคลเอนต์: ใช้ Omise.js เพื่อแปลงเป็นโทเค็นข้อมูลบัตรด้วย public key ของคุณ
3. ฝั่งไคลเอนต์: ส่ง Token ID ไปยังเซิร์ฟเวอร์ของคุณ (ปลอดภัย - ใช้ครั้งเดียว)
4. ฝั่งเซิร์ฟเวอร์: สร้าง Charge โดยใช้ Token ID กับ secret key ของคุณ
5. ฝั่งเซิร์ฟเวอร์: ส่งผลการชำระเงินกลับไปยังไคลเอนต์

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

สถานะ

สถานะ	คำอธิบาย	สามารถสร้าง Charge ได้หรือไม่
Active	Token ที่สร้างใหม่และยังไม่ได้ใช้	✅ ได้
Used	Token ที่ใช้แล้วในการสร้าง Charge/ลูกค้า	❌ ไม่ได้ - ข้อผิดพลาด "used_token"
Expired	Token ที่เก่ากว่า 30 นาที	❌ ไม่ได้ - ข้อผิดพลาด "token_expired"

การเปลี่ยนสถานะ

Token เปลี่ยนผ่านสถานะตามตัวกระตุ้นต่อไปนี้

┌─────────┐
│ Active  │ ← Token สร้างผ่าน Omise.js หรือ API
└────┬────┘
     │
     ├─────────────┐
     │             │
     ▼             ▼
┌─────────┐   ┌─────────┐
│  Used   │   │ Expired │
└─────────┘   └─────────┘

ตัวกระตุ้นการเปลี่ยนสถานะ:

จากสถานะ	ไปสถานะ	ตัวกระตุ้น	รหัสข้อผิดพลาด
Active → Used	Token ใช้ใน POST /charges หรือ POST /customers/:id/cards	-
Active → Expired	ผ่านไป 30 นาทีนับจากการสร้าง	token_expired
Used → same	พยายามใช้ Token ซ้ำ	used_token
Expired → same	พยายามใช้ Token ที่หมดอายุ	token_expired

ตัวอย่างการเปลี่ยนสถานะ:

// 1. สร้าง Token (สถานะ Active)
const token = await omise.tokens.create({
  card: {
    number: '4242424242424242',
    expiration_month: 12,
    expiration_year: 2027,
    security_code: '123',
    name: 'JOHN DOE'
  }
});
console.log(token.used); // false (Active)

// 2. สร้าง Charge (Active → Used)
const charge = await omise.charges.create({
  amount: 100000,
  currency: 'thb',
  card: token.id
});
// Token ถูกทำเครื่องหมายว่าใช้แล้ว

// 3. พยายามใช้ซ้ำ (ข้อผิดพลาด: used_token)
try {
  await omise.charges.create({
    amount: 50000,
    currency: 'thb',
    card: token.id  // Token เดียวกัน
  });
} catch (error) {
  console.error(error.code); // "used_token"
  console.error(error.message); // "token was already used"
}

// 4. Token หมดอายุหลังจาก 30 นาที (Active → Expired)
// อัตโนมัติ - ไม่ต้องทำอะไร
// หากไม่ได้ใช้เกิน 30 นาที token.used === false แต่ API จะคืนค่า token_expired

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

• การหมดอายุอัตโนมัติ: 30 นาทีหลังจากสร้าง
• ใช้ครั้งเดียว: ทำเครื่องหมายว่าใช้แล้วทันทีหลังจาก Charge ครั้งแรก/แนบกับลูกค้า
• ไม่สามารถใช้ซ้ำได้: ไม่สามารถใช้ซ้ำแม้กับลูกค้าคนเดียวกัน
• ไม่สามารถย้อนกลับได้: Token ที่ใช้แล้วและหมดอายุไม่สามารถเปิดใช้งานใหม่ได้

API Endpoint

เมธอด	Endpoint	คำอธิบาย
POST	/tokens	สร้าง Token ใหม่จากข้อมูลบัตร
GET	/tokens/:id	ดึงข้อมูล Token

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

การใช้ Omise.js (แนะนำ)

<!-- 1. รวม Omise.js -->
<script src="https://cdn.omise.co/omise.js"></script>

<script>
// 2. ตั้งค่า public key
Omise.setPublicKey('pkey_test_YOUR_PUBLIC_KEY');

// 3. แปลงเป็นโทเค็นบัตร
const cardData = {
  name: 'JOHN DOE',
  number: '4242424242424242',
  expiration_month: 12,
  expiration_year: 2025,
  security_code: '123'
};

Omise.createToken('card', cardData, (statusCode, response) => {
  if (statusCode === 200) {
    // สำเร็จ - Token ถูกสร้างแล้ว
    const tokenId = response.id;

    // 4. ส่ง Token ไปยังเซิร์ฟเวอร์ของคุณ
    fetch('/charge', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ token: tokenId, amount: 100000 })
    })
    .then(res => res.json())
    .then(data => {
      console.log('Charge created:', data.id);
    })
    .catch(err => {
      console.error('Charge failed:', err);
      alert('การประมวลผลการชำระเงินล้มเหลว กรุณาลองอีกครั้ง');
    });
  } else {
    // การแปลงเป็นโทเค็นล้มเหลว - จัดการข้อผิดพลาดเฉพาะ
    console.error('Tokenization failed:', response);

    // จัดการรหัสข้อผิดพลาดทั่วไป
    switch (response.code) {
      case 'invalid_card':
        alert('หมายเลขบัตรไม่ถูกต้อง กรุณาตรวจสอบและลองอีกครั้ง');
        break;
      case 'invalid_expiration_date':
        alert('วันหมดอายุไม่ถูกต้อง กรุณาตรวจสอบและลองอีกครั้ง');
        break;
      case 'invalid_security_code':
        alert('CVV/รหัสความปลอดภัยไม่ถูกต้อง กรุณาตรวจสอบและลองอีกครั้ง');
        break;
      case 'network_error':
        alert('ข้อผิดพลาดเครือข่าย กรุณาตรวจสอบการเชื่อมต่อของคุณและลองอีกครั้ง');
        break;
      default:
        alert('การชำระเงินล้มเหลว: ' + response.message);
    }
  }
});
</script>

การประมวลผลฝั่งเซิร์ฟเวอร์

// ตัวอย่าง Node.js
const omise = require('omise')({
  secretKey: 'skey_test_YOUR_SECRET_KEY'
});

// รับ Token จากไคลเอนต์
app.post('/charge', async (req, res) => {
  const { token, amount } = req.body;

  try {
    // สร้าง Charge ด้วย Token
    const charge = await omise.charges.create({
      amount: amount,
      currency: 'thb',
      card: token  // ใช้ Token ที่นี่
    });

    res.json({ success: true, charge: charge });
  } catch (error) {
    res.status(400).json({ error: error.message });
  }
});

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

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

สร้าง Token → สร้าง Charge → เสร็จสิ้น

// ไคลเอนต์: แปลงเป็นโทเค็น
Omise.createToken('card', cardData, (status, response) => {
  // เซิร์ฟเวอร์: Charge
  omise.charges.create({ card: response.id, amount: 100000 });
});

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

สร้าง Token → แนบกับลูกค้า → Charge ลูกค้า

// สร้างลูกค้าด้วย Token
const customer = await omise.customers.create({
  email: 'john@example.com',
  card: tokenId
});

// ภายหลัง: Charge บัตรที่บันทึกไว้ของลูกค้า
const charge = await omise.charges.create({
  customer: customer.id,
  amount: 100000
});

หลายบัตรต่อลูกค้า

สร้าง Token → แนบกับลูกค้าที่มีอยู่ → เลือกบัตรที่จะ Charge

// เพิ่มบัตรให้กับลูกค้า
const card = await omise.customers.updateCard(customerId, {
  card: tokenId
});

// Charge บัตรที่ระบุ
const charge = await omise.charges.create({
  customer: customerId,
  card: card.id,
  amount: 100000
});

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

✅ สิ่งที่ควรทำ

• ใช้ HTTPS สำหรับหน้าเว็บทั้งหมดที่มีฟอร์มการชำระเงิน
• ใช้ Omise.js สำหรับการแปลงเป็นโทเค็นฝั่งไคลเอนต์
• ตรวจสอบบนเซิร์ฟเวอร์ - อย่าเชื่อการตรวจสอบฝั่งไคลเอนต์เพียงอย่างเดียว
• อย่าบันทึก Token ในข้อความธรรมดา
• ใช้ public key ฝั่งไคลเอนต์เท่านั้น
• ใช้ secret key ฝั่งเซิร์ฟเวอร์เท่านั้น
• ใช้ CSP header เพื่อป้องกันการโจมตี XSS

❌ สิ่งที่ไม่ควรทำ

• อย่าส่งข้อมูลบัตรไปยังเซิร์ฟเวอร์ของคุณ (ใช้การแปลงเป็นโทเค็น)
• อย่าเก็บหมายเลขบัตร ในฐานข้อมูลของคุณ
• อย่าใช้ Token ซ้ำ (มันเป็นแบบใช้ครั้งเดียว)
• อย่าเปิดเผย secret key ในโค้ดฝั่งไคลเอนต์
• อย่าข้ามการตรวจสอบฝั่งเซิร์ฟเวอร์
• อย่าทำการแปลงเป็นโทเค็นบนเซิร์ฟเวอร์ เว้นแต่จำเป็น (ใช้ฝั่งไคลเอนต์)

การทดสอบ

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

ใช้บัตรทดสอบเหล่านี้ในโหมดทดสอบ:

หมายเลขบัตร	คำอธิบาย	ผลลัพธ์
4242424242424242	Visa	Charge สำเร็จ
5555555555554444	Mastercard	Charge สำเร็จ
4111111111111111	Visa	Charge สำเร็จ
4000000000000002	Visa	บัตรถูกปฏิเสธ

โหมดทดสอบ

• ใช้ test public key ของคุณ: pkey_test_...
• Token ที่สร้างด้วย test key จะทำงานกับ test secret key เท่านั้น
• ไม่มีเงินจริงที่ถูกเรียกเก็บในโหมดทดสอบ

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

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

รหัสข้อผิดพลาด	คำอธิบาย	วิธีแก้ไข
invalid_card	หมายเลขบัตรไม่ถูกต้อง	ตรวจสอบรูปแบบหมายเลขบัตร
invalid_expiration_date	วันที่ไม่ถูกต้องหรือหมดอายุ	ตรวจสอบเดือน/ปีที่หมดอายุ
invalid_security_code	CVV ไม่ถูกต้อง	ตรวจสอบว่า CVV เป็นตัวเลข 3-4 หลัก
used_token	Token ถูกใช้แล้ว	สร้าง Token ใหม่
token_not_found	ไม่พบ Token	ตรวจสอบ Token ID

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

• สร้าง Token - POST /tokens
• ดึงข้อมูล Token - GET /tokens/:id

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

• เอกสาร Omise.js
• สร้าง Charge
• Customers API
• Cards API

SDK และไลบรารี

• Omise.js - ไลบรารี JavaScript
• iOS SDK - Native iOS
• Android SDK - Native Android
• Server SDK - Ruby, Python, PHP, Node.js, Go, Java, .NET

---

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