เอกสาร API

ยินดีต้อนรับสู่คู่มือนักพัฒนาของ Elixopay! ออกแบบมาเพื่อให้คุณผสานระบบการชำระเงินที่ปลอดภัยและเสถียรเข้ากับแพลตฟอร์มของคุณได้อย่างรวดเร็ว API ของเราใช้สถาปัตยกรรม REST ที่ได้มาตรฐาน ตอบกลับเป็น JSON เสมอ และใช้ HTTP Status Codes อย่างถูกต้อง

การยืนยันตัวตน (Authentication)

Elixopay API ใช้ API Keys ในการยืนยันตัวตน คุณสามารถจัดการและสร้างคีย์ใหม่ได้ที่แดชบอร์ดนักพัฒนา

คำเตือนความปลอดภัย

ห้ามเปิดเผย Secret API Key ของคุณในที่สาธารณะ เช่น ในฝั่ง Client-side (เบราว์เซอร์, แอปมือถือ) หรือใน GitHub repository การประมวลผลการชำระเงินทั้งหมดต้องทำผ่านเซิร์ฟเวอร์ (Backend) เท่านั้น

การร้องขอทั้งหมดต้องส่งคีย์ผ่าน Authorization Header ในรูปแบบ Bearer token:

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxx

คู่มือทดลองเชื่อมต่อ (Sandbox Guide)

สำหรับนักพัฒนาที่ต้องการนำ Elixopay ไปทดสอบเชื่อมต่อกับระบบของตัวเอง สามารถทำตามขั้นตอนทั้ง 5 นี้ได้เลยครับ

1. ขอรับ API Keys (Test Mode)

สมัครสมาชิกและเข้าสู่ Developer Dashboard ไปที่เมนู API Keys เพื่อคัดลอกคีย์ทดสอบที่ขึ้นต้นด้วย sk_test_... (การทำรายการด้วยคีย์นี้จะไม่เกิดการตัดเงินจริง)

2. ยิงคำสั่งสร้างการชำระเงิน (Create Payment)

เมื่อลูกค้ากดจ่ายเงิน ให้ Backend ของคุณยิง POST /api/v1/payments มาที่ Elixopay พร้อมแนบคีย์ sk_test_... (ตามตัวอย่างในหัวข้อก่อนหน้า)

3. พาผู้ใช้ไปหน้าชำระเงิน (Redirect)

หลังจากยิง API สำเร็จ Elixopay จะตอบกลับมาเป็น checkout_url ระบบของคุณแค่ต้อง Redirect ลูกค้าไปที่ลิงก์นั้น เพื่อให้ลูกค้ากรอกข้อมูลบัตรหรือแสกน QR ทดสอบ

4. รับรู้ผลการชำระเงิน (Check Status / Webhooks)

เมื่อรายการทดสอบเสร็จสิ้น Elixopay จะเด้งลูกค้ากลับไปยัง return_url ที่คุณตั้งไว้ และจะยิง Webhook แจ้งเตือนสถานะสำเร็จไปยังระบบหลังบ้านของคุณ

5. เปลี่ยนเป็นโหมดใช้งานจริง (Go Live)

เมื่อทดสอบจนมั่นใจแล้ว ให้เปลี่ยน API Key ในโค้ดจาก sk_test_... เป็น sk_live_... เพื่อพร้อมรับชำระเงินจริงจากลูกค้าได้ทันที!

บัตรเครดิตสำหรับทดสอบ

ใช้เลขบัตรเหล่านี้สำหรับทดสอบในหน้า Checkout:

ชำระเงินสำเร็จ: 4242 4242 4242 4242
ชำระเงินถูกปฏิเสธ: 4000 0000 0000 0002
* วันหมดอายุ: (เดือน/ปี ใดก็ได้ในอนาคต) | CVV: 123 หรือเลข 3 หลักใดก็ได้

สร้างการชำระเงิน (Create Payment)

ใช้ Endpoint นี้เพื่อสร้างเซสชันการชำระเงินใหม่สำหรับลูกค้าของคุณ ระบบจะส่งกลับลิงก์สำหรับชำระเงิน (Checkout URL) ที่คุณสามารถพาลูกค้าไปทำรายการต่อได้

POST /api/v1/payments

พารามิเตอร์ของ Request (Body)

พารามิเตอร์ คำอธิบาย
amount numberRequired จำนวนเงินที่ต้องการเรียกเก็บ (เช่น 1000.00 สำหรับหนึ่งพันบาท)
currency stringRequired สกุลเงินที่ใช้ทำรายการ ปัจจุบันรองรับเฉพาะ THB
description string รายละเอียดหรือชื่อสินค้าที่จะแสดงในหน้าชำระเงิน
reference_id stringRequired รหัสอ้างอิงรายการจากระบบของคุณ (ต้องไม่ซ้ำกันในแต่ละรายการ)
return_url stringRequired URL ที่คุณต้องการให้ระบบพาลูกค้ากลับไป หลังจากหน้าชำระเงินดำเนินการเสร็จสิ้น
metadata object ข้อมูลเพิ่มเติมแบบ Key-Value (สูงสุด 10 keys) ที่คุณต้องการแนบไว้กับรายการนี้

พารามิเตอร์ของ Response

พารามิเตอร์ คำอธิบาย
id string รหัสอ้างอิงรายการของ Elixopay (เริ่มต้นด้วย pay_) นำไปใช้เช็คสถานะต่อไป
checkout_url string ลิงก์หน้าชำระเงินที่คุณต้องนำไป Redirect ลูกค้าย้ายไปหน้าชำระเงิน
status string สถานะของการชำระเงิน (เริ่มต้นด้วย pending เสมอสำหรับการสร้างรายการใหม่)

ตัวอย่าง Request

curl -X POST https://api.elixopay.com/api/v1/payments \ -H "Authorization: Bearer sk_live_YOUR_SECRET_KEY" \ -H "Content-Type: application/json" \ -d '{ "amount": 1000.00, "currency": "THB", "description": "Order #EX-12345", "reference_id": "EX-12345", "return_url": "https://yourwebsite.com/checkout/success", "metadata": { "customer_id": "CUST-987" } }'
const axios = require('axios'); axios.post('https://api.elixopay.com/api/v1/payments', { amount: 1000.00, currency: 'THB', description: 'Order #EX-12345', reference_id: 'EX-12345', return_url: 'https://yourwebsite.com/checkout/success', metadata: { customer_id: 'CUST-987' } }, { headers: { 'Authorization': 'Bearer sk_live_YOUR_SECRET_KEY', 'Content-Type': 'application/json' } }).then(res => console.log(res.data));
import requests url = "https://api.elixopay.com/api/v1/payments" headers = { "Authorization": "Bearer sk_live_YOUR_SECRET_KEY", "Content-Type": "application/json" } data = { "amount": 1000.00, "currency": "THB", "description": "Order #EX-12345", "reference_id": "EX-12345", "return_url": "https://yourwebsite.com/checkout/success", "metadata": { "customer_id": "CUST-987" } } response = requests.post(url, json=data, headers=headers) print(response.json())
$ch = curl_init('https://api.elixopay.com/api/v1/payments'); $payload = json_encode([ 'amount' => 1000.00, 'currency' => 'THB', 'description' => 'Order #EX-12345', 'reference_id' => 'EX-12345', 'return_url' => 'https://yourwebsite.com/checkout/success', 'metadata' => ['customer_id' => 'CUST-987'] ]); curl_setopt($ch, CURLOPT_POSTFIELDS, $payload); curl_setopt($ch, CURLOPT_HTTPHEADER, [ 'Authorization: Bearer sk_live_YOUR_SECRET_KEY', 'Content-Type: application/json' ]); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); $response = curl_exec($ch);

ตัวอย่าง Response (200 OK)

{ "id": "pay_xxxxxxxxxxxxxx", "object": "payment", "amount": 1000.00, "currency": "THB", "status": "pending", "checkout_url": "https://checkout.elixopay.com/c/pay_xxxxxxxxxxxxxx", "created_at": 1709280000 }

ตรวจสอบสถานะ (Check Status)

ดึงข้อมูลรายละเอียดและสถานะล่าสุดของรายการชำระเงินด้วย Payment ID

GET /api/v1/payments/:id

พารามิเตอร์ของ URL

พารามิเตอร์ คำอธิบาย
id stringRequired รหัส Payment ID ที่ได้รับตอนสร้างรายการ (pay_xxxxxxxxxxxxxx)

พารามิเตอร์ของ Response

พารามิเตอร์ คำอธิบาย
id string รหัส Payment ID ของรายการนี้ (เริ่มด้วย pay_)
object string ประเภทของออบเจ็กต์ (จะเป็น payment เสมอ)
amount number จำนวนเงินของรายการ
currency string สกุลเงินของรายการ (เช่น THB)
status string สถานะปัจจุบันของการชำระเงิน (pending, successful, failed)
paid_at timestamp เวลาที่รายการชำระเงินสำเร็จ (เป็น Unix Timestamp) จะเป็น null หากยังไม่สำเร็จ
payment_method string ช่องทางที่ลูกค้าใช้ชำระเงิน (เช่น promptpay, credit_card, truemoney)
reference_id string รหัสอ้างอิงรายการจากระบบของคุณ

ตัวอย่าง Request

curl -X GET https://api.elixopay.com/api/v1/payments/pay_xxxxxxxxxxxxxx \ -H "Authorization: Bearer sk_live_YOUR_SECRET_KEY"
const axios = require('axios'); axios.get('https://api.elixopay.com/api/v1/payments/pay_xxxxxxxxxxxxxx', { headers: { 'Authorization': 'Bearer sk_live_YOUR_SECRET_KEY' } }).then(res => console.log(res.data));
import requests url = "https://api.elixopay.com/api/v1/payments/pay_xxxxxxxxxxxxxx" headers = { "Authorization": "Bearer sk_live_YOUR_SECRET_KEY" } response = requests.get(url, headers=headers) print(response.json())
$ch = curl_init('https://api.elixopay.com/api/v1/payments/pay_xxxxxxxxxxxxxx'); curl_setopt($ch, CURLOPT_HTTPHEADER, [ 'Authorization: Bearer sk_live_YOUR_SECRET_KEY' ]); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); $response = curl_exec($ch);

ตัวอย่าง Response (200 OK)

{ "id": "pay_xxxxxxxxxxxxxx", "object": "payment", "amount": 1000.00, "currency": "THB", "status": "successful", "paid_at": 1709280350, "payment_method": "promptpay", "reference_id": "EX-12345" }

การคืนเงิน (Refunds)

ใช้ Endpoint นี้เพื่อทำการคืนเงิน (Refund) ให้กับลูกค้า หลังจากที่ชำระเงินสำเร็จ (Completed) สามารถระบุจำนวนเงินคืนบางส่วน หรือคืนเต็มจำนวนก็ได้ ยอดเงินจะถูกหักจากกระเป๋าเงิน (Wallet) ของคุณ

POST /api/v1/payments/:id/refund

พารามิเตอร์ของ Request (Body)

พารามิเตอร์ คำอธิบาย
id number (URL)Required ไอดีของการชำระเงินที่ต้องการคืนเงิน (Transaction ID) ส่งผ่าน URL path
amount number จำนวนเงินที่ต้องการคืน หากไม่ระบุจะเป็นการคืนเต็มจำนวน
reason string เหตุผลในการคืนเงิน (ไม่บังคับ)

พารามิเตอร์ของ Response

พารามิเตอร์ คำอธิบาย
success boolean ระบุว่าการคืนเงินสำเร็จหรือไม่
data.id number รหัสรายการคืนเงินที่ถูกสร้างขึ้น
data.refundedAmount number จำนวนเงินที่คืนให้ลูกค้า
data.originalTransactionId number รหัสรายการชำระเงินต้นทาง

ตัวอย่าง Request

curl -X POST https://api.elixopay.com/api/v1/payments/999/refund \ -H "Authorization: Bearer sk_test_YOUR_SECRET_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: ref_12345" \ -d '{ "amount": 500.00, "reason": "Customer requested refund" }'
const axios = require('axios'); axios.post('https://api.elixopay.com/api/v1/payments/999/refund', { amount: 500.00, reason: 'Customer requested refund' }, { headers: { 'Authorization': 'Bearer sk_test_YOUR_SECRET_KEY', 'Content-Type': 'application/json', 'Idempotency-Key': 'ref_12345' } }).then(res => console.log(res.data));
import requests url = "https://api.elixopay.com/api/v1/payments/999/refund" headers = { "Authorization": "Bearer sk_test_YOUR_SECRET_KEY", "Content-Type": "application/json", "Idempotency-Key": "ref_12345" } data = { "amount": 500.00, "reason": "Customer requested refund" } response = requests.post(url, json=data, headers=headers) print(response.json())
$ch = curl_init('https://api.elixopay.com/api/v1/payments/999/refund'); $payload = json_encode([ 'amount' => 500.00, 'reason' => 'Customer requested refund' ]); curl_setopt($ch, CURLOPT_POSTFIELDS, $payload); curl_setopt($ch, CURLOPT_HTTPHEADER, [ 'Authorization: Bearer sk_test_YOUR_SECRET_KEY', 'Content-Type: application/json', 'Idempotency-Key: ref_12345' ]); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); $response = curl_exec($ch);

ตัวอย่าง Response (200 OK)

{ "success": true, "message": "Refund processed successfully", "data": { "id": 165, "refundedAmount": 500.00, "originalTransactionId": 999, "status": "COMPLETED" } }

ระบบสมาชิก (Subscriptions)

API จัดการระบบ Subscription ซึ่งอนุญาตให้คุณสร้างสินค้ารายเดือน (Products), แผนราคา (Prices) และพ่วงผูกลูกค้าเข้ากับแพ็กเกจ เพื่อให้เกิดการเรียกเก็บเงินอัตโนมัติ

POST /api/v1/billing/products

สร้างสินค้าเพื่อใช้ในการสมัครสมาชิก (เช่น "Premium Plan")

พารามิเตอร์ Create Product

พารามิเตอร์ คำอธิบาย
name stringRequired ชื่อสินค้าหรือแพลน (เช่น "Premium Plan", "Basic Plan")
POST /api/v1/billing/prices

สร้างราคาและรอบบิล (เช่น เดือนละ 500 บาท) ผูกกับ Product ID

พารามิเตอร์ Create Price

พารามิเตอร์ คำอธิบาย
productId stringRequired รหัส Product ที่ต้องการผูกราคา
amount numberRequired จำนวนเงินต่อรอบบิล (เช่น 500.00 บาท)
interval stringRequired รอบการเก็บเงิน (month, year)
POST /api/v1/billing/customers

ลงทะเบียนลูกค้าใหม่เข้าสู่ระบบ Billing

POST /api/v1/billing/subscriptions

สมัครสมาชิกลูกค้า (พ่วง Customer ID กับ Price ID)

พารามิเตอร์ Create Subscription

พารามิเตอร์ คำอธิบาย
customerId stringRequired รหัสลูกค้าที่ต้องการสมัครสมาชิก
priceId stringRequired รหัสราคา (Price ID) ที่ต้องการผูก

ตัวอย่าง Request

curl -X POST https://api.elixopay.com/api/v1/billing/subscriptions \ -H "Authorization: Bearer sk_test_YOUR_SECRET_KEY" \ -H "Content-Type: application/json" \ -d '{ "customerId": "cus_123", "priceId": "price_456" }'
const axios = require('axios'); axios.post('https://api.elixopay.com/api/v1/billing/subscriptions', { customerId: 'cus_123', priceId: 'price_456' }, { headers: { 'Authorization': 'Bearer sk_test_YOUR_SECRET_KEY', 'Content-Type': 'application/json' } }).then(res => console.log(res.data));
import requests url = "https://api.elixopay.com/api/v1/billing/subscriptions" headers = { "Authorization": "Bearer sk_test_YOUR_SECRET_KEY", "Content-Type": "application/json" } data = { "customerId": "cus_123", "priceId": "price_456" } response = requests.post(url, json=data, headers=headers) print(response.json())
$ch = curl_init('https://api.elixopay.com/api/v1/billing/subscriptions'); $payload = json_encode([ 'customerId' => 'cus_123', 'priceId' => 'price_456' ]); curl_setopt($ch, CURLOPT_POSTFIELDS, $payload); curl_setopt($ch, CURLOPT_HTTPHEADER, [ 'Authorization: Bearer sk_test_YOUR_SECRET_KEY', 'Content-Type: application/json' ]); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); $response = curl_exec($ch);

ตัวอย่าง Response (201 Created)

{ "success": true, "data": { "subscription": { "id": "sub_789xyz", "status": "active", "currentPeriodEnd": "2026-04-01T00:00:00.000Z" } } }

สร้างการถอนเงิน (Payouts)

ใช้ Endpoint นี้เพื่อสร้างคำสั่งถอนเงินออกจากกระเป๋าเงิน (Wallet) ยอดเงินจะถูกโอนเข้าบัญชีธนาคารที่คุณผูกไว้ในระบบ

POST /api/v1/wallet/withdraw

พารามิเตอร์ของ Request (Body)

พารามิเตอร์ คำอธิบาย
amount numberRequired จำนวนเงินที่ต้องการถอน (ต้องมียอดคงเหลือเพียงพอรวมค่าธรรมเนียม) ตัวอย่างเช่น 500.00

พารามิเตอร์ของ Response

พารามิเตอร์ คำอธิบาย
success boolean ระบุว่าการส่งคำขอสำเร็จหรือไม่
transaction object ออบเจ็กต์ข้อมูลรายการถอนเงินที่ถูกสร้างขึ้นในสถานะ 'PENDING'

ตัวอย่าง Request

curl -X POST https://api.elixopay.com/api/v1/wallet/withdraw \ -H "Authorization: Bearer sk_live_YOUR_SECRET_KEY" \ -H "Content-Type: application/json" \ -d '{ "amount": 500.00 }'
const axios = require('axios'); axios.post('https://api.elixopay.com/api/v1/wallet/withdraw', { amount: 500.00 }, { headers: { 'Authorization': 'Bearer sk_live_YOUR_SECRET_KEY', 'Content-Type': 'application/json' } }).then(res => console.log(res.data));
import requests url = "https://api.elixopay.com/api/v1/wallet/withdraw" headers = { "Authorization": "Bearer sk_live_YOUR_SECRET_KEY", "Content-Type": "application/json" } data = { "amount": 500.00 } response = requests.post(url, json=data, headers=headers) print(response.json())
$ch = curl_init('https://api.elixopay.com/api/v1/wallet/withdraw'); $payload = json_encode([ 'amount' => 500.00 ]); curl_setopt($ch, CURLOPT_POSTFIELDS, $payload); curl_setopt($ch, CURLOPT_HTTPHEADER, [ 'Authorization: Bearer sk_live_YOUR_SECRET_KEY', 'Content-Type: application/json' ]); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); $response = curl_exec($ch);

ตัวอย่าง Response (201 Created)

{ "success": true, "message": "Withdrawal requested successfully", "data": { "transaction": { "id": 164, "amount": 599.00, "status": "PENDING", "reference": "WD-16440590", "fee": "99.00" } } }

Webhooks (รับการแจ้งเตือน)

Webhooks คือวิธีการที่ Elixopay ส่งการแจ้งเตือนแบบเรียลไทม์ (HTTP POST) ไปยังเซิร์ฟเวอร์ของคุณเมื่อเกิดเหตุการณ์ต่างๆ เช่น ลูกค้าชำระเงินสำเร็จแล้ว

Best Practice

เพื่อความปลอดภัยสูงสุด คุณควรยืนยันความถูกต้องของ Webhook ทุกครั้งโดยตรวจสอบลายเซ็น (Signature) เข้ารหัสผ่าน HMAC-SHA256 ที่แนบมาใน Header X-Elixopay-Signature

โครงสร้าง Event Payload พารามิเตอร์

พารามิเตอร์ คำอธิบาย
event string ประเภทของ Event ที่เกิดขึ้น (เช่น payment.successful, payment.failed)
created_at timestamp เวลาที่เกิด Event แจ้งเตือน (Unix Timestamp)
data object ออบเจ็กต์ข้อมูลที่อัปเดต เช่น ข้อมูลของ Payment ที่สำเร็จ (มีโครงสร้างเดียวกับ Response การเช็คสถานะ)

ตัวอย่าง Event Payload (`payment.successful`)

{ "event": "payment.successful", "created_at": 1709280350, "data": { "id": "pay_xxxxxxxxxxxxxx", "object": "payment", "amount": 1000.00, "currency": "THB", "status": "successful", "reference_id": "EX-12345" } }

ดาวน์โหลดทรัพยากรสำหรับนักพัฒนา

ดาวน์โหลดไฟล์และเครื่องมือที่จะช่วยให้การเชื่อมต่อกับ Elixopay ของคุณง่ายและรวดเร็วยิ่งขึ้น

Postman Collection

รวบรวม API Endpoints ทั้งหมดไว้ในที่เดียว เพื่อการทดสอบที่รวดเร็วไม่ต้องตั้งค่าเอง

ดาวน์โหลดไฟล์

OpenAPI Specification

ไฟล์ YAML มาตรฐานสำหรับใช้กับ Swagger หรือเครื่องมือสร้าง Code Generator ต่างๆ

ดาวน์โหลดไฟล์

API Reference (PDF)

คู่มือฉบับสมบูรณ์ในรูปแบบ PDF สำหรับการอ่านแบบออฟไลน์หรือพิมพ์ออกมาอ้างอิง

Download File

Elixopay Developer Tools v1.0