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

Tokens API

ภาพรวม

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

Token คืออะไร?

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

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

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

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

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

การผสานรวมง่ายดาย

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

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

ใช้งานได้กับบัตรทุกประเภท - Visa, Mastercard, JCB ฯลฯ
รองรับ 3D Secure - จัดการ 3DS อัตโนมัติ
การตรวจสอบบัตร - ตรวจสอบหมายเลขบัตร CVV วันหมดอายุ
รองรับต่างประเทศ - ประมวลผลบัตรจากทุกประเทศ

การทำงานของ Token

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

┌─────────┐         ┌─────────┐         ┌─────────┐         ┌─────────┐
│ Client  │         │ Omise.js│         │ Your    │         │ Omise   │
│ Browser │         │ Library │         │ Server  │         │ API     │
└────┬────┘         └────┬────┘         └────┬────┘         └────┬────┘
     │                   │                   │                   │
     │ 1. กรอกข้อมูลบัตร │                   │                   │
     ├──────────────────>│                   │                   │
     │                   │                   │                   │
     │                   │ 2. สร้าง Token    │                   │
     │                   │   (ด้วย public key)                   │
     │                   ├──────────────────────────────────────>│
     │                   │                   │                   │
     │                   │ 3. ส่ง Token กลับ │                   │
     │                   │<──────────────────────────────────────┤
     │                   │                   │                   │
     │ 4. ส่ง Token ID   │                   │                   │
     ├──────────────────────────────────────>│                   │
     │                   │                   │                   │
     │                   │                   │ 5. สร้างการเรียก  │
     │                   │                   │   เก็บเงิน        │
     │                   │                   │   (ด้วย secret key)
     │                   │                   ├──────────────────>│
     │                   │                   │                   │
     │                   │                   │ 6. ผลการเรียก     │
     │                   │                   │   เก็บเงิน        │
     │                   │                   │<──────────────────┤
     │                   │                   │                   │
     │ 7. แสดงผลลัพธ์    │                   │                   │
     │<──────────────────────────────────────┤                   │
     │                   │                   │                   │

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

ฝั่งไคลเอนต์: รวบรวมรายละเอียดบัตรในแบบฟอร์มชำระเงินของคุณ
ฝั่งไคลเอนต์: ใช้ Omise.js เพื่อแปลงข้อมูลบัตรเป็น Token ด้วย Public Key ของคุณ
ฝั่งไคลเอนต์: ส่ง Token ID ไปยังเซิร์ฟเวอร์ของคุณ (ปลอดภัย - ใช้ได้ครั้งเดียว)
ฝั่งเซิร์ฟเวอร์: สร้างการเรียกเก็บเงินโดยใช้ Token ID ด้วย Secret Key ของคุณ
ฝั่งเซิร์ฟเวอร์: ส่งผลการชำระเงินกลับไปยังไคลเอนต์

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

สถานะ

สถานะ	คำอธิบาย	สามารถสร้างการเรียกเก็บเงินได้?
Active	Token ที่สร้างใหม่ ยังไม่ได้ใช้	ได้
Used	Token ที่ใช้สร้างการเรียกเก็บเงิน/ลูกค้าแล้ว	ไม่ได้ - ข้อผิดพลาด "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 → เหมือนเดิม	พยายามใช้ Token ซ้ำ	`used_token`
Expired → เหมือนเดิม	พยายามใช้ 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. สร้างการเรียกเก็บเงิน (Active → Used)
const charge = await omise.charges.create({
  amount: 100000,
  currency: 'thb',
  card: token.id
});
// Token ตอนนี้ถูกทำเครื่องหมายว่า Used

// 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 นาทีหลังสร้าง
ใช้ครั้งเดียว: ถูกทำเครื่องหมายว่าใช้แล้วทันทีหลังการเรียกเก็บเงิน/ผูกลูกค้าครั้งแรก
ไม่สามารถใช้ซ้ำ: ไม่สามารถใช้ซ้ำได้แม้สำหรับลูกค้าคนเดิม
ย้อนกลับไม่ได้: Token ที่ใช้แล้วและหมดอายุไม่สามารถเปิดใช้งานใหม่ได้

API Endpoints

Method	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. แปลงข้อมูลบัตรเป็น Token
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('สร้างการเรียกเก็บเงินแล้ว:', data.id);
    })
    .catch(err => {
      console.error('การเรียกเก็บเงินล้มเหลว:', err);
      alert('การประมวลผลการชำระเงินล้มเหลว กรุณาลองใหม่อีกครั้ง');
    });
  } else {
    // การสร้าง Token ล้มเหลว - จัดการข้อผิดพลาดเฉพาะ
    console.error('การสร้าง Token ล้มเหลว:', 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 {
    // สร้างการเรียกเก็บเงินด้วย 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 → สร้างการเรียกเก็บเงิน → เสร็จสิ้น

// ไคลเอนต์: สร้าง Token
Omise.createToken('card', cardData, (status, response) => {
  // เซิร์ฟเวอร์: เรียกเก็บเงิน
  omise.charges.create({ card: response.id, amount: 100000 });
});

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

สร้าง Token → ผูกกับลูกค้า → เรียกเก็บเงินลูกค้า

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

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

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

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

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

// เรียกเก็บเงินจากบัตรที่ระบุ
const charge = await omise.charges.create({
  customer: customerId,
  card: card.id,
  amount: 100000
});

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

ควรทำ

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

ไม่ควรทำ

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

การทดสอบ

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

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

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

โหมดทดสอบ

ใช้ Public Key ทดสอบ ของคุณ: pkey_test_...
Token ที่สร้างด้วย Key ทดสอบใช้ได้เฉพาะกับ 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

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

SDKs และไลบรารี

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

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

ภาพรวม​

Token คืออะไร?​

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

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

การผสานรวมง่ายดาย​

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

การทำงานของ Token​

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

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

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

สถานะ​

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

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

API Endpoints​

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

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

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

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

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

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

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

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

ควรทำ​

ไม่ควรทำ​

การทดสอบ​

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

โหมดทดสอบ​

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

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

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

SDKs และไลบรารี​