Quản lý tài khoản

Bộ API này được thiết kế để khởi tạo client, đăng ký webhook, đăng ký tài khoản ngân hàng chính và tạo tài khoản ngân hàng.

Tham chiếu nhanh

Endpoint	Phương thức	Mô tả
/api/v1/master-bank-accounts	GET	Liệt kê tất cả tài khoản ngân hàng chính
/api/v1/master-bank-accounts?id=&account_number=	GET	Lấy tài khoản ngân hàng chính cụ thể
/api/v1/bank-accounts	POST	Tạo tài khoản ngân hàng mới
/api/v1/bank-accounts	GET	Liệt kê tài khoản ngân hàng (bộ lọc: id, account_number)
/api/v1/bank-accounts/:id	GET	Lấy tài khoản ngân hàng cụ thể

---

Hướng dẫn cài đặt

1. Tạo Client ID & Secret Key

1. Truy cập book.finan.one/setting, chọn Open API

2. Nhấn "Create Client"

3. Nhập tên client và xác nhận

4. Lưu lại client_id và secret_key của bạn

Quan trọng

Lưu cả hai thông tin xác thực ngay lập tức. Bạn không thể lấy lại secret_key sau khi đóng popup này.

2. Đăng ký Webhook

1. Truy cập book.finan.one/setting/open-api
2. Chọn client của bạn và nhập Webhook URL
3. Đặt Trạng thái thành "Activate" và xác nhận

3. Đăng ký tài khoản ngân hàng chính

Các ngân hàng hiện được hỗ trợ:

Ngân hàng	Trạng thái	Cài đặt
MB Bank	✅ Khả dụng	Tự đăng ký qua cổng thông tin
Shinhan Bank	✅ Khả dụng	Liên hệ hỗ trợ
Galaxy Pay	✅ Khả dụng	Liên hệ hỗ trợ
BIDV	🔜 Sắp ra mắt	-

Đối với MB Bank: Truy cập book.finan.one/cash-and-bank/fund → Thêm tài khoản → Ngân hàng → MB Bank

---

API Endpoints

Lấy danh sách tài khoản ngân hàng chính

Truy xuất tất cả tài khoản ngân hàng chính, hoặc lọc theo tham số truy vấn để lấy một tài khoản cụ thể.

GET /api/v1/master-bank-accounts
GET /api/v1/master-bank-accounts?id=&account_number=

Tham số truy vấn

Tham số	Kiểu	Mô tả
id	uuid	Lọc theo ID tài khoản ngân hàng chính
account_number	string	Lọc theo số tài khoản

Chữ ký phải bao gồm chuỗi truy vấn

Khi sử dụng tham số truy vấn, đường dẫn chữ ký phải bao gồm toàn bộ chuỗi truy vấn:

signature_path = "/api/v1/master-bank-accounts?id=xxx&account_number=0933450210"

cURL

# List all
curl -X GET 'https://api.finan.one/open/api/v1/master-bank-accounts' \
  -H 'Content-Type: application/json' \
  -H 'x-client-id: YOUR_CLIENT_ID' \
  -H 'x-signature: YOUR_SIGNATURE' \
  -H 'x-timestamp: 1699999999'

# Filter by ID
curl -X GET 'https://api.finan.one/open/api/v1/master-bank-accounts?id=9c028f93-89f9-4cf5-a2fb-fb8fa8580fe5' \
  -H 'Content-Type: application/json' \
  -H 'x-client-id: YOUR_CLIENT_ID' \
  -H 'x-signature: YOUR_SIGNATURE' \
  -H 'x-timestamp: 1699999999'

# Filter by account number
curl -X GET 'https://api.finan.one/open/api/v1/master-bank-accounts?account_number=0933450210' \
  -H 'Content-Type: application/json' \
  -H 'x-client-id: YOUR_CLIENT_ID' \
  -H 'x-signature: YOUR_SIGNATURE' \
  -H 'x-timestamp: 1699999999'

Go

package main

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

func generateSignature(secretKey, method, path, payload, timestamp string) string {
    message := secretKey + "_" + method + "_" + path + "_" + payload + "_" + timestamp
    hash := sha256.Sum256([]byte(message))
    return hex.EncodeToString(hash[:])
}

func main() {
    clientID := "YOUR_CLIENT_ID"
    secretKey := "YOUR_SECRET_KEY"
    timestamp := strconv.FormatInt(time.Now().Unix(), 10)

    // Include query string in signature path
    path := "/api/v1/master-bank-accounts?id=9c028f93-89f9-4cf5-a2fb-fb8fa8580fe5"
    signature := generateSignature(secretKey, "GET", path, "", timestamp)

    req, _ := http.NewRequest("GET", "https://api.finan.one/open"+path, nil)
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("x-client-id", clientID)
    req.Header.Set("x-signature", signature)
    req.Header.Set("x-timestamp", timestamp)

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

    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}

Phản hồi

✅ Success (200)

{
  "message": { "content": "Thực thi API thành công" },
  "code": 102000,
  "request_id": "abc123...",
  "data": [
    {
      "account_id": "550e8400-e29b-41d4-a716-446655440000",
      "account_number": "1234XXXX5678",
      "account_name": "COMPANY ABC",
      "bank_code": "SHB",
      "qr_code": "https://api.finan.one/qr/abc123",
      "balance": 15000000,
      "currency": "VND",
      "status": "active",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
}

❌ Error

Mã	Thông báo	Mô tả
401	Unauthorized	Xác thực không hợp lệ hoặc thiếu
403	Forbidden	IP không nằm trong danh sách cho phép
500	Internal Server Error	Lỗi máy chủ, thử lại sau

{
  "message": {
    "content": "Yêu cầu không hợp lệ",
    "error": "Invalid signature"
  },
  "code": 104000,
  "request_id": "abc123..."
}

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

Trường	Kiểu	Mô tả
account_id	uuid	Định danh duy nhất của tài khoản ngân hàng chính
account_number	string	Số tài khoản đã che (ví dụ: 1234XXXX5678)
account_name	string	Tên chủ tài khoản đã đăng ký với ngân hàng
bank_code	string	Mã định danh ngân hàng (ví dụ: SHB, MB)
qr_code	string	URL hình ảnh mã QR
balance	number	Số dư hiện tại theo đơn vị tiền tệ nhỏ nhất
currency	string	Mã tiền tệ ISO (ví dụ: VND)
status	string	active hoặc inactive
created_at	datetime	Dấu thời gian ISO 8601

---

Tạo tài khoản ngân hàng

Tạo tài khoản ngân hàng mới dưới tài khoản chính để thực hiện các thao tác thanh toán.

POST /api/v1/bank-accounts

cURL

curl -X POST 'https://api.finan.one/open/api/v1/bank-accounts' \
  -H 'Content-Type: application/json' \
  -H 'x-client-id: YOUR_CLIENT_ID' \
  -H 'x-signature: YOUR_SIGNATURE' \
  -H 'x-timestamp: 1699999999' \
  -d '{
    "master_account_id": "550e8400-e29b-41d4-a716-446655440000",
    "account_name": "KE TOAN"
  }'

Go

package main

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

type CreateBankAccountRequest struct {
    MasterAccountID string `json:"master_account_id"`
    AccountName     string `json:"account_name"`
}

func generateSignature(secretKey, method, path, payload, timestamp string) string {
    message := secretKey + "_" + method + "_" + path + "_" + payload + "_" + timestamp
    hash := sha256.Sum256([]byte(message))
    return hex.EncodeToString(hash[:])
}

func main() {
    clientID := "YOUR_CLIENT_ID"
    secretKey := "YOUR_SECRET_KEY"
    timestamp := strconv.FormatInt(time.Now().Unix(), 10)

    reqBody := CreateBankAccountRequest{
        MasterAccountID: "550e8400-e29b-41d4-a716-446655440000",
        AccountName:     "KE TOAN",
    }

    jsonBody, _ := json.Marshal(reqBody)
    signature := generateSignature(secretKey, "POST", "/api/v1/bank-accounts", string(jsonBody), timestamp)

    req, _ := http.NewRequest("POST", "https://api.finan.one/open/api/v1/bank-accounts", bytes.NewBuffer(jsonBody))
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("x-client-id", clientID)
    req.Header.Set("x-signature", signature)
    req.Header.Set("x-timestamp", timestamp)

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

    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}

Nội dung request

Trường	Kiểu	Bắt buộc	Mô tả	Ví dụ
master_account_id	uuid	✅	ID của tài khoản chính cha	550e8400-...
account_name	string	✅	Tên hiển thị cho tài khoản	KE TOAN

Phản hồi

✅ Success (200)

{
  "message": { "content": "Thực thi API thành công" },
  "code": 102001,
  "request_id": "abc123...",
  "data": {
    "bank_code": "MB",
    "account_id": "c3643c99-50ff-47ed-94d0-f6e7f9c6bae1",
    "account_name": "API TEST BANK ACC",
    "account_number": "VQRQAHZKN0048",
    "currency_code": "704",
    "master_account_name": "TRAN TU THIEN"
  }
}

❌ Error

Mã	Thông báo	Mô tả
400	Bad Request	Nội dung request không hợp lệ
401	Unauthorized	Xác thực không hợp lệ
404	Not Found	Không tìm thấy tài khoản chính
422	Unprocessable Entity	Xác thực dữ liệu thất bại

{
  "message": {
    "content": "Yêu cầu không hợp lệ",
    "error": "Master account does not exist"
  },
  "code": 104000,
  "request_id": "abc123..."
}

thông tin

URL qr_code có thể được hiển thị để nhận thanh toán. Thông báo webhook sẽ được gửi khi nhận được thanh toán.

---

Lấy danh sách tài khoản ngân hàng

Truy xuất tất cả tài khoản ngân hàng của client đã xác thực.

GET /api/v1/bank-accounts

cURL

curl -X GET 'https://api.finan.one/open/api/v1/bank-accounts' \
  -H 'Content-Type: application/json' \
  -H 'x-client-id: YOUR_CLIENT_ID' \
  -H 'x-signature: YOUR_SIGNATURE' \
  -H 'x-timestamp: 1699999999'

Go

package main

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

func generateSignature(secretKey, method, path, payload, timestamp string) string {
    message := secretKey + "_" + method + "_" + path + "_" + payload + "_" + timestamp
    hash := sha256.Sum256([]byte(message))
    return hex.EncodeToString(hash[:])
}

func main() {
    clientID := "YOUR_CLIENT_ID"
    secretKey := "YOUR_SECRET_KEY"
    timestamp := strconv.FormatInt(time.Now().Unix(), 10)

    signature := generateSignature(secretKey, "GET", "/api/v1/bank-accounts", "", timestamp)

    req, _ := http.NewRequest("GET", "https://api.finan.one/open/api/v1/bank-accounts", nil)
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("x-client-id", clientID)
    req.Header.Set("x-signature", signature)
    req.Header.Set("x-timestamp", timestamp)

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

    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}

Phản hồi

✅ Success (200)

{
  "message": { "content": "Thực thi API thành công" },
  "code": 102000,
  "request_id": "abc123...",
  "data": [
    {
      "account_id": "660e8400-e29b-41d4-a716-446655440001",
      "account_number": "9876XXXX5432",
      "account_name": "KE TOAN",
      "bank_code": "SHB",
      "qr_code": "https://api.finan.one/qr/xyz789",
      "balance": 5000000,
      "currency": "VND",
      "status": "active",
      "created_at": "2024-01-20T14:00:00Z"
    }
  ]
}

❌ Error

Mã	Thông báo	Mô tả
401	Unauthorized	Xác thực không hợp lệ
500	Internal Server Error	Lỗi máy chủ

mẹo

Để lấy một tài khoản ngân hàng cụ thể:

GET /api/v1/bank-accounts/:account_id

---

Bước tiếp theo

• Tạo chữ ký - Tìm hiểu cách xác thực các yêu cầu API
• Cổng thanh toán - Xử lý thanh toán bằng tài khoản ngân hàng của bạn
• Chi hộ - Gửi chi hộ đến các ngân hàng khác