ເອກະສານ API ສາທາລະນະ

ເວີຊັ່ນ: 1.1.0 ອັບເດດລ່າສຸດ: 2025-12-24

ສະພາບແວດລ້ອມ

ສະພາບແວດລ້ອມ	Base URL	ຄຳອະທິບາຍ
Production	`https://gateway.facaiqq.com/v1`	ທຸລະກຳຈິງ, ການຊຳລະເງິນຈິງ
Sandbox	`https://gateway.facaiqq.com/v1`	ທຸລະກຳທົດສອບ (ປະເພດ merchant sandbox ເທົ່ານັ້ນ)

ພາບລວມ

API ສາທາລະນະຊ່ວຍໃຫ້ merchants ສາມາດເຊື່ອມຕໍ່ຄວາມສາມາດໃນການປະມວນຜົນການຊຳລະເງິນເຂົ້າກັບແອັບພລິເຄຊັນຂອງພວກເຂົາ. ທຸກຄຳຂໍ API ຕ້ອງມີການຢືນຢັນຕົວຕົນດ້ວຍ HMAC-SHA256.

Production ທຽບກັບ Sandbox

ປະເພດ Merchant ກຳນົດເສັ້ນທາງທຸລະກຳ:

Production Merchant: ທຸລະກຳເງິນຈິງທີ່ປະມວນຜົນຜ່ານຜູ້ໃຫ້ບໍລິການຊຳລະເງິນ.
Sandbox Merchant: ທຸລະກຳຈຳລອງສຳລັບການທົດສອບ. ຄຳຕອບຖືກຈຳລອງໃນທ້ອງຖິ່ນໂດຍບໍ່ມີການປະມວນຜົນພາຍນອກ.

ການຢືນຢັນຕົວຕົນ

ທຸກຄຳຂໍ API ຕ້ອງມີ headers ດັ່ງຕໍ່ໄປນີ້:

Header	ຈຳເປັນ	ຄຳອະທິບາຍ
`X-API-Key`	ແມ່ນ	API key ຂອງ merchant ຂອງທ່ານ (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):

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

ຕົວຢ່າງ (ຄຳຂໍ GET):

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 ຕ້ອງເປັນເສັ້ນທາງ HTTP ເຕັມ (ເຊັ່ນ: /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)

# ສ້າງ deposit - ໝາຍເຫດ: ໃຊ້ເສັ້ນທາງເຕັມລວມທັງ /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": "test test",
    "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 ຕ້ອງເປັນເສັ້ນທາງ HTTP ເຕັມ (ເຊັ່ນ: /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 });
  }
}

// ສ້າງ deposit - ໝາຍເຫດ: ໃຊ້ເສັ້ນທາງເຕັມລວມທັງ /v1
makeRequest("POST", "/v1/payments/deposit", {
  amount: 1000.0,
  currency: "THB",
  reference_id: "ORD888888888",
  bank_code: "004",
  bank_account_no: "1234567890",
  bank_account_name: "test test",
  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 ຕ້ອງເປັນເສັ້ນທາງ HTTP ເຕັມ (ເຊັ່ນ: /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);
}

// ສ້າງ deposit - ໝາຍເຫດ: ໃຊ້ເສັ້ນທາງເຕັມລວມທັງ /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' => 'test test',
    '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 ຕ້ອງເປັນເສັ້ນທາງ HTTP ເຕັມ (ເຊັ່ນ: /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() {
    // ສ້າງ deposit - ໝາຍເຫດ: ໃຊ້ເສັ້ນທາງເຕັມລວມທັງ /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": "test test",
        "webhook_url":       "https://example.com/path/to/your/webhook",
    })
    fmt.Printf("%+v\n", result)
}

Endpoints

ສ້າງ Deposit

ສ້າງຄຳຂໍການຊຳລະເງິນ deposit ໃໝ່. ສົ່ງຄືນ PromptPay 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 webhook ສຳລັບການແຈ້ງເຕືອນການຊຳລະເງິນ
`bank_code`	string	ບໍ່	ລະຫັດທະນາຄານຂອງຜູ້ຊຳລະ (3 ຕົວເລກ) ສຳລັບອ້າງອີງ
`bank_account_no`	string	ບໍ່	ເລກບັນຊີທະນາຄານຂອງຜູ້ຊຳລະ (ສູງສຸດ 20 ຕົວອັກສອນ)
`bank_account_name`	string	ບໍ່	ຊື່ເຈົ້າຂອງບັນຊີທະນາຄານຂອງຜູ້ຊຳລະ (ສູງສຸດ 100 ຕົວອັກສອນ)

ຕົວຢ່າງຄຳຂໍ

json

{
  "amount": 1000.00,
  "currency": "THB",
  "reference_id": "ORD888888888",
  "bank_code": "004",
  "bank_account_no": "1234567890",
  "bank_account_name": "test test",
  "webhook_url": "https://example.com/path/to/your/webhook"
}

ຄຳຕອບ

ຮູບແບບຄຳຕອບຈະຂຶ້ນກັບວ່າຍອດ amount ຮອດເກນທີ່ແອັດມິນກຳນົດຫຼືບໍ່ (ຕົວຢ່າງດ້ານລຸ່ມໃຊ້ເກນ 5000 ເຊິ່ງເປັນພຽງຄ່າຕົວຢ່າງເທົ່ານັ້ນ — ຄ່າຈິງກຳນົດໂດຍແອັດມິນ).

ກໍລະນີ amount ຕ່ຳກວ່າເກນ (ເຊັ່ນ < 5000) — ຊຳລະຜ່ານ QR PromptPay

company_account = false ແລະ ຍັງຄົງສົ່ງຄືນ QR code PromptPay ຕາມປົກກະຕິ.

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). ຄຳຕອບນີ້ຈະບໍ່ສົ່ງຄືນຊ່ອງ 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"
}

ຊ່ອງຂໍ້ມູນຄຳຕອບ

ຊ່ອງຂໍ້ມູນ	ປະເພດ	ຄຳອະທິບາຍ
`id`	string	ID ທຸລະກຳທີ່ບໍ່ຊ້ຳກັນ (ຮູບແບບ 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	ສະຕຣິງ PromptPay 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 webhook ສຳລັບການແຈ້ງເຕືອນການໂອນ

ລະຫັດທະນາຄານ

ລະຫັດ	ຊື່ໄທ	ຊື່ອັງກິດ
`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

ການຖອນເງິນ PromptPay

ເມື່ອໃຊ້ bank_code: "PROMPTPAY", ຊ່ອງ account_number ຄວນມີ:

ຄວາມຍາວເລກບັນຊີ	ປະເພດ Proxy	ຄຳອະທິບາຍ
10 ຕົວເລກ	MOBILE	ເບີໂທລະສັບມືຖື
13 ຕົວເລກ	TXID	ເລກບັດປະຈຳຕົວ ຫຼື ເລກປະຈຳຕົວຜູ້ເສຍພາສີ

ຕົວຢ່າງຄຳຂໍ (PromptPay ກັບເບີມືຖື):

json

{
  "amount": 5000.00,
  "currency": "THB",
  "reference_id": "ORD888888890",
  "bank_code": "PROMPTPAY",
  "account_number": "0812345678",
  "account_holder_name": "John Doe"
}

ຕົວຢ່າງຄຳຂໍ (PromptPay ກັບເລກບັດປະຈຳຕົວ):

json

{
  "amount": 5000.00,
  "currency": "THB",
  "reference_id": "ORD888888891",
  "bank_code": "PROMPTPAY",
  "account_number": "1234567890123",
  "account_holder_name": "John Doe"
}

ຕົວຢ່າງຄຳຂໍ

json

{
  "amount": 5000.00,
  "currency": "THB",
  "reference_id": "ORD888888889",
  "bank_code": "014",
  "account_number": "1234567890",
  "account_holder_name": "John Doe",
  "webhook_url": "https://example.com/path/to/your/webhook"
}

ຄຳຕອບ

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"
}

ເອົາຂໍ້ມູນການຊຳລະເງິນ

ເອົາລາຍລະອຽດການຊຳລະເງິນໂດຍ ID ການຊຳລະເງິນ.

GET /v1/payments/{id}

Path Parameters

Parameter	ປະເພດ	ຄຳອະທິບາຍ
`id`	string	ID ການຊຳລະເງິນ (ຮູບແບບ UUID)

ຕົວຢ່າງຄຳຕອບ

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

Parameter	ປະເພດ	ຄຳອະທິບາຍ
`id`	string	ID ການຊຳລະເງິນທີ່ຈະຍົກເລີກ

ຕົວຢ່າງຄຳຕອບ

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 ພ້ອມກັບການອັບເດດການຊຳລະເງິນ.

Webhook Payload

Webhook payload ຖືກສົ່ງໂດຍກົງ (ບໍ່ໄດ້ຫໍ່ຢູ່ໃນໂຄງສ້າງເຫດການ):

json

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "type": "deposit",
  "amount": 1500.00,
  "fee": 37.50,
  "netAmount": 1462.50,
  "bankAccountNo": "1234567890",
  "bankAccountName": "SOMCHAI JAIDEE",
  "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

ຊ່ອງຂໍ້ມູນ	ປະເພດ	ຄຳອະທິບາຍ
`id`	string	ID ທຸລະກຳ
`type`	string	ປະເພດທຸລະກຳ: `deposit` ຫຼື `withdraw`
`amount`	number	ຈຳນວນເງິນການຊຳລະເງິນເດີມ
`fee`	number	ຄ່າທຳນຽມການປະມວນຜົນ
`netAmount`	number	ຈຳນວນເງິນຫຼັງຫັກຄ່າທຳນຽມ
`bankAccountNo`	string	ເລກບັນຊີທະນາຄານ (ສຳລັບ deposits ທີ່ມີຂໍ້ມູນຜູ້ຊຳລະ)
`bankAccountName`	string	ຊື່ເຈົ້າຂອງບັນຊີທະນາຄານ
`bankCode`	string	ລະຫັດທະນາຄານ
`bankName`	string	ຊື່ທະນາຄານເປັນພາສາໄທ
`currency`	string	ລະຫັດສະກຸນເງິນ
`referenceNo`	string	ID ອ້າງອີງຂອງທ່ານ
`status`	string	`success`, `failed`, ຫຼື `expired`
`timestamp`	string	ເວລາສົ່ງ webhook (ISO 8601)
`paidAt`	string	ເວລາສຳເລັດການຊຳລະເງິນ (ວ່າງຖ້າຍັງບໍ່ຊຳລະ)

ຄ່າສະຖານະ Webhook

ສະຖານະ	ຄຳອະທິບາຍ
`success`	ການຊຳລະເງິນສຳເລັດແລ້ວ
`failed`	ການຊຳລະເງິນລົ້ມເຫລວ ຫຼື ໝົດອາຍຸ
`expired`	ການຊຳລະເງິນໝົດອາຍຸ (legacy, ປັດຈຸບັນໃຊ້ failed)

ນະໂຍບາຍການລອງສົ່ງ Webhook ໃໝ່

Webhooks ຈະຖືກລອງສົ່ງໃໝ່ສູງສຸດ 5 ຄັ້ງ ຖ້າການສົ່ງລົ້ມເຫລວ
ໄລຍະຫ່າງການລອງໃໝ່: 1 ນາທີ ລະຫວ່າງການພະຍາຍາມ
ການສົ່ງສຳເລັດແມ່ນ ຄຳຕອບ HTTP 2xx ໃດໆກໍໄດ້
ຫຼັງຈາກ 5 ຄັ້ງທີ່ລົ້ມເຫລວ, webhook ຈະຖືກໝາຍວ່າລົ້ມເຫລວ

ການຢືນຢັນ Webhook

ຄຳຂໍ Webhook ລວມມີ headers ສຳລັບການຢືນຢັນ:

Header	ຄຳອະທິບາຍ
`X-Webhook-Signature`	ລາຍເຊັນ HMAC-SHA256 ຂອງ request body
`X-Webhook-Timestamp`	Unix timestamp ຂອງ webhook
`Content-Type`	`application/json`

ຢືນຢັນ webhooks ໂດຍໃຊ້ວິທີ HMAC ດຽວກັນກັບຄຳຂໍ API:

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)

ຄຳຕອບຂໍ້ຜິດພາດ

ຂໍ້ຜິດພາດທັງໝົດມີຮູບແບບດັ່ງນີ້:

json

{
  "code": "ERROR_CODE",
  "message": "Human-readable error message"
}

ລະຫັດສະຖານະ HTTP

ສະຖານະ	ຄຳອະທິບາຍ
`200`	ສຳເລັດ
`201`	ສ້າງສຳເລັດ
`400`	ຄຳຂໍບໍ່ຖືກຕ້ອງ - parameters ບໍ່ຖືກຕ້ອງ
`401`	ບໍ່ໄດ້ຮັບອະນຸຍາດ - API key ຫຼື ລາຍເຊັນບໍ່ຖືກຕ້ອງ
`403`	ຖືກຫ້າມ - merchant ບໍ່ເຄື່ອນໄຫວ ຫຼື ສິດທິບໍ່ພຽງພໍ
`404`	ບໍ່ພົບ
`409`	ຂັດແຍ້ງ - reference_id ຊ້ຳ
`500`	ຂໍ້ຜິດພາດພາຍໃນເຊີບເວີ
`504`	Gateway timeout

ລະຫັດຂໍ້ຜິດພາດ

ລະຫັດ	ຄຳອະທິບາຍ
`INVALID_REQUEST`	ການກວດສອບ request body ລົ້ມເຫລວ
`MISSING_API_KEY`	ຂາດ header X-API-Key
`MISSING_SIGNATURE`	ຂາດ header X-Signature
`MISSING_TIMESTAMP`	ຂາດ header X-Timestamp
`INVALID_API_KEY`	API key ບໍ່ຖືກຕ້ອງ
`INVALID_SIGNATURE`	ການຢືນຢັນລາຍເຊັນລົ້ມເຫລວ
`INVALID_TIMESTAMP`	ຮູບແບບ timestamp ບໍ່ຖືກຕ້ອງ
`TIMESTAMP_EXPIRED`	timestamp ຂອງຄຳຂໍຢູ່ນອກຂອບເຂດທີ່ຖືກຕ້ອງ
`MERCHANT_INACTIVE`	ບັນຊີ merchant ບໍ່ເຄື່ອນໄຫວ
`PAYMENT_NOT_FOUND`	ບໍ່ພົບການຊຳລະເງິນ
`PAYMENT_ERROR`	ຂໍ້ຜິດພາດການປະມວນຜົນການຊຳລະເງິນທົ່ວໄປ
`DUPLICATE_REFERENCE`	ID ອ້າງອີງມີຢູ່ແລ້ວ
`INSUFFICIENT_BALANCE`	ຍອດເງິນບໍ່ພຽງພໍສຳລັບການຖອນ
`INVALID_BANK_CODE`	ລະຫັດທະນາຄານບໍ່ຖືກຕ້ອງ
`INVALID_ACCOUNT`	ບັນຊີທະນາຄານບໍ່ຖືກຕ້ອງ (sandbox)
`PAYMENT_CANNOT_BE_CANCELLED`	ບໍ່ສາມາດຍົກເລີກການຊຳລະເງິນໄດ້
`TIMEOUT`	ຄຳຂໍໝົດເວລາ

ການທົດສອບ Sandbox

Sandbox ເຮັດວຽກແນວໃດ

ໂໝດ Sandbox ຖືກກຳນົດໂດຍ ປະເພດ merchant ຂອງທ່ານ, ບໍ່ແມ່ນ URL ແຍກຕ່າງຫາກ. ທັງ sandbox ແລະ production merchants ໃຊ້ API endpoint ດຽວກັນ:

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

Sandbox Merchants: ທຸລະກຳຖືກເກັບໄວ້ໃນຖານຂໍ້ມູນ sandbox. ບໍ່ມີການປະມວນຜົນເງິນຈິງ.
Production Merchants: ທຸລະກຳຖືກເກັບໄວ້ໃນຖານຂໍ້ມູນ production ແລະ ປະມວນຜົນຜ່ານຜູ້ໃຫ້ບໍລິການຊຳລະເງິນ.

ຕິດຕໍ່ຝ່າຍຊ່ວຍເຫຼືອເພື່ອຂໍ credentials sandbox ສຳລັບການທົດສອບ.

ຈຳນວນເງິນທົດສອບ

ໃນໂໝດ 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`	ຂັ້ນຕອນການຊຳລະເງິນປົກກະຕິ

ສະຖານະການທົດສອບ

ທ່ານສາມາດແທນທີ່ພຶດຕິກຳໂດຍໃຊ້ header X-Sandbox-Scenario:

ສະຖານະການ	ຄຳອະທິບາຍ
`auto_approve`	ບັງຄັບໃຫ້ການຊຳລະເງິນສຳເລັດທັນທີ
`auto_fail`	ບັງຄັບໃຫ້ການຊຳລະເງິນລົ້ມເຫລວ
`auto_pending`	ບັງຄັບໃຫ້ການຊຳລະເງິນຢູ່ໃນສະຖານະລໍຖ້າ
`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

ຄຳຕອບລວມມີ header ທີ່ບອກສະພາບແວດລ້ອມ:

Header	ຄ່າ	ຄຳອະທິບາຍ
`X-Environment`	`sandbox` ຫຼື `production`	ບອກປະເພດ merchant

ການໝົດອາຍຸທຸລະກຳ

ທຸລະກຳ Deposit ມີຄ່າເລີ່ມຕົ້ນການໝົດອາຍຸ 15 ນາທີ
ຖ້າລູກຄ້າບໍ່ຊຳລະເງິນພາຍໃນເວລານີ້:
- ສະຖານະປ່ຽນເປັນ failed (ບໍ່ແມ່ນ expired)
- failure_reason ຖືກຕັ້ງເປັນ "Transaction expired"
- Webhook ຖືກສົ່ງພ້ອມກັບ status: "failed"
ການກວດສອບການໝົດອາຍຸດຳເນີນທຸກ 1 ນາທີ

ຂໍ້ຈຳກັດອັດຕາ

Endpoint	ຂໍ້ຈຳກັດອັດຕາ
ທຸກ endpoints	100 ຄຳຂໍ/ນາທີ
Create Deposit	30 ຄຳຂໍ/ນາທີ
Create Withdraw	20 ຄຳຂໍ/ນາທີ

Headers ຂໍ້ຈຳກັດອັດຕາລວມຢູ່ໃນຄຳຕອບ:

Header	ຄຳອະທິບາຍ
`X-RateLimit-Limit`	ຄຳຂໍສູງສຸດຕໍ່ຊ່ວງເວລາ
`X-RateLimit-Remaining`	ຄຳຂໍທີ່ຍັງເຫຼືອໃນຊ່ວງເວລາ
`X-RateLimit-Reset`	Unix timestamp ເວລາຂໍ້ຈຳກັດຖືກຣີເຊັດ

ການຊ່ວຍເຫຼືອ

ສຳລັບການຊ່ວຍເຫຼືອດ້ານເທັກນິກ:

ອີເມວ: [email protected]
ເອກະສານ: https://docs.facaiqq.com
ໜ້າສະຖານະ: https://gateway.facaiqq.com

ເອກະສານ API ສາທາລະນະ ​

ສະພາບແວດລ້ອມ ​

ພາບລວມ ​

Production ທຽບກັບ Sandbox ​

ການຢືນຢັນຕົວຕົນ ​

ການສ້າງລາຍເຊັນ ​

ຕົວຢ່າງລະຫັດ ​

Endpoints ​

ສ້າງ Deposit ​

Request Body ​

ຕົວຢ່າງຄຳຂໍ ​

ຄຳຕອບ ​

ຊ່ອງຂໍ້ມູນຄຳຕອບ ​

ສ້າງ Withdraw ​

Request Body ​

ລະຫັດທະນາຄານ ​

ການຖອນເງິນ PromptPay ​

ຕົວຢ່າງຄຳຂໍ ​

ຄຳຕອບ ​

ເອົາຂໍ້ມູນການຊຳລະເງິນ ​

Path Parameters ​

ຕົວຢ່າງຄຳຕອບ ​

ຍົກເລີກການຊຳລະເງິນ ​

Path Parameters ​

ຕົວຢ່າງຄຳຕອບ ​

ສະຖານະການຊຳລະເງິນ ​

Webhooks ​

Webhook Payload ​

ຊ່ອງຂໍ້ມູນ Webhook Payload ​

ຄ່າສະຖານະ Webhook ​

ນະໂຍບາຍການລອງສົ່ງ Webhook ໃໝ່ ​

ການຢືນຢັນ Webhook ​

ຄຳຕອບຂໍ້ຜິດພາດ ​

ລະຫັດສະຖານະ HTTP ​

ລະຫັດຂໍ້ຜິດພາດ ​

ການທົດສອບ Sandbox ​

Sandbox ເຮັດວຽກແນວໃດ ​

ຈຳນວນເງິນທົດສອບ ​

ສະຖານະການທົດສອບ ​

Response Headers ​

ການໝົດອາຍຸທຸລະກຳ ​

ຂໍ້ຈຳກັດອັດຕາ ​

ການຊ່ວຍເຫຼືອ ​

ເອກະສານ API ສາທາລະນະ

ສະພາບແວດລ້ອມ

ພາບລວມ

Production ທຽບກັບ Sandbox

ການຢືນຢັນຕົວຕົນ

ການສ້າງລາຍເຊັນ

ຕົວຢ່າງລະຫັດ

Endpoints

ສ້າງ Deposit

Request Body

ຕົວຢ່າງຄຳຂໍ

ຄຳຕອບ

ຊ່ອງຂໍ້ມູນຄຳຕອບ

ສ້າງ Withdraw

Request Body

ລະຫັດທະນາຄານ

ການຖອນເງິນ PromptPay

ຕົວຢ່າງຄຳຂໍ

ຄຳຕອບ

ເອົາຂໍ້ມູນການຊຳລະເງິນ

Path Parameters

ຕົວຢ່າງຄຳຕອບ

ຍົກເລີກການຊຳລະເງິນ

Path Parameters

ຕົວຢ່າງຄຳຕອບ

ສະຖານະການຊຳລະເງິນ

Webhooks

Webhook Payload

ຊ່ອງຂໍ້ມູນ Webhook Payload

ຄ່າສະຖານະ Webhook

ນະໂຍບາຍການລອງສົ່ງ Webhook ໃໝ່

ການຢືນຢັນ Webhook

ຄຳຕອບຂໍ້ຜິດພາດ

ລະຫັດສະຖານະ HTTP

ລະຫັດຂໍ້ຜິດພາດ

ການທົດສອບ Sandbox

Sandbox ເຮັດວຽກແນວໃດ

ຈຳນວນເງິນທົດສອບ

ສະຖານະການທົດສອບ

Response Headers

ການໝົດອາຍຸທຸລະກຳ

ຂໍ້ຈຳກັດອັດຕາ

ການຊ່ວຍເຫຼືອ