Tài liệu Public API

Phiên bản: 1.1.0 Cập nhật lần cuối: 2025-12-24

Môi trường

Môi trường	Base URL	Mô tả
Production	`https://gateway.facaiqq.com/v1`	Giao dịch thực, thanh toán trực tiếp
Sandbox	`https://gateway.facaiqq.com/v1`	Giao dịch thử nghiệm (chỉ dành cho merchant sandbox)

Tổng quan

Public API cho phép các merchant tích hợp khả năng xử lý thanh toán vào ứng dụng của họ. Tất cả các yêu cầu API đều yêu cầu xác thực HMAC-SHA256.

Production vs Sandbox

Loại merchant quyết định định tuyến giao dịch:

Merchant Production: Giao dịch tiền thật được xử lý thông qua các nhà cung cấp thanh toán.
Merchant Sandbox: Giao dịch mô phỏng để thử nghiệm. Phản hồi được mô phỏng cục bộ mà không xử lý bên ngoài.

Xác thực

Tất cả các yêu cầu API phải bao gồm các headers sau:

Header	Bắt buộc	Mô tả
`X-API-Key`	Có	API key của merchant (64 ký tự)
`X-Signature`	Có	Chữ ký HMAC-SHA256 của yêu cầu
`X-Timestamp`	Có	Unix timestamp (số giây từ epoch)
`Content-Type`	Có	`application/json`

Tạo chữ ký

Chữ ký được tính toán bằng HMAC-SHA256 với Secret Key của bạn:

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

Ví dụ (yêu cầu POST):

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

Ví dụ (yêu cầu GET):

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

Ví dụ mã nguồn

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=""):
    # QUAN TRỌNG: path phải là đường dẫn HTTP đầy đủ (ví dụ: /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)

# Tạo deposit - lưu ý: sử dụng đường dẫn đầy đủ bao gồm /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 = "") {
  // QUAN TRỌNG: path phải là đường dẫn HTTP đầy đủ (ví dụ: /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 });
  }
}

// Tạo deposit - lưu ý: sử dụng đường dẫn đầy đủ bao gồm /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;
    // QUAN TRỌNG: path phải là đường dẫn HTTP đầy đủ (ví dụ: /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);
}

// Tạo deposit - lưu ý: sử dụng đường dẫn đầy đủ bao gồm /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 {
    // QUAN TRỌNG: path phải là đường dẫn HTTP đầy đủ (ví dụ: /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() {
    // Tạo deposit - lưu ý: sử dụng đường dẫn đầy đủ bao gồm /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

Tạo Deposit

Tạo yêu cầu thanh toán deposit mới. Trả về mã QR PromptPay để khách hàng thanh toán.

POST /v1/payments/deposit

Nội dung yêu cầu

Trường	Kiểu	Bắt buộc	Mô tả
`amount`	number	Có	Số tiền thanh toán (> 0)
`currency`	string	Có	Mã tiền tệ (3 ký tự, ví dụ: "THB")
`reference_id`	string	Có	Mã tham chiếu đơn hàng duy nhất của bạn (1-64 ký tự)
`customer_email`	string	Không	Email khách hàng để nhận thông báo
`customer_phone`	string	Không	Số điện thoại khách hàng (tối đa 20 ký tự)
`description`	string	Không	Mô tả thanh toán (tối đa 255 ký tự)
`webhook_url`	string	Không	URL webhook để nhận thông báo thanh toán
`bank_code`	string	Không	Mã ngân hàng của người trả (3 chữ số) để tham chiếu
`bank_account_no`	string	Không	Số tài khoản ngân hàng của người trả (tối đa 20 ký tự)
`bank_account_name`	string	Không	Tên chủ tài khoản ngân hàng (tối đa 100 ký tự)

Ví dụ yêu cầu

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

Phản hồi

Định dạng phản hồi phụ thuộc vào việc amount có đạt ngưỡng do quản trị viên cấu hình hay không (ví dụ bên dưới dùng 5000 chỉ để minh họa — giá trị thực tế do quản trị viên thiết lập).

Khi amount thấp hơn ngưỡng (ví dụ < 5000) — Thanh toán qua mã QR PromptPay

company_account = false và mã QR PromptPay vẫn được trả về như bình thường.

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

Khi amount đạt ngưỡng (ví dụ >= 5000) — Chuyển khoản vào tài khoản công ty

company_account = true kèm thông tin tài khoản công ty (company_account_bank_code, company_account_bank_name, company_account_name, company_account_no). Trường qr_code / qr_code_image sẽ không được trả về trong phản hồi này.

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": "Kasikornbank",
  "company_account_name": "Công ty Ví dụ TNHH",
  "company_account_no": "1234567890",
  "created_at": "2025-12-24T10:30:00Z",
  "expires_at": "2025-12-24T10:45:00Z"
}

Các trường phản hồi

Trường	Kiểu	Mô tả
`id`	string	ID giao dịch duy nhất (định dạng UUID)
`reference_id`	string	Mã tham chiếu đơn hàng của bạn
`type`	string	Loại giao dịch (`deposit`)
`status`	string	Trạng thái thanh toán
`amount`	number	Số tiền thanh toán
`currency`	string	Mã tiền tệ
`company_account`	boolean	Cờ tài khoản công ty — `true` khi `amount` đạt ngưỡng quản trị viên cấu hình (chuyển khoản công ty), `false` khi thấp hơn ngưỡng (thanh toán QR). `5000` chỉ là ví dụ.
`company_account_bank_code`	string	Mã ngân hàng của tài khoản công ty (3 chữ số) (chỉ hiển thị khi `company_account = true`)
`company_account_bank_name`	string	Tên ngân hàng của tài khoản công ty (chỉ hiển thị khi `company_account = true`)
`company_account_name`	string	Tên chủ tài khoản công ty (chỉ hiển thị khi `company_account = true`)
`company_account_no`	string	Số tài khoản công ty (chỉ hiển thị khi `company_account = true`)
`qr_code`	string	Chuỗi mã QR PromptPay (chỉ trả về khi `company_account = false`)
`qr_code_image`	string	Hình ảnh mã QR được mã hóa Base64, PNG (chỉ trả về khi `company_account = false`)
`created_at`	string	Thời gian tạo (ISO 8601)
`expires_at`	string	Thời gian hết hạn (ISO 8601, mặc định 15 phút)

Tạo Withdraw

Tạo yêu cầu rút tiền/chi trả mới vào tài khoản ngân hàng.

POST /v1/payments/withdraw

Nội dung yêu cầu

Trường	Kiểu	Bắt buộc	Mô tả
`amount`	number	Có	Số tiền rút (> 0)
`currency`	string	Có	Mã tiền tệ (3 ký tự)
`reference_id`	string	Có	Mã tham chiếu duy nhất của bạn (1-64 ký tự)
`bank_code`	string	Có	Mã ngân hàng (3 chữ số, xem bảng bên dưới)
`account_number`	string	Có	Số tài khoản ngân hàng (10-20 chữ số)
`account_holder_name`	string	Có	Tên chủ tài khoản (1-100 ký tự)
`description`	string	Không	Mô tả chuyển khoản (tối đa 255 ký tự)
`webhook_url`	string	Không	URL webhook để nhận thông báo chuyển khoản

Mã ngân hàng

Mã	Tên tiếng Thái	Tên tiếng Anh
`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

Rút tiền qua PromptPay

Khi sử dụng bank_code: "PROMPTPAY", trường account_number cần chứa:

Độ dài số tài khoản	Loại Proxy	Mô tả
10 chữ số	MOBILE	Số điện thoại di động
13 chữ số	TXID	Số CMND/CCCD hoặc Mã số thuế

Ví dụ yêu cầu (PromptPay với Số điện thoại):

json

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

Ví dụ yêu cầu (PromptPay với Số CMND/CCCD):

json

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

Ví dụ yêu cầu

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

Phản hồi

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

Lấy thông tin Thanh toán

Lấy thông tin chi tiết thanh toán theo ID thanh toán.

GET /v1/payments/{id}

Tham số đường dẫn

Tham số	Kiểu	Mô tả
`id`	string	ID Thanh toán (định dạng UUID)

Ví dụ phản hồi

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

Hủy Thanh toán

Hủy một thanh toán đang chờ xử lý. Chỉ có thể hủy các thanh toán có trạng thái pending.

POST /v1/payments/{id}/cancel

Tham số đường dẫn

Tham số	Kiểu	Mô tả
`id`	string	ID Thanh toán cần hủy

Ví dụ phản hồi

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

Trạng thái Thanh toán

Trạng thái	Mô tả
`pending`	Thanh toán đã tạo, đang chờ khách hàng thực hiện
`processing`	Thanh toán đang được xử lý
`completed`	Thanh toán hoàn thành thành công
`failed`	Thanh toán thất bại (bao gồm cả giao dịch hết hạn)
`cancelled`	Thanh toán đã bị hủy
`refunded`	Thanh toán đã được hoàn tiền

Lưu ý

Khi thanh toán hết hạn (khách hàng không thanh toán trong thời gian quy định), trạng thái sẽ chuyển sang failed với lý do thất bại là "Transaction expired". Một webhook sẽ được gửi để thông báo cho hệ thống của bạn.

Webhooks

Khi bạn cung cấp webhook_url, chúng tôi sẽ gửi các yêu cầu POST với các cập nhật thanh toán.

Nội dung Webhook

Nội dung webhook được gửi trực tiếp (không bọc trong cấu trúc sự kiện):

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

Các trường nội dung Webhook

Trường	Kiểu	Mô tả
`id`	string	ID giao dịch
`type`	string	Loại giao dịch: `deposit` hoặc `withdraw`
`amount`	number	Số tiền thanh toán gốc
`fee`	number	Phí xử lý được tính
`netAmount`	number	Số tiền sau khi trừ phí
`bankAccountNo`	string	Số tài khoản ngân hàng (cho deposit có thông tin người trả)
`bankAccountName`	string	Tên chủ tài khoản ngân hàng
`bankCode`	string	Mã ngân hàng
`bankName`	string	Tên ngân hàng bằng tiếng Thái
`currency`	string	Mã tiền tệ
`referenceNo`	string	ID tham chiếu của bạn
`status`	string	`success`, `failed`, hoặc `expired`
`timestamp`	string	Thời gian gửi webhook (ISO 8601)
`paidAt`	string	Thời gian hoàn thành thanh toán (trống nếu chưa thanh toán)

Giá trị trạng thái Webhook

Trạng thái	Mô tả
`success`	Thanh toán hoàn thành thành công
`failed`	Thanh toán thất bại hoặc hết hạn
`expired`	Thanh toán hết hạn (cũ, hiện dùng failed)

Chính sách thử lại Webhook

Webhook được thử lại tối đa 5 lần nếu việc gửi thất bại
Khoảng cách thử lại: 1 phút giữa các lần thử
Gửi thành công là bất kỳ phản hồi HTTP 2xx nào
Sau 5 lần thất bại, webhook được đánh dấu là thất bại

Xác minh Webhook

Các yêu cầu webhook bao gồm các headers để xác minh:

Header	Mô tả
`X-Webhook-Signature`	Chữ ký HMAC-SHA256 của nội dung yêu cầu
`X-Webhook-Timestamp`	Unix timestamp của webhook
`Content-Type`	`application/json`

Xác minh webhook sử dụng phương pháp HMAC giống như các yêu cầu 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)

Phản hồi lỗi

Tất cả các lỗi theo định dạng này:

json

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

Mã trạng thái HTTP

Trạng thái	Mô tả
`200`	Thành công
`201`	Tạo thành công
`400`	Yêu cầu sai - tham số không hợp lệ
`401`	Không được phép - API key hoặc chữ ký không hợp lệ
`403`	Bị cấm - merchant không hoạt động hoặc không đủ quyền
`404`	Không tìm thấy
`409`	Xung đột - reference_id bị trùng
`500`	Lỗi máy chủ nội bộ
`504`	Hết thời gian gateway

Mã lỗi

Mã	Mô tả
`INVALID_REQUEST`	Xác thực nội dung yêu cầu thất bại
`MISSING_API_KEY`	Thiếu header X-API-Key
`MISSING_SIGNATURE`	Thiếu header X-Signature
`MISSING_TIMESTAMP`	Thiếu header X-Timestamp
`INVALID_API_KEY`	API key không hợp lệ
`INVALID_SIGNATURE`	Xác minh chữ ký thất bại
`INVALID_TIMESTAMP`	Định dạng timestamp không hợp lệ
`TIMESTAMP_EXPIRED`	Timestamp yêu cầu nằm ngoài khung thời gian hợp lệ
`MERCHANT_INACTIVE`	Tài khoản merchant không hoạt động
`PAYMENT_NOT_FOUND`	Không tìm thấy thanh toán
`PAYMENT_ERROR`	Lỗi xử lý thanh toán chung
`DUPLICATE_REFERENCE`	ID tham chiếu đã tồn tại
`INSUFFICIENT_BALANCE`	Không đủ số dư để rút tiền
`INVALID_BANK_CODE`	Mã ngân hàng không hợp lệ
`INVALID_ACCOUNT`	Tài khoản ngân hàng không hợp lệ (sandbox)
`PAYMENT_CANNOT_BE_CANCELLED`	Không thể hủy thanh toán
`TIMEOUT`	Yêu cầu hết thời gian

Thử nghiệm Sandbox

Sandbox hoạt động như thế nào

Chế độ sandbox được xác định bởi loại merchant của bạn, không phải URL riêng biệt. Cả merchant sandbox và production đều sử dụng cùng một API endpoint:

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

Merchant Sandbox: Giao dịch được lưu trong cơ sở dữ liệu sandbox. Không xử lý tiền thật.
Merchant Production: Giao dịch được lưu trong cơ sở dữ liệu production và xử lý thông qua các nhà cung cấp thanh toán.

Liên hệ hỗ trợ để yêu cầu thông tin xác thực sandbox để thử nghiệm.

Số tiền thử nghiệm

Trong chế độ sandbox, các số tiền cụ thể sẽ kích hoạt các hành vi khác nhau:

Số tiền	Tiền tệ	Hành vi	Mô tả
`100.00`	THB	`auto_approve`	Thanh toán hoàn thành ngay lập tức
`200.00`	THB	`auto_pending`	Thanh toán giữ trạng thái pending (mô phỏng trễ)
`500.00`	THB	`auto_approve`	Thanh toán hoàn thành ngay lập tức
`888.88`	THB	`timeout`	Thanh toán hết thời gian
`999.99`	THB	`auto_fail`	Thanh toán thất bại ngay lập tức
`1000.00`	THB	`auto_approve`	Thanh toán hoàn thành ngay lập tức
Khác	THB	`pending`	Luồng thanh toán bình thường

Kịch bản thử nghiệm

Bạn có thể ghi đè hành vi bằng header X-Sandbox-Scenario:

Kịch bản	Mô tả
`auto_approve`	Bắt buộc thanh toán hoàn thành ngay lập tức
`auto_fail`	Bắt buộc thanh toán thất bại
`auto_pending`	Bắt buộc thanh toán giữ trạng thái pending
`timeout`	Mô phỏng hết thời gian
`invalid_account`	Mô phỏng tài khoản ngân hàng không hợp lệ (chỉ withdraw)

Ví dụ:

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

Header phản hồi

Phản hồi bao gồm header chỉ ra môi trường:

Header	Giá trị	Mô tả
`X-Environment`	`sandbox` hoặc `production`	Chỉ ra loại merchant

Hết hạn Giao dịch

Giao dịch deposit có thời gian hết hạn mặc định là 15 phút
Nếu khách hàng không thanh toán trong thời gian này:
- Trạng thái chuyển sang failed (không phải expired)
- failure_reason được đặt là "Transaction expired"
- Webhook được gửi với status: "failed"
Kiểm tra hết hạn chạy mỗi 1 phút

Giới hạn Tốc độ

Endpoint	Giới hạn Tốc độ
Tất cả endpoint	100 yêu cầu/phút
Tạo Deposit	30 yêu cầu/phút
Tạo Withdraw	20 yêu cầu/phút

Các header giới hạn tốc độ được bao gồm trong phản hồi:

Header	Mô tả
`X-RateLimit-Limit`	Số yêu cầu tối đa trong khung thời gian
`X-RateLimit-Remaining`	Số yêu cầu còn lại trong khung thời gian
`X-RateLimit-Reset`	Unix timestamp khi giới hạn được đặt lại

Hỗ trợ

Để được hỗ trợ kỹ thuật:

Email: [email protected]
Tài liệu: https://docs.facaiqq.com
Trang trạng thái: https://gateway.facaiqq.com

Tài liệu Public API ​

Môi trường ​

Tổng quan ​

Production vs Sandbox ​

Xác thực ​

Tạo chữ ký ​

Ví dụ mã nguồn ​

Endpoints ​

Tạo Deposit ​

Nội dung yêu cầu ​

Ví dụ yêu cầu ​

Phản hồi ​

Các trường phản hồi ​

Tạo Withdraw ​

Nội dung yêu cầu ​

Mã ngân hàng ​

Rút tiền qua PromptPay ​

Ví dụ yêu cầu ​

Phản hồi ​

Lấy thông tin Thanh toán ​

Tham số đường dẫn ​

Ví dụ phản hồi ​

Hủy Thanh toán ​

Tham số đường dẫn ​

Ví dụ phản hồi ​

Trạng thái Thanh toán ​

Webhooks ​

Nội dung Webhook ​

Các trường nội dung Webhook ​

Giá trị trạng thái Webhook ​

Chính sách thử lại Webhook ​

Xác minh Webhook ​

Phản hồi lỗi ​

Mã trạng thái HTTP ​

Mã lỗi ​

Thử nghiệm Sandbox ​

Sandbox hoạt động như thế nào ​

Số tiền thử nghiệm ​

Kịch bản thử nghiệm ​

Header phản hồi ​

Hết hạn Giao dịch ​

Giới hạn Tốc độ ​

Hỗ trợ ​

Tài liệu Public API

Môi trường

Tổng quan

Production vs Sandbox

Xác thực

Tạo chữ ký

Ví dụ mã nguồn

Endpoints

Tạo Deposit

Nội dung yêu cầu

Ví dụ yêu cầu

Phản hồi

Các trường phản hồi

Tạo Withdraw

Nội dung yêu cầu

Mã ngân hàng

Rút tiền qua PromptPay

Ví dụ yêu cầu

Phản hồi

Lấy thông tin Thanh toán

Tham số đường dẫn

Ví dụ phản hồi

Hủy Thanh toán

Tham số đường dẫn

Ví dụ phản hồi

Trạng thái Thanh toán

Webhooks

Nội dung Webhook

Các trường nội dung Webhook

Giá trị trạng thái Webhook

Chính sách thử lại Webhook

Xác minh Webhook

Phản hồi lỗi

Mã trạng thái HTTP

Mã lỗi

Thử nghiệm Sandbox

Sandbox hoạt động như thế nào

Số tiền thử nghiệm

Kịch bản thử nghiệm

Header phản hồi

Hết hạn Giao dịch

Giới hạn Tốc độ

Hỗ trợ