API ลิงก์การชำระเงิน

อัตโนมัติการสร้างและการจัดการลิงก์การชำระเงินโดยใช้ API ลิงก์การชำระเงิน Omise เหมาะสำหรับธุรกิจที่ต้องสร้างลิงก์จำนวนมาก ผสานรวมกับระบบที่มีอยู่ หรือสร้างประสบการณ์การชำระเงินที่ไดนามิก

ภาพรวม

API ลิงก์การชำระเงิน ช่วยให้คุณ:

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

การพิสูจน์ตัวตน

ส่วนขยาย API ทั้งหมดต้องใช้การพิสูจน์ตัวตนด้วยคีย์ลับ:

curl https://api.omise.co/links \
  -u skey_test_xxx:

สำคัญ:

• ใช้ skey_test_xxx สำหรับโหมดทดสอบ
• ใช้ skey_live_xxx สำหรับโหมดการทำงาน
• ไม่ต้องเปิดเผยคีย์ลับในโค้ดฝั่งไคลเอ็นต์
• เก็บคีย์ลับให้ปลอดภัย

จุดสิ้นสุด API

URL พื้นฐาน

https://api.omise.co

จุดสิ้นสุดที่มี

วิธีการ	จุดสิ้นสุด	คำอธิบาย
POST	/links	สร้างลิงก์การชำระเงิน
GET	/links/:id	ดึงข้อมูลลิงก์การชำระเงิน
PATCH	/links/:id	อัปเดตลิงก์การชำระเงิน
GET	/links	แสดงรายการลิงก์การชำระเงินทั้งหมด

สร้างลิงก์การชำระเงิน

การสร้างพื้นฐาน

สร้างลิงก์การชำระเงินง่าย:

const omise = require('omise')({
  secretKey: 'skey_test_xxx'
});

omise.links.create({
  amount: 100000, // จำนวนเงินในหน่วยสกุลเงินที่เล็กที่สุด (1,000.00 THB)
  currency: 'thb',
  title: 'ซื้อสินค้า',
  description: 'การซื้อวิดเจ็ตพรีเมียม',
  multiple: true // ลิงก์ที่ใช้ได้หลายครั้ง
}, function(error, link) {
  if (error) {
    console.error('ข้อผิดพลาด:', error);
  } else {
    console.log('สร้างลิงก์:', link.payment_uri);
  }
});

ตอบกลับ:

{
  "object": "link",
  "id": "payl_test_5xyx8z94w46ixr9l",
  "livemode": false,
  "location": "/links/payl_test_5xyx8z94w46ixr9l",
  "amount": 100000,
  "currency": "thb",
  "title": "ซื้อสินค้า",
  "description": "การซื้อวิดเจ็ตพรีเมียม",
  "multiple": true,
  "payment_uri": "https://pay.omise.co/links/payl_test_5xyx8z94w46ixr9l",
  "used": false,
  "charges": {
    "object": "list",
    "data": [],
    "total": 0
  },
  "created_at": "2026-02-06T10:30:00Z"
}

ใช้ cURL

curl https://api.omise.co/links \
  -u skey_test_xxx: \
  -d "amount=100000" \
  -d "currency=thb" \
  -d "title=ซื้อสินค้า" \
  -d "description=การซื้อวิดเจ็ตพรีเมียม" \
  -d "multiple=true"

ใช้ Python

import omise

omise.api_secret = 'skey_test_xxx'

link = omise.Link.create(
    amount=100000,
    currency='thb',
    title='ซื้อสินค้า',
    description='การซื้อวิดเจ็ตพรีเมียม',
    multiple=True
)

print(f"URL ลิงก์: {link.payment_uri}")

ใช้ PHP

<?php
require_once 'vendor/autoload.php';

define('OMISE_SECRET_KEY', 'skey_test_xxx');

$link = OmiseLink::create([
    'amount' => 100000,
    'currency' => 'thb',
    'title' => 'ซื้อสินค้า',
    'description' => 'การซื้อวิดเจ็ตพรีเมียม',
    'multiple' => true
]);

echo "URL ลิงก์: " . $link['payment_uri'];
?>

ใช้ Ruby

require 'omise'

Omise.api_key = 'skey_test_xxx'

link = Omise::Link.create({
  amount: 100000,
  currency: 'thb',
  title: 'ซื้อสินค้า',
  description: 'การซื้อวิดเจ็ตพรีเมียม',
  multiple: true
})

puts "URL ลิงก์: #{link.payment_uri}"

พารามิเตอร์ส่วนขยาย

พารามิเตอร์ที่จำเป็น

พารามิเตอร์	ชนิด	คำอธิบาย
amount	integer	จำนวนเงินในหน่วยสกุลเงินที่เล็กที่สุด (เช่น satang สำหรับ THB)
currency	string	รหัสสกุลเงิน ISO 3 ตัวอักษร (เช่น thb, usd)
title	string	ชื่อลิงก์ที่แสดงให้ลูกค้าเห็น (สูงสุด 200 ตัวอักษร)

พารามิเตอร์ทางเลือก

พารามิเตอร์	ชนิด	เริ่มต้น	คำอธิบาย
description	string	null	คำอธิบายโดยละเอียด (สูงสุด 1000 ตัวอักษร)
multiple	boolean	false	อนุญาตการใช้งานหลายครั้ง (true) หรือการใช้งานครั้งเดียว (false)
metadata	object		ข้อมูลเมตาแบบกำหนดเอง (คู่คีย์-ค่า)

ตัวอย่างการสร้างขั้นสูง

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

เหมาะสำหรับใบแจ้งหนี้:

omise.links.create({
  amount: 250000, // 2,500.00 THB
  currency: 'thb',
  title: 'ใบแจ้งหนี้ #INV-001',
  description: 'การชำระเงินสำหรับบริการปรึกษา',
  multiple: false, // ใช้ได้ครั้งเดียวเท่านั้น
  metadata: {
    invoice_id: 'INV-001',
    customer_id: 'CUST-123',
    customer_email: 'customer@example.com'
  }
}, function(error, link) {
  if (!error) {
    console.log('ลิงก์ใบแจ้งหนี้:', link.payment_uri);
    console.log('รหัสลิงก์:', link.id);
  }
});

ลิงก์พร้อมข้อมูลเมตา

เก็บข้อมูลแบบกำหนดเอง:

omise.links.create({
  amount: 150000,
  currency: 'thb',
  title: 'การจองปรึกษา',
  description: 'เซสชั่นปรึกษา 1 ชั่วโมง',
  multiple: true,
  metadata: {
    service_type: 'consultation',
    duration: '60_minutes',
    category: 'business',
    booking_date: '2026-03-15',
    time_slot: '14:00',
    consultant_id: 'CONS-456'
  }
}, function(error, link) {
  if (!error) {
    console.log('สร้างลิงก์การจอง');
    // บันทึก link.id ในฐานข้อมูล
  }
});

ดึงข้อมูลลิงก์การชำระเงิน

ดึงข้อมูลลิงก์เฉพาะ

ดึงข้อมูลลิงก์ตามรหัส:

omise.links.retrieve('payl_test_5xyx8z94w46ixr9l', function(error, link) {
  if (!error) {
    console.log('สถานะลิงก์:', link.used ? 'ใช้แล้ว' : 'ใช้งานอยู่');
    console.log('ค่าใช้สอยทั้งหมด:', link.charges.total);
    console.log('สร้างเมื่อ:', link.created_at);
  }
});

ใช้ cURL:

curl https://api.omise.co/links/payl_test_5xyx8z94w46ixr9l \
  -u skey_test_xxx:

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

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

omise.links.create({
  amount: 100000,
  currency: 'thb',
  title: 'สินค้า'
}, function(error, link) {
  if (error) {
    switch(error.code) {
      case 'invalid_amount':
        console.error('จำนวนเงินไม่ถูกต้อง:', error.message);
        break;
      case 'invalid_currency':
        console.error('สกุลเงินไม่รองรับ:', error.message);
        break;
      case 'authentication_failure':
        console.error('คีย์ API ไม่ถูกต้อง:', error.message);
        break;
      default:
        console.error('ข้อผิดพลาด:', error.message);
    }
  }
});

รหัสข้อผิดพลาดทั่วไป

รหัส	คำอธิบาย	วิธีแก้
authentication_failure	คีย์ API ไม่ถูกต้อง	ตรวจสอบคีย์ลับของคุณ
invalid_amount	จำนวนเงินไม่ถูกต้อง	ใช้จำนวนเต็มบวกในหน่วยที่เล็กที่สุด
invalid_currency	สกุลเงินไม่รองรับ	ใช้รหัสสกุลเงินที่รองรับ
invalid_card	การตรวจสอบบัตรล้มเหลว	ตรวจสอบรายละเอียดบัตร
insufficient_fund	ยอดคงเหลือไม่เพียงพอ	ลูกค้าต้องเติมเงิน
failed_processing	การประมวลผลการชำระเงินล้มเหลว	ลองใหม่หรือติดต่อการสนับสนุน

Webhooks

รับการแจ้งเตือนแบบเรียลไทม์เกี่ยวกับเหตุการณ์ลิงก์การชำระเงิน:

const express = require('express');
const app = express();

app.post('/webhooks/omise', express.json(), (req, res) => {
  const event = req.body;

  switch(event.key) {
    case 'charge.create':
      handleChargeCreated(event.data);
      break;
    case 'charge.complete':
      handleChargeCompleted(event.data);
      break;
    case 'charge.failed':
      handleChargeFailed(event.data);
      break;
  }

  res.sendStatus(200);
});

function handleChargeCompleted(charge) {
  // ตรวจสอบว่าค่าใช้สอยมาจากลิงก์การชำระเงิน
  if (charge.source && charge.source.type === 'link') {
    const linkId = charge.source.id;

    console.log('ได้รับการชำระเงินสำหรับลิงก์:', linkId);

    // ดึงข้อมูลรายละเอียดลิงก์
    omise.links.retrieve(linkId, (error, link) => {
      if (!error) {
        const metadata = link.metadata;

        // ประมวลผลตามข้อมูลเมตา
        if (metadata.invoice_id) {
          markInvoicePaid(metadata.invoice_id);
        } else if (metadata.product_id) {
          fulfillOrder(metadata.product_id, charge);
        }

        // ส่งอีเมลยืนยัน
        sendConfirmationEmail(charge.customer_email, {
          amount: charge.amount,
          description: link.title
        });
      }
    });
  }
}

app.listen(3000);

สรุปวิธีปฏิบัติที่ดีที่สุด

1. ใช้ข้อมูลเมตาอย่างมีประสิทธิผล

เก็บข้อมูลที่เกี่ยวข้องทั้งหมด:

omise.links.create({
  amount: 100000,
  currency: 'thb',
  title: 'ซื้อสินค้า',
  metadata: {
    // บริบททางธุรกิจ
    order_id: 'ORD-123',
    customer_id: 'CUST-456',

    // รายละเอียดสินค้า
    product_id: 'PROD-789',
    product_sku: 'WIDGET-001',

    // ข้อมูลการปฏิบัติ
    shipping_required: 'true',
    warehouse: 'BKK-01',

    // การติดตาม
    campaign: 'summer-sale',
    referrer: 'social-media',

    // ติดต่อ
    customer_email: 'customer@example.com',
    customer_phone: '+66812345678'
  }
});

2. จัดการข้อผิดพลาดอย่างเหมาะสม

ดำเนินการลองใหม่ด้วยการถ่วงน้ำหนัก:

async function createLinkWithRetry(data, maxRetries = 3) {
  let lastError;

  for (let i = 0; i < maxRetries; i++) {
    try {
      const link = await new Promise((resolve, reject) => {
        omise.links.create(data, (error, link) => {
          if (error) reject(error);
          else resolve(link);
        });
      });

      return link;
    } catch (error) {
      lastError = error;

      // อย่าลองข้อผิดพลาดบางอย่างใหม่
      if (error.code === 'authentication_failure' ||
          error.code === 'invalid_amount') {
        throw error;
      }

      // การถ่วงน้ำหนัก: 1 วินาที, 2 วินาที, 4 วินาที
      const delay = Math.pow(2, i) * 1000;
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }

  throw lastError;
}

การทดสอบ

โหมดทดสอบ

ใช้คีย์ API ทดสอบ:

const omise = require('omise')({
  secretKey: 'skey_test_xxx'  // คีย์ทดสอบ
});

บัตรทดสอบ

// ทดสอบการชำระเงินสำเร็จ
const testCardSuccess = {
  number: '4242424242424242',
  name: 'ผู้ใช้ทดสอบ',
  expiration_month: 1,
  expiration_year: 2026,
  security_code: '123'
};

// ทดสอบการชำระเงินล้มเหลว
const testCardFailed = {
  number: '4000000000000002',
  name: 'ผู้ใช้ทดสอบ',
  expiration_month: 1,
  expiration_year: 2026,
  security_code: '123'
};

คำถามที่พบบ่อย

ถาม: สามารถสร้างลิงก์โดยไม่มีจำนวนเงิน (ให้ลูกค้าตัดสินใจ) ได้หรือไม่? ตอบ: ไม่ API ต้องมีจำนวนเงินคงที่ สำหรับจำนวนเงินที่ยืดหยุ่น ให้ใช้อินเทอร์เฟซแดชบอร์ด

ถาม: สามารถลบลิงก์การชำระเงินได้หรือไม่? ตอบ: ไม่สามารถลบผ่าน API ได้ สามารถปิดใช้งานได้เท่านั้น

ถาม: ลิงก์มี rate limiting หรือไม่? ตอบ: 60 ส่วนขยาย/นาทีต่อคีย์ API และ 1000 ส่วนขยาย/ชั่วโมง

ถาม: สามารถอัปเดตจำนวนเงิน ได้หรือไม่? ตอบ: ไม่ สร้างลิงก์ใหม่ด้วยจำนวนเงินที่อัปเดต

ขั้นตอนต่อไป

• ภาพรวมลิงก์การชำระเงิน - เรียนรู้เกี่ยวกับคุณสมบัติลิงก์การชำระเงิน
• สร้างลิงก์ - สร้างลิงก์ผ่านแดชบอร์ด
• คำแนะนำ Webhooks - ตั้งค่าการแจ้งเตือน webhook
• อ้างอิง API - เอกสาร API ที่สมบูรณ์

ทรัพยากรเพิ่มเติม

• ไลบรารี Omise - SDK ไลบรารี
• คำแนะนำการทดสอบ - กลยุทธ์การทดสอบ
• วิธีปฏิบัติด้านความปลอดภัย - ส่วนขยายปลอดภัย
• คำแนะนำแดชบอร์ด - การใช้แดชบอร์ด

---

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