ภาพรวม (Overview)

ยินดีต้อนรับสู่ Noahland API เราออกแบบ API ในรูปแบบ RESTful สื่อสารด้วยรูปแบบ JSON และใช้มาตรฐาน HTTP Status Codes เพื่อให้นักพัฒนาสามารถเชื่อมต่อระบบรับชำระเงินได้อย่างรวดเร็วและปลอดภัยที่สุด

Base URLs

ระบบของเราแยก Environment ระหว่างระบบทดสอบ (Test Mode) และระบบใช้งานจริง (Live Mode) อย่างชัดเจน โปรดตรวจสอบ URL ที่คุณใช้เรียกให้ถูกต้อง

Sandbox https://api-sandbox.noahland.co.th/v1/

Production https://api.noahland.co.th/v1/

รูปแบบข้อมูล (Data Format)

Noahland API รับข้อมูล (Request) ในรูปแบบ application/x-www-form-urlencoded และส่งข้อมูลกลับ (Response) ในรูปแบบ application/json เสมอ รวมถึงกรณีที่เกิด Error ด้วย

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

Noahland ใช้ระบบ API Keys เพื่อระบุตัวตนและสิทธิ์ในการเข้าถึงทรัพยากรต่างๆ ของคุณ

ประเภทของ API Keys

เก็บเป็นความลับ

Secret Key

ใช้ฝั่ง Server-side (Backend) เท่านั้น สามารถทำได้ทุกอย่าง เช่น ตัดบัตร, คืนเงิน, ลบข้อมูล

sk_test_... sk_live_...

ใช้บนหน้าเว็บได้

Public Key

ใช้ฝั่ง Client-side (Frontend/App) ใช้สำหรับแปลงข้อมูลบัตรเป็น Token เท่านั้น (Tokenization)

pk_test_... pk_live_...

การใช้งานผ่าน HTTP Header

คุณต้องแนบ Key ผ่าน Header Authorization: Bearer {YOUR_API_KEY} ในทุกๆ Request

ตัวอย่างการแนบ Header

curl -X GET https://api.noahland.co.th/v1/account \
  -H "Authorization: Bearer sk_test_01abc23def456ghi789jkl" \
  -H "Noahland-Version: 2024-01-01"
                        

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

Noahland ใช้ HTTP Status Code สากลเพื่อบอกผลลัพธ์ของ Request และส่ง Error Object ที่เป็น JSON กลับมาเพื่อให้อ่านสาเหตุได้ง่าย

HTTP Status Codes

Status	ความหมาย (Description)
200 - OK	ทำงานสำเร็จ
400 - Bad Request	พารามิเตอร์ผิดพลาด, ข้อมูลไม่ครบ
401 - Unauthorized	API Key ไม่ถูกต้อง
402 - Request Failed	พารามิเตอร์ถูก แต่การทำธุรกรรมล้มเหลว (เช่น บัตรถูกปฏิเสธ)
404 - Not Found	ไม่พบข้อมูลที่ค้นหา (เช่น Charge ID ไม่ถูกต้อง)
500 - Server Error	ข้อผิดพลาดจากฝั่งเซิร์ฟเวอร์ Noahland

รูปแบบ Error Object (JSON)

Example 402 Card Declined

{ "object": "error", "location": "https://api.noahland.co.th/v1/charges", "code": "card_declined", "message": "The card was declined by the issuer.", "charge_id": "ch_test_5x1y2z3a4b" }

Idempotency (ป้องกันคำขอซ้ำ)

ป้องกันปัญหา "ลูกค้าถูกตัดเงินซ้ำซ้อน" ในกรณีที่เน็ตหลุดหรือระบบ Timeout โดยการส่ง Header Idempotency-Key มาพร้อมกับ Request

คำแนะนำ: สร้างค่า String แบบสุ่ม (เช่น UUID) สำหรับแต่ละธุรกรรม หากคุณส่ง Request ที่มี `Idempotency-Key` ตัวเดิมเข้ามาภายใน 24 ชั่วโมง ระบบ Noahland จะไม่สร้างรายการใหม่ แต่จะส่ง Response ของรายการเดิมกลับไปทันที

การใช้งาน Idempotency-Key

curl -X POST https://api.noahland.co.th/v1/charges \
  -H "Authorization: Bearer sk_test_12345" \
  -H "Idempotency-Key: a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -d "amount=50000" \
  -d "currency=thb"
                        

Charges

Core API

API นี้ใช้สำหรับการสร้างรายการตัดเงินจากบัตรเครดิต, พร้อมเพย์, บัญชีธนาคาร หรือช่องทางอื่นๆ (Charge Object)

Create a Charge (สร้างรายการ)

POST /v1/charges

Parameters

Attribute	Description
amount integer REQUIRED	จำนวนเงินที่ต้องการเรียกเก็บ หน่วยเป็นสตางค์ สำหรับสกุลเงิน THB (เช่น `10000` = 100.00 บาท) ขั้นต่ำคือ 20.00 บาท (2000)
currency string REQUIRED	ตัวย่อสกุลเงิน 3 ตัวอักษรตามมาตรฐาน ISO 4217 เช่น `thb`, `usd`, `jpy`
card string OPTIONAL*	Token ของบัตรเครดิตที่ได้จากการทำ Tokenization ฝั่ง Frontend (รูปแบบ: `tok_...`) * จำเป็นต้องส่งหากไม่ได้ระบุ `customer` หรือ `source`
customer string OPTIONAL*	ID ของลูกค้าที่มีบัตรผูกไว้อยู่แล้ว (รูปแบบ: `cus_...`) เหมาะสำหรับทำ One-Click Checkout
description string OPTIONAL	คำอธิบายรายการ (ไม่เกิน 255 ตัวอักษร) จะไปแสดงในหน้า Dashboard ของร้านค้า
capture boolean OPTIONAL	ค่าเริ่มต้นคือ `true` (ตัดเงินทันที) หากตั้งเป็น `false` ระบบจะแค่กันวงเงินไว้ (Authorize Only) และคุณต้องเรียก API Capture อีกครั้งเพื่อตัดเงินจริง

Request (cURL)

curl -X POST https://api.noahland.co.th/v1/charges \
  -u sk_test_01ab2c3d4e5f6g7h8i9j: \
  -d "amount=150000" \
  -d "currency=thb" \
  -d "card=tok_test_9z8y7x6w5v4u3t2s1r" \
  -d "description=Order #12345 Premium Pack"
                            

Response (200 OK) JSON

{ "object": "charge", "id": "ch_test_5a6b7c8d9e0f", "livemode": false, "amount": 150000, "currency": "thb", "status": "successful", "captured": true, "authorized": true, "reversed": false, "paid": true, "fee": 5350, // ค่าธรรมเนียมรวม VAT 53.50 บาท "net": 144650, // ยอดรับสุทธิ 1,446.50 บาท "description": "Order #12345 Premium Pack", "card": { "object": "card", "id": "card_test_112233", "brand": "Visa", "last_digits": "4242", "name": "SOMCHAI JAIKAEW", "bank": "KASIKORNBANK" }, "created_at": "2024-10-24T10:15:30Z" }

Customers

ใช้บันทึกข้อมูลลูกค้า และ ผูกบัตรเครดิต (Save Card) ไว้กับลูกค้าคนนั้นๆ ทำให้ในการซื้อครั้งถัดไป ลูกค้าไม่จำเป็นต้องกรอกข้อมูลบัตรใหม่ (ใช้ Customer ID ตัดเงินได้เลย)

Create a Customer (สร้างลูกค้าใหม่)

POST /v1/customers

Parameters

Attribute	Description
email string OPTIONAL	อีเมลของลูกค้า ใช้สำหรับค้นหาในระบบ Dashboard
description string OPTIONAL	คำอธิบาย เช่น ชื่อ นามสกุล หรือ User ID จากระบบของคุณ
card string OPTIONAL	Token ของบัตร (`tok_...`) ที่ต้องการบันทึกผูกไว้กับลูกค้ารายนี้

Create Customer Request

curl -X POST https://api.noahland.co.th/v1/customers \
  -u sk_test_01ab2c3d4e5f6g7h8i9j: \
  -d "email=customer@company.com" \
  -d "description=User ID: 998877" \
  -d "card=tok_test_1a2b3c4d5e"
                        

Refunds

คืนเงินให้ลูกค้า (Refund) สามารถทำได้ทั้งแบบ คืนเต็มจำนวน (Full Refund) หรือ คืนบางส่วน (Partial Refund) ยอดเงินจะถูกโอนกลับไปยังบัตรเครดิตของลูกค้าภายใน 7-14 วันทำการ

Create a Refund

POST /v1/charges/{charge_id}/refunds

Parameters

Attribute	Description
amount integer OPTIONAL	จำนวนเงินที่ต้องการคืน (หน่วยเป็นสตางค์) หากไม่ระบุ ระบบจะทำการคืนเงินเต็มจำนวน (Full Refund) อัตโนมัติ

Partial Refund Request (คืนแค่ 500 บาท)

curl -X POST https://api.noahland.co.th/v1/charges/ch_test_5a6b7c8d9e0f/refunds \
  -u sk_test_01ab2c3d4e5f6g7h8i9j: \
  -d "amount=50000"
                        

Webhooks (เหตุการณ์แบบ Real-time)

แทนที่คุณจะต้องยิง API มาเช็คสถานะเรื่อยๆ (Polling) ระบบ Webhook จะส่ง HTTP POST ไปหา Server ของคุณทันทีที่มีเหตุการณ์สำคัญเกิดขึ้น (เช่น ตัดบัตรสำเร็จ, ลูกค้าโอนพร้อมเพย์สำเร็จ)

Events ที่พบบ่อย (Common Events)

charge.successful - เมื่อชำระเงินสำเร็จ (จ่ายของให้ลูกค้าได้เลย)
charge.failed - เมื่อชำระเงินไม่สำเร็จ (บัตรถูกปฏิเสธ)
refund.successful - เมื่อดำเนินการคืนเงินให้ลูกค้าสำเร็จ

ความปลอดภัย (Webhook Signatures)

เพื่อป้องกัน Hacker แกล้งส่ง Request ปลอมไปหา Server ของคุณ Noahland จะแนบ Header Noahland-Signature ไปด้วยทุกครั้ง คุณต้องนำค่านี้ไป Validate กับ Webhook Secret Key ของคุณ

Example Webhook Payload (JSON)

{
  "object": "event",
  "id": "evnt_live_1a2b3c",
  "livemode": true,
  "type": "charge.successful",
  "created_at": "2024-10-24T10:15:35Z",
  "data": {
    "object": "charge",
    "id": "ch_live_5a6b7c8d9e0f",
    "amount": 150000,
    "status": "successful",
    "metadata": {
        "order_id": "12345"
    }
  }
}
                        