เอกสาร Public API

เวอร์ชัน: 1.1.0 อัปเดตล่าสุด: 2025-12-24

สภาพแวดล้อม

สภาพแวดล้อม	Base URL	คำอธิบาย
Production	`https://gateway.facaiqq.com/v1`	ธุรกรรมจริง, การชำระเงินจริง
Sandbox	`https://gateway.facaiqq.com/v1`	ธุรกรรมทดสอบ (เฉพาะ merchant ประเภท sandbox)

ภาพรวม

Public API ช่วยให้ร้านค้าสามารถเชื่อมต่อระบบชำระเงินเข้ากับแอปพลิเคชันของตน คำขอ API ทั้งหมดต้องมีการยืนยันตัวตนด้วย HMAC-SHA256

Production vs Sandbox

ประเภท merchant กำหนดการเส้นทางของธุรกรรม:

Production Merchant: ธุรกรรมเงินจริงผ่านผู้ให้บริการชำระเงิน
Sandbox Merchant: ธุรกรรมจำลองสำหรับทดสอบ ไม่มีการประมวลผลจริง

การยืนยันตัวตน

คำขอ API ทั้งหมดต้องมี headers ต่อไปนี้:

Header	จำเป็น	คำอธิบาย
`X-API-Key`	ใช่	API key ของร้านค้า (64 ตัวอักษร)
`X-Signature`	ใช่	ลายเซ็น HMAC-SHA256 ของคำขอ
`X-Timestamp`	ใช่	Unix timestamp (วินาทีตั้งแต่ epoch)
`Content-Type`	ใช่	`application/json`

การสร้างลายเซ็น

ลายเซ็นคำนวณโดยใช้ HMAC-SHA256 กับ Secret Key ของคุณ:

Signature = HMAC-SHA256(SignatureData, SecretKey)
SignatureData = METHOD|PATH|TIMESTAMP|BODY

ตัวอย่าง (POST request):

SignatureData = "POST|/v1/payments/deposit|1702400000|{\"amount\":100.00,\"currency\":\"THB\",\"reference_id\":\"ORDER-001\"}"

ตัวอย่าง (GET request):

SignatureData = "GET|/v1/payments/pay_abc123|1702400000"

ตัวอย่างโค้ด

PythonNode.jsPHPGo

python

import hmac
import hashlib
import time
import json
import requests

api_key = "your_api_key"
secret_key = "your_secret_key"
base_url = "https://gateway.facaiqq.com"

def create_signature(method, path, timestamp, body=""):
    # สำคัญ: path ต้องเป็น full HTTP path (เช่น /v1/payments/deposit)
    data = f"{method}|{path}|{timestamp}"
    if body:
        data += f"|{body}"
    return hmac.new(
        secret_key.encode(),
        data.encode(),
        hashlib.sha256
    ).hexdigest()

def make_request(method, path, body=None):
    timestamp = str(int(time.time()))
    body_str = json.dumps(body) if body else ""
    signature = create_signature(method, path, timestamp, body_str)

    headers = {
        "X-API-Key": api_key,
        "X-Signature": signature,
        "X-Timestamp": timestamp,
        "Content-Type": "application/json"
    }

    url = base_url + path
    if method == "POST":
        return requests.post(url, headers=headers, json=body)
    else:
        return requests.get(url, headers=headers)

# สร้างรายการฝากเงิน - ใช้ full path รวม /v1
response = make_request("POST", "/v1/payments/deposit", {
    "amount": 1000.00,
    "currency": "THB",
    "reference_id": "ORD888888888",
    "bank_code": "004",
    "bank_account_no": "1234567890",
    "bank_account_name": "ทดสอบ ทดสอบ",
    "webhook_url": "https://example.com/path/to/your/webhook"
})
print(response.json())

javascript

const crypto = require("crypto");
const axios = require("axios");

const apiKey = "your_api_key";
const secretKey = "your_secret_key";
const baseUrl = "https://gateway.facaiqq.com";

function createSignature(method, path, timestamp, body = "") {
  // สำคัญ: path ต้องเป็น full HTTP path (เช่น /v1/payments/deposit)
  let data = `${method}|${path}|${timestamp}`;
  if (body) {
    data += `|${body}`;
  }
  return crypto.createHmac("sha256", secretKey).update(data).digest("hex");
}

async function makeRequest(method, path, body = null) {
  const timestamp = Math.floor(Date.now() / 1000).toString();
  const bodyStr = body ? JSON.stringify(body) : "";
  const signature = createSignature(method, path, timestamp, bodyStr);

  const headers = {
    "X-API-Key": apiKey,
    "X-Signature": signature,
    "X-Timestamp": timestamp,
    "Content-Type": "application/json",
  };

  const url = baseUrl + path;
  if (method === "POST") {
    return axios.post(url, body, { headers });
  } else {
    return axios.get(url, { headers });
  }
}

// สร้างรายการฝากเงิน - ใช้ full path รวม /v1
makeRequest("POST", "/v1/payments/deposit", {
  amount: 1000.0,
  currency: "THB",
  reference_id: "ORD888888888",
  bank_code: "004",
  bank_account_no: "1234567890",
  bank_account_name: "ทดสอบ ทดสอบ",
  webhook_url: "https://example.com/path/to/your/webhook",
}).then((res) => console.log(res.data));

php

<?php
$apiKey = 'your_api_key';
$secretKey = 'your_secret_key';
$baseUrl = 'https://gateway.facaiqq.com';

function createSignature($method, $path, $timestamp, $body = '') {
    global $secretKey;
    // สำคัญ: path ต้องเป็น full HTTP path (เช่น /v1/payments/deposit)
    $data = "$method|$path|$timestamp";
    if ($body) {
        $data .= "|$body";
    }
    return hash_hmac('sha256', $data, $secretKey);
}

function makeRequest($method, $path, $body = null) {
    global $apiKey, $baseUrl;

    $timestamp = time();
    $bodyStr = $body ? json_encode($body) : '';
    $signature = createSignature($method, $path, $timestamp, $bodyStr);

    $headers = [
        'X-API-Key: ' . $apiKey,
        'X-Signature: ' . $signature,
        'X-Timestamp: ' . $timestamp,
        'Content-Type: application/json'
    ];

    $ch = curl_init($baseUrl . $path);
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    if ($method === 'POST') {
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, $bodyStr);
    }

    $response = curl_exec($ch);
    curl_close($ch);

    return json_decode($response, true);
}

// สร้างรายการฝากเงิน - ใช้ full path รวม /v1
$response = makeRequest('POST', '/v1/payments/deposit', [
    'amount' => 1000.00,
    'currency' => 'THB',
    'reference_id' => 'ORD888888888',
    'bank_code' => '004',
    'bank_account_no' => '1234567890',
    'bank_account_name' => 'ทดสอบ ทดสอบ',
    'webhook_url' => 'https://example.com/path/to/your/webhook'
]);
print_r($response);

package main

import (
    "bytes"
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    "strconv"
    "time"
)

const (
    apiKey    = "your_api_key"
    secretKey = "your_secret_key"
    baseURL   = "https://gateway.facaiqq.com"
)

func createSignature(method, path, timestamp, body string) string {
    // สำคัญ: path ต้องเป็น full HTTP path (เช่น /v1/payments/deposit)
    data := fmt.Sprintf("%s|%s|%s", method, path, timestamp)
    if body != "" {
        data += "|" + body
    }
    h := hmac.New(sha256.New, []byte(secretKey))
    h.Write([]byte(data))
    return hex.EncodeToString(h.Sum(nil))
}

func makeRequest(method, path string, body interface{}) (map[string]interface{}, error) {
    timestamp := strconv.FormatInt(time.Now().Unix(), 10)

    var bodyStr string
    var reqBody io.Reader
    if body != nil {
        bodyBytes, _ := json.Marshal(body)
        bodyStr = string(bodyBytes)
        reqBody = bytes.NewBuffer(bodyBytes)
    }

    signature := createSignature(method, path, timestamp, bodyStr)

    req, _ := http.NewRequest(method, baseURL+path, reqBody)
    req.Header.Set("X-API-Key", apiKey)
    req.Header.Set("X-Signature", signature)
    req.Header.Set("X-Timestamp", timestamp)
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()

    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)
    return result, nil
}

func main() {
    // สร้างรายการฝากเงิน - ใช้ full path รวม /v1
    result, _ := makeRequest("POST", "/v1/payments/deposit", map[string]interface{}{
        "amount":            1000.00,
        "currency":          "THB",
        "reference_id":      "ORD888888888",
        "bank_code":         "004",
        "bank_account_no":   "1234567890",
        "bank_account_name": "ทดสอบ ทดสอบ",
        "webhook_url":       "https://example.com/path/to/your/webhook",
    })
    fmt.Printf("%+v\n", result)
}

Endpoints

สร้างรายการฝากเงิน (Deposit)

สร้างคำขอฝากเงินใหม่ ระบบจะส่งคืน QR code พร้อมเพย์ให้ลูกค้าชำระเงิน

POST /v1/payments/deposit

Request Body

ฟิลด์	ประเภท	จำเป็น	คำอธิบาย
`amount`	number	ใช่	จำนวนเงิน (> 0)
`currency`	string	ใช่	รหัสสกุลเงิน (3 ตัวอักษร เช่น "THB")
`reference_id`	string	ใช่	รหัสอ้างอิงของคุณ (1-64 ตัวอักษร)
`customer_email`	string	ไม่	อีเมลลูกค้าสำหรับการแจ้งเตือน
`customer_phone`	string	ไม่	เบอร์โทรศัพท์ลูกค้า (สูงสุด 20 ตัวอักษร)
`description`	string	ไม่	คำอธิบายการชำระเงิน (สูงสุด 255 ตัวอักษร)
`webhook_url`	string	ไม่	URL สำหรับรับการแจ้งเตือน
`bank_code`	string	ไม่	รหัสธนาคารของผู้โอน (3 หลัก)
`bank_account_no`	string	ไม่	เลขบัญชีธนาคารของผู้โอน (สูงสุด 20 ตัวอักษร)
`bank_account_name`	string	ไม่	ชื่อบัญชีธนาคารของผู้โอน (สูงสุด 100 ตัวอักษร)

ตัวอย่าง Request

json

{
  "amount": 1000.00,
  "currency": "THB",
  "reference_id": "ORD888888888",
  "bank_code": "004",
  "bank_account_no": "1234567890",
  "bank_account_name": "สมชาย ใจดี",
  "webhook_url": "https://example.com/path/to/your/webhook"
}

Response

รูปแบบของ Response จะขึ้นอยู่กับว่า amount ถึงเกณฑ์ (threshold) ที่แอดมินกำหนดหรือไม่ (ตัวอย่างด้านล่างใช้ 5000 เพื่อประกอบคำอธิบายเท่านั้น — ค่าจริงถูกตั้งโดยแอดมิน)

เมื่อ amount ต่ำกว่าเกณฑ์ (เช่น < 5000) — ชำระผ่าน QR พร้อมเพย์

company_account = false และระบบส่งคืน QR code พร้อมเพย์ตามปกติ

json

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "reference_id": "ORD888888888",
  "type": "deposit",
  "status": "pending",
  "amount": 1000.00,
  "currency": "THB",
  "company_account": false,
  "qr_code": "00020101021129370016A000000677010111011300668123456785802TH5303764...",
  "qr_code_image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
  "created_at": "2025-12-24T10:30:00Z",
  "expires_at": "2025-12-24T10:45:00Z"
}

เมื่อ amount ถึงเกณฑ์ (เช่น >= 5000) — โอนเข้าบัญชีบริษัท

company_account = true พร้อมข้อมูลบัญชีบริษัท (company_account_bank_code, company_account_bank_name, company_account_name, company_account_no) โดย Response นี้จะไม่มีฟิลด์ qr_code / qr_code_image ส่งกลับมา

json

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "reference_id": "ORD888888888",
  "type": "deposit",
  "status": "pending",
  "amount": 5000.00,
  "currency": "THB",
  "company_account": true,
  "company_account_bank_code": "004",
  "company_account_bank_name": "ธนาคารกสิกรไทย",
  "company_account_name": "บริษัท ตัวอย่าง จำกัด",
  "company_account_no": "1234567890",
  "created_at": "2025-12-24T10:30:00Z",
  "expires_at": "2025-12-24T10:45:00Z"
}

Response Fields

ฟิลด์	ประเภท	คำอธิบาย
`id`	string	รหัสธุรกรรมที่ไม่ซ้ำ (รูปแบบ UUID)
`reference_id`	string	รหัสอ้างอิงของคุณ
`type`	string	ประเภทธุรกรรม (`deposit`)
`status`	string	สถานะการชำระเงิน
`amount`	number	จำนวนเงิน
`currency`	string	รหัสสกุลเงิน
`company_account`	boolean	ธงบัญชีบริษัท — เป็น `true` เมื่อ `amount` ถึงเกณฑ์ที่แอดมินกำหนด (โอนเข้าบัญชีบริษัท), เป็น `false` เมื่อต่ำกว่าเกณฑ์ (ชำระผ่าน QR). `5000` เป็นเพียงตัวอย่าง
`company_account_bank_code`	string	รหัสธนาคารของบัญชีบริษัท (3 หลัก) (ส่งเฉพาะเมื่อ `company_account = true`)
`company_account_bank_name`	string	ชื่อธนาคารของบัญชีบริษัท (ส่งเฉพาะเมื่อ `company_account = true`)
`company_account_name`	string	ชื่อเจ้าของบัญชีบริษัท (ส่งเฉพาะเมื่อ `company_account = true`)
`company_account_no`	string	เลขบัญชีบริษัท (ส่งเฉพาะเมื่อ `company_account = true`)
`qr_code`	string	ข้อความ QR code พร้อมเพย์ (ส่งเฉพาะเมื่อ `company_account = false`)
`qr_code_image`	string	รูปภาพ QR code เข้ารหัส Base64 (PNG) (ส่งเฉพาะเมื่อ `company_account = false`)
`created_at`	string	เวลาสร้าง (ISO 8601)
`expires_at`	string	เวลาหมดอายุ (ISO 8601, เริ่มต้น 15 นาที)

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

สร้างคำขอถอน/จ่ายเงินไปยังบัญชีธนาคาร

POST /v1/payments/withdraw

Request Body

ฟิลด์	ประเภท	จำเป็น	คำอธิบาย
`amount`	number	ใช่	จำนวนเงินถอน (> 0)
`currency`	string	ใช่	รหัสสกุลเงิน (3 ตัวอักษร)
`reference_id`	string	ใช่	รหัสอ้างอิงของคุณ (1-64 ตัวอักษร)
`bank_code`	string	ใช่	รหัสธนาคาร (3 หลัก, ดูตารางด้านล่าง)
`account_number`	string	ใช่	เลขบัญชีธนาคาร (10-20 หลัก)
`account_holder_name`	string	ใช่	ชื่อเจ้าของบัญชี (1-100 ตัวอักษร)
`description`	string	ไม่	คำอธิบายการโอน (สูงสุด 255 ตัวอักษร)
`webhook_url`	string	ไม่	URL สำหรับรับการแจ้งเตือน

รหัสธนาคาร

รหัส	ชื่อธนาคาร	ชื่อภาษาอังกฤษ
`002`	ธนาคารกรุงเทพ	Bangkok Bank PCL (BBL)
`004`	ธนาคารกสิกรไทย	Kasikornbank PCL (Kbank)
`006`	ธนาคารกรุงไทย	Krungthai Bank PCL (KTB)
`011`	ธนาคารทหารไทยธนชาต	TMBThanachart Bank PCL (TTB)
`014`	ธนาคารไทยพาณิชย์	Siam Commercial Bank PCL (SCB)
`017`	ธนาคารซิตี้แบงก์	Citibank N.A.
`020`	ธนาคารสแตนดาร์ดชาร์เตอร์ด (ไทย)	Standard Chartered Bank (Thai) PCL
`022`	ธนาคารซีไอเอ็มบี ไทย	CIMB Thai Bank PCL
`024`	ธนาคารยูโอบี	United Overseas Bank (Thai) PCL
`025`	ธนาคารกรุงศรีอยุธยา	Bank of Ayudhya PCL (Krungsri)
`026`	ธนาคารเมกะสากลพาณิชย์	Mega International Commercial Bank
`030`	ธนาคารออมสิน	Government Savings Bank (GSB)
`031`	ธนาคารฮ่องกงและเซี่ยงไฮ้	HSBC Thailand
`033`	ธนาคารอาคารสงเคราะห์	Government Housing Bank (GHB)
`034`	ธนาคารเพื่อการเกษตรฯ	BAAC
`065`	ธนาคารธนชาต	Thanachart Bank PCL
`066`	ธนาคารอิสลามแห่งประเทศไทย	Islamic Bank of Thailand
`067`	ธนาคารทิสโก้	TISCO Bank PCL
`069`	ธนาคารเกียรตินาคินภัทร	Kiatnakin Phatra Bank PCL (KKP)
`070`	ธนาคารไอซีบีซี (ไทย)	ICBC (Thai) PCL
`071`	ธนาคารไทยเครดิต	Thai Credit Retail Bank
`073`	ธนาคารแลนด์ แอนด์ เฮ้าส์	Land and Houses Bank PCL (LH Bank)
`088`	ธนาคารคลิกซ์	Clicx Bank
`PROMPTPAY`	พร้อมเพย์	PromptPay
`TRUE`	ทรูมันนี่	TrueMoney

ถอนเงินผ่านพร้อมเพย์

เมื่อใช้ bank_code: "PROMPTPAY" ฟิลด์ account_number ควรมี:

ความยาวเลขบัญชี	ประเภท Proxy	คำอธิบาย
10 หลัก	MOBILE	เบอร์โทรศัพท์มือถือ
13 หลัก	TXID	เลขบัตรประชาชนหรือเลขประจำตัวผู้เสียภาษี

ตัวอย่าง Request (พร้อมเพย์ด้วยเบอร์โทร):

json

{
  "amount": 5000.00,
  "currency": "THB",
  "reference_id": "ORD888888890",
  "bank_code": "PROMPTPAY",
  "account_number": "0812345678",
  "account_holder_name": "สมชาย ใจดี"
}

ตัวอย่าง Request (พร้อมเพย์ด้วยเลขบัตรประชาชน):

json

{
  "amount": 5000.00,
  "currency": "THB",
  "reference_id": "ORD888888891",
  "bank_code": "PROMPTPAY",
  "account_number": "1234567890123",
  "account_holder_name": "สมชาย ใจดี"
}

ตัวอย่าง Request

json

{
  "amount": 5000.00,
  "currency": "THB",
  "reference_id": "ORD888888889",
  "bank_code": "014",
  "account_number": "1234567890",
  "account_holder_name": "สมชาย ใจดี",
  "webhook_url": "https://example.com/path/to/your/webhook"
}

Response

json

{
  "id": "660e8400-e29b-41d4-a716-446655440000",
  "reference_id": "ORD888888889",
  "type": "withdraw",
  "status": "processing",
  "amount": 5000.00,
  "currency": "THB",
  "created_at": "2025-12-24T11:00:00Z"
}

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

ดึงรายละเอียดการชำระเงินโดยใช้รหัสการชำระเงิน

GET /v1/payments/{id}

Path Parameters

พารามิเตอร์	ประเภท	คำอธิบาย
`id`	string	รหัสการชำระเงิน (รูปแบบ UUID)

ตัวอย่าง Response

json

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "reference_id": "ORDER-2024-001",
  "type": "deposit",
  "status": "completed",
  "amount": 1500.00,
  "currency": "THB",
  "qr_code": "00020101021129370016A000000677010111...",
  "created_at": "2024-12-12T10:30:00Z",
  "expires_at": "2024-12-12T10:45:00Z"
}

ยกเลิกการชำระเงิน

ยกเลิกการชำระเงินที่รอดำเนินการ สามารถยกเลิกได้เฉพาะการชำระเงินที่มีสถานะ pending

POST /v1/payments/{id}/cancel

Path Parameters

พารามิเตอร์	ประเภท	คำอธิบาย
`id`	string	รหัสการชำระเงินที่ต้องการยกเลิก

ตัวอย่าง Response

json

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "reference_id": "ORDER-2024-001",
  "type": "deposit",
  "status": "cancelled",
  "amount": 1500.00,
  "currency": "THB",
  "created_at": "2024-12-12T10:30:00Z"
}

สถานะการชำระเงิน

สถานะ	คำอธิบาย
`pending`	สร้างการชำระเงินแล้ว รอลูกค้าดำเนินการ
`processing`	กำลังดำเนินการชำระเงิน
`completed`	ชำระเงินสำเร็จ
`failed`	ชำระเงินล้มเหลว (รวมถึงธุรกรรมที่หมดอายุ)
`cancelled`	ยกเลิกการชำระเงินแล้ว
`refunded`	คืนเงินแล้ว

หมายเหตุ

เมื่อการชำระเงินหมดอายุ (ลูกค้าไม่ชำระเงินภายในเวลาที่กำหนด) สถานะจะเปลี่ยนเป็น failed พร้อมเหตุผล "Transaction expired" ระบบจะส่ง webhook แจ้งเตือนไปยังระบบของคุณ

Webhooks

เมื่อคุณระบุ webhook_url ระบบจะส่ง POST requests พร้อมการอัปเดตการชำระเงิน

Webhook Payload

Webhook payload จะถูกส่งโดยตรง (ไม่ได้ wrap ใน event structure):

json

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "type": "deposit",
  "amount": 1500.00,
  "fee": 37.50,
  "netAmount": 1462.50,
  "bankAccountNo": "1234567890",
  "bankAccountName": "สมชาย ใจดี",
  "bankCode": "014",
  "bankName": "ธนาคารไทยพาณิชย์",
  "currency": "THB",
  "referenceNo": "ORDER-2024-001",
  "status": "success",
  "timestamp": "2024-12-12T10:35:00Z",
  "paidAt": "2024-12-12T10:34:55.123456789Z"
}

Webhook Payload Fields

ฟิลด์	ประเภท	คำอธิบาย
`id`	string	รหัสธุรกรรม
`type`	string	ประเภทธุรกรรม: `deposit` หรือ `withdraw`
`amount`	number	จำนวนเงินดั้งเดิม
`fee`	number	ค่าธรรมเนียมที่เรียกเก็บ
`netAmount`	number	จำนวนเงินหลังหักค่าธรรมเนียม
`bankAccountNo`	string	เลขบัญชีธนาคาร
`bankAccountName`	string	ชื่อเจ้าของบัญชีธนาคาร
`bankCode`	string	รหัสธนาคาร
`bankName`	string	ชื่อธนาคาร
`currency`	string	รหัสสกุลเงิน
`referenceNo`	string	รหัสอ้างอิงของคุณ
`status`	string	`success`, `failed`, หรือ `expired`
`timestamp`	string	เวลาที่ส่ง webhook (ISO 8601)
`paidAt`	string	เวลาที่ชำระเงินสำเร็จ (ว่างถ้ายังไม่ชำระ)

สถานะ Webhook

สถานะ	คำอธิบาย
`success`	ชำระเงินสำเร็จ
`failed`	ชำระเงินล้มเหลวหรือหมดอายุ
`expired`	การชำระเงินหมดอายุ (เก่า, ใช้ failed แทน)

นโยบายการส่งซ้ำ Webhook

Webhooks จะส่งซ้ำสูงสุด 5 ครั้ง หากการส่งล้มเหลว
ระยะเวลาส่งซ้ำ: 1 นาที ระหว่างแต่ละครั้ง
การส่งสำเร็จคือการตอบกลับด้วย 2xx HTTP response
หลังจากล้มเหลว 5 ครั้ง webhook จะถูกทำเครื่องหมายว่าล้มเหลว

การตรวจสอบ Webhook

Webhook requests มี headers สำหรับการตรวจสอบ:

Header	คำอธิบาย
`X-Webhook-Signature`	ลายเซ็น HMAC-SHA256 ของ request body
`X-Webhook-Timestamp`	Unix timestamp ของ webhook
`Content-Type`	`application/json`

ตรวจสอบ webhooks โดยใช้ HMAC method เดียวกับ API requests:

python

import hmac
import hashlib

def verify_webhook(body, signature, timestamp, secret_key):
    expected = hmac.new(
        secret_key.encode(),
        f"{timestamp}|{body}".encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

Error Responses

Errors ทั้งหมดมีรูปแบบดังนี้:

json

{
  "code": "ERROR_CODE",
  "message": "ข้อความ error ที่อ่านได้"
}

HTTP Status Codes

Status	คำอธิบาย
`200`	สำเร็จ
`201`	สร้างสำเร็จ
`400`	Bad request - พารามิเตอร์ไม่ถูกต้อง
`401`	Unauthorized - API key หรือลายเซ็นไม่ถูกต้อง
`403`	Forbidden - merchant ไม่ใช้งานหรือไม่มีสิทธิ์เพียงพอ
`404`	ไม่พบ
`409`	Conflict - reference_id ซ้ำ
`500`	Internal server error
`504`	Gateway timeout

Error Codes

Code	คำอธิบาย
`INVALID_REQUEST`	การตรวจสอบ request body ล้มเหลว
`MISSING_API_KEY`	ไม่มี X-API-Key header
`MISSING_SIGNATURE`	ไม่มี X-Signature header
`MISSING_TIMESTAMP`	ไม่มี X-Timestamp header
`INVALID_API_KEY`	API key ไม่ถูกต้อง
`INVALID_SIGNATURE`	การตรวจสอบลายเซ็นล้มเหลว
`INVALID_TIMESTAMP`	รูปแบบ timestamp ไม่ถูกต้อง
`TIMESTAMP_EXPIRED`	Timestamp ของ request อยู่นอกช่วงที่ถูกต้อง
`MERCHANT_INACTIVE`	บัญชี merchant ไม่ใช้งาน
`PAYMENT_NOT_FOUND`	ไม่พบการชำระเงิน
`PAYMENT_ERROR`	ข้อผิดพลาดการประมวลผลการชำระเงินทั่วไป
`DUPLICATE_REFERENCE`	Reference ID มีอยู่แล้ว
`INSUFFICIENT_BALANCE`	ยอดเงินไม่เพียงพอสำหรับการถอน
`INVALID_BANK_CODE`	รหัสธนาคารไม่ถูกต้อง
`INVALID_ACCOUNT`	บัญชีธนาคารไม่ถูกต้อง (sandbox)
`PAYMENT_CANNOT_BE_CANCELLED`	ไม่สามารถยกเลิกการชำระเงินได้
`TIMEOUT`	Request หมดเวลา

การทดสอบ Sandbox

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

โหมด Sandbox ถูกกำหนดโดย ประเภท merchant ไม่ใช่ URL แยก ทั้ง sandbox และ production merchants ใช้ API endpoint เดียวกัน:

Base URL: https://gateway.facaiqq.com/v1

Sandbox Merchants: ธุรกรรมเก็บในฐานข้อมูล sandbox ไม่มีการประมวลผลเงินจริง
Production Merchants: ธุรกรรมเก็บในฐานข้อมูล production และประมวลผลผ่านผู้ให้บริการชำระเงิน

ติดต่อฝ่ายสนับสนุนเพื่อขอ sandbox credentials สำหรับการทดสอบ

จำนวนเงินทดสอบ

ในโหมด sandbox จำนวนเงินเฉพาะจะทริกเกอร์พฤติกรรมต่างๆ:

จำนวน	สกุลเงิน	พฤติกรรม	คำอธิบาย
`100.00`	THB	`auto_approve`	ชำระเงินสำเร็จทันที
`200.00`	THB	`auto_pending`	รอดำเนินการต่อ (จำลองการล่าช้า)
`500.00`	THB	`auto_approve`	ชำระเงินสำเร็จทันที
`888.88`	THB	`timeout`	หมดเวลา
`999.99`	THB	`auto_fail`	ชำระเงินล้มเหลวทันที
`1000.00`	THB	`auto_approve`	ชำระเงินสำเร็จทันที
อื่นๆ	THB	`pending`	การชำระเงินปกติ

สถานการณ์ทดสอบ

คุณสามารถ override พฤติกรรมโดยใช้ X-Sandbox-Scenario header:

สถานการณ์	คำอธิบาย
`auto_approve`	บังคับให้การชำระเงินสำเร็จทันที
`auto_fail`	บังคับให้การชำระเงินล้มเหลว
`auto_pending`	บังคับให้การชำระเงินค้างอยู่ในสถานะ pending
`timeout`	จำลอง timeout
`invalid_account`	จำลองบัญชีธนาคารไม่ถูกต้อง (withdraw เท่านั้น)

ตัวอย่าง:

bash

curl -X POST https://gateway.facaiqq.com/v1/payments/deposit \
  -H "X-Sandbox-Scenario: auto_approve" \
  -H "X-API-Key: your_sandbox_api_key" \
  -H "X-Signature: ..." \
  -H "X-Timestamp: ..." \
  -H "Content-Type: application/json" \
  -d '{"amount": 500.00, "currency": "THB", "reference_id": "TEST-001"}'

Response Headers

Responses รวม header ที่ระบุสภาพแวดล้อม:

Header	ค่า	คำอธิบาย
`X-Environment`	`sandbox` หรือ `production`	ระบุประเภท merchant

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

ธุรกรรมฝากเงิน มีเวลาหมดอายุเริ่มต้น 15 นาที
หากลูกค้าไม่ชำระเงินภายในเวลานี้:
- สถานะเปลี่ยนเป็น failed (ไม่ใช่ expired)
- failure_reason ตั้งเป็น "Transaction expired"
- ส่ง Webhook พร้อม status: "failed"
การตรวจสอบหมดอายุทำงานทุก 1 นาที

Rate Limits

Endpoint	Rate Limit
ทุก endpoints	100 requests/นาที
สร้าง Deposit	30 requests/นาที
สร้าง Withdraw	20 requests/นาที

Rate limit headers รวมอยู่ใน responses:

Header	คำอธิบาย
`X-RateLimit-Limit`	จำนวน request สูงสุดต่อ window
`X-RateLimit-Remaining`	จำนวน request ที่เหลือใน window
`X-RateLimit-Reset`	Unix timestamp เมื่อ limit รีเซ็ต

การสนับสนุน

สำหรับการสนับสนุนทางเทคนิค:

Email: [email protected]
Documentation: https://docs.facaiqq.com
Status Page: https://gateway.facaiqq.com

เอกสาร Public API ​

สภาพแวดล้อม ​

ภาพรวม ​

Production vs Sandbox ​

การยืนยันตัวตน ​

การสร้างลายเซ็น ​

ตัวอย่างโค้ด ​

Endpoints ​

สร้างรายการฝากเงิน (Deposit) ​

Request Body ​

ตัวอย่าง Request ​

Response ​

Response Fields ​

สร้างรายการถอนเงิน (Withdraw) ​

Request Body ​

รหัสธนาคาร ​

ถอนเงินผ่านพร้อมเพย์ ​

ตัวอย่าง Request ​

Response ​

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

Path Parameters ​

ตัวอย่าง Response ​

ยกเลิกการชำระเงิน ​

Path Parameters ​

ตัวอย่าง Response ​

สถานะการชำระเงิน ​

Webhooks ​

Webhook Payload ​

Webhook Payload Fields ​

สถานะ Webhook ​

นโยบายการส่งซ้ำ Webhook ​

การตรวจสอบ Webhook ​

Error Responses ​

HTTP Status Codes ​

Error Codes ​

การทดสอบ Sandbox ​

Sandbox ทำงานอย่างไร ​

จำนวนเงินทดสอบ ​

สถานการณ์ทดสอบ ​

Response Headers ​

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

Rate Limits ​

การสนับสนุน ​

เอกสาร Public API

สภาพแวดล้อม

ภาพรวม

Production vs Sandbox

การยืนยันตัวตน

การสร้างลายเซ็น

ตัวอย่างโค้ด

Endpoints

สร้างรายการฝากเงิน (Deposit)

Request Body

ตัวอย่าง Request

Response

Response Fields

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

Request Body

รหัสธนาคาร

ถอนเงินผ่านพร้อมเพย์

ตัวอย่าง Request

Response

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

Path Parameters

ตัวอย่าง Response

ยกเลิกการชำระเงิน

Path Parameters

ตัวอย่าง Response

สถานะการชำระเงิน

Webhooks

Webhook Payload

Webhook Payload Fields

สถานะ Webhook

นโยบายการส่งซ้ำ Webhook

การตรวจสอบ Webhook

Error Responses

HTTP Status Codes

Error Codes

การทดสอบ Sandbox

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

จำนวนเงินทดสอบ

สถานการณ์ทดสอบ

Response Headers

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

Rate Limits

การสนับสนุน