Account Management

This API set is designed for client initialization, webhook registration, master bank account registration, and bank account creation.

Account Overview

Quick Reference

Endpoint	Method	Description
`/api/v1/master-bank-accounts`	GET	List all master bank accounts
`/api/v1/master-bank-accounts?id=&account_number=`	GET	Get specific master bank account
`/api/v1/bank-accounts`	POST	Create a new bank account
`/api/v1/bank-accounts`	GET	List bank accounts (filter: `id`, `account_number`)
`/api/v1/bank-accounts/:id`	GET	Get specific bank account

Setup Guide

1. Create Client ID & Secret Key

Go to book.finan.one/setting, select Open API

Open API Settings

Click "Create Client"

Create Client

Enter client name and confirm

Client Form

Save your client_id and secret_key

Success

Important

Save both credentials immediately. You cannot retrieve the secret_key after closing this popup.

2. Register Webhook

Go to book.finan.one/setting/open-api
Select your client and enter Webhook URL
Set Status to "Activate" and confirm

Webhook Settings

Webhook Form

3. Register Master Bank Account

Currently supported banks:

Bank	Status	Setup
MB Bank	✅ Available	Self-service via portal
Shinhan Bank	✅ Available	Contact support
Galaxy Pay	✅ Available	Contact support
BIDV	🔜 Coming soon	-

For MB Bank: Go to book.finan.one/cash-and-bank/fund → Add Account → Bank → MB Bank

Add Account MB Bank Bank Form

API Endpoints

Get Master Bank Accounts

Retrieve all master bank accounts, or filter by query parameters to get a specific one.

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

Query Parameters

Parameter	Type	Description
`id`	uuid	Filter by master bank account ID
`account_number`	string	Filter by account number

Signature Must Include Query String

When using query parameters, the signature path must include the full query string:

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

cURL
Go

# 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'

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

Response

✅ Success (200)
❌ Error

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

Code	Message	Description
401	`Unauthorized`	Invalid or missing authentication
403	`Forbidden`	IP not whitelisted
500	`Internal Server Error`	Server error, retry later

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

Response Fields

Field	Type	Description
`account_id`	uuid	Unique identifier for the master bank account
`account_number`	string	Masked account number (e.g., `1234XXXX5678`)
`account_name`	string	Account holder name as registered with bank
`bank_code`	string	Bank identifier (e.g., `SHB`, `MB`)
`qr_code`	string	URL for QR code image
`balance`	number	Current balance in smallest currency unit
`currency`	string	ISO currency code (e.g., `VND`)
`status`	string	`active` or `inactive`
`created_at`	datetime	ISO 8601 timestamp

Create Bank Account

Create a new bank account under a master account for payment operations.

POST /api/v1/bank-accounts

cURL
Go

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

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

Request Body

Field	Type	Required	Description	Example
`master_account_id`	uuid	✅	ID of the parent master account	`550e8400-...`
`account_name`	string	✅	Display name for the account	`KE TOAN`

Response

✅ Success (200)
❌ Error

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

Code	Message	Description
400	`Bad Request`	Invalid request body
401	`Unauthorized`	Invalid authentication
404	`Not Found`	Master account not found
422	`Unprocessable Entity`	Validation failed

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

info

The qr_code URL can be displayed to receive payments. Webhook notifications will be sent when payments are received.

Get Bank Accounts

Retrieve all bank accounts for the authenticated client.

GET /api/v1/bank-accounts

cURL
Go

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'

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

Response

✅ Success (200)
❌ Error

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

Code	Message	Description
401	`Unauthorized`	Invalid authentication
500	`Internal Server Error`	Server error

tip

To get a specific bank account:

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

Next Steps

Generate Signature - Learn how to authenticate API requests
Payment Gateway - Process payments using your bank accounts
Payout - Send payouts to other banks

Quick Reference​

Setup Guide​

1. Create Client ID & Secret Key​

2. Register Webhook​

3. Register Master Bank Account​

API Endpoints​

Get Master Bank Accounts​

Query Parameters​

Response​

Response Fields​

Create Bank Account​

Request Body​

Response​

Get Bank Accounts​

Response​

Next Steps​

Quick Reference

Setup Guide

1. Create Client ID & Secret Key

2. Register Webhook

3. Register Master Bank Account

API Endpoints

Get Master Bank Accounts

Query Parameters

Response

Response Fields

Create Bank Account

Request Body

Response

Get Bank Accounts

Response

Next Steps