Chuyển tiền

Hướng dẫn này giải thích cách chuyển tiền từ ví của bạn đến các địa chỉ bên ngoài.

Yêu cầu rút tiền

POST

/wallets/{wallet_id}/request-withdrawal

Tạo một yêu cầu rút tiền mới từ ví. Lệnh rút tiền sẽ cần được phê duyệt bởi những người dùng có thẩm quyền.

Header

Name
X-Idempotency-Key
Type
header
Recommended
recommended
Description
Một UUID định danh lệnh rút tiền này để nó chỉ được xử lý một lần. Nếu cùng một key được gửi lại trong vòng 24 giờ, response đã lưu cache từ request ban đầu sẽ được trả về thay vì tạo một lệnh rút tiền trùng lặp.
Hãy gắn key này với lệnh rút tiền trong hệ thống của bạn: dùng ID rút tiền hoặc ID chuyển tiền nội bộ nếu đó là UUID, nếu không hãy tạo một UUID một lần khi bạn tạo bản ghi đó và lưu kèm theo. Gửi cùng một key trong mọi lần thử lại. Không tạo key mới cho mỗi lần thử, vì mỗi key mới sẽ được coi là một lệnh rút tiền mới.

Tham số

Name
asset_id
Type
string
Required
required
Description
UUID của tài sản cần rút.
Name
amount
Type
string
Required
required
Description
Số tiền cần rút ở định dạng chuỗi thập phân.
Name
recipient_address
Type
string
Required
required
Description
Địa chỉ blockchain nhận tiền.

Response

Name
id
Type
string
Description
UUID của yêu cầu rút tiền.
Name
status
Type
string
Description
Trạng thái hiện tại của lệnh rút tiền:
- PENDING_APPROVAL: Đang chờ phê duyệt từ những người dùng có thẩm quyền
- PENDING: Đã được phê duyệt và đang chờ xử lý
- EXECUTED: Giao dịch đã được gửi lên blockchain
- SUCCESS: Giao dịch đã được xác nhận trên blockchain
- REJECTED: Lệnh rút tiền đã bị người phê duyệt từ chối
- FAILED: Giao dịch thực thi thất bại
Name
wallet_id
Type
string
Description
UUID của ví nguồn.
Name
asset_id
Type
string
Description
UUID của tài sản được rút.
Name
amount
Type
string
Description
Số tiền rút.
Name
recipient_address
Type
string
Description
Địa chỉ blockchain đích.
Name
creator_id
Type
string
Description
UUID của người dùng đã tạo yêu cầu rút tiền.
Name
withdrawal_approvals
Type
array
Description
Danh sách trạng thái phê duyệt từ những người dùng có thẩm quyền.
Name
created_at
Type
string
Description
Thời điểm yêu cầu được tạo.
Name
updated_at
Type
string
Description
Thời điểm cập nhật trạng thái gần nhất.

Quy trình rút tiền diễn ra theo luồng sau:

PENDING_APPROVAL → Đang chờ các phê duyệt cần thiết
PENDING → Đã được phê duyệt và xếp hàng chờ xử lý
EXECUTED → Giao dịch đã được gửi lên blockchain
SUCCESS → Giao dịch đã được xác nhận

Hoặc nếu bị từ chối/thất bại:

REJECTED → Người phê duyệt đã từ chối lệnh rút tiền
FAILED → Giao dịch thực thi thất bại

Request

POST

/wallets/:wallet_id/request-withdrawal

import { FystackSDK, Environment } from "@fystack/sdk"
  
const apiCredentials = {
  apiKey: process.env.API_KEY,
  apiSecret: process.env.API_SECRET
}

const sdk = new FystackSDK({
  credentials: apiCredentials,
  environment: Environment.Sandbox,
  logger: true
})

const response = await sdk.requestWithdrawal(
  "e0851607-417a-475a-b399-5f3aa262b81d",
  {
    assetId: "f1be472d-1338-43ff-b547-06faba7ecce7",
    amount: "0.001",
    recipientAddress: "0xe6EBF81E9C225BbCEa9b5399E0D0d0f29f30f119"
  }
)

Response

200

{
  "success": true,
  "message": "success",
  "code": 0,
  "data": {
    "id": "0de79230-a820-4bd4-b020-883d395faa87",
    "wallet_id": "e0851607-417a-475a-b399-5f3aa262b81d",
    "asset_id": "f1be472d-1338-43ff-b547-06faba7ecce7",
    "amount": "1000",
    "recipient_address": "0x7c2BbE2e02af09F1cf9aFd4A79EC201DC841675a",
    "status": "PENDING_APPROVAL",
    "creator_id": "075243c1-962e-4803-83da-d73c78b8b060",
    "withdrawal_approvals": [
      {
        "id": "9a85c312-7d3b-4c6f-9f4e-123456789abc",
        "withdrawal_id": "0de79230-a820-4bd4-b020-883d395faa87",
        "user_id": "075243c1-962e-4803-83da-d73c78b8b060",
        "status": "PENDING",
        "created_at": "2025-08-11T17:37:29.815148+07:00",
        "updated_at": "2025-08-11T17:37:29.815148+07:00"
      },
      {
        "id": "8b74d123-9e5f-4a2d-8c3b-987654321def",
        "withdrawal_id": "0de79230-a820-4bd4-b020-883d395faa87",
        "user_id": "165243c1-962e-4803-83da-d73c78b8b070",
        "status": "APPROVED",
        "created_at": "2025-08-11T17:37:29.815148+07:00",
        "updated_at": "2025-08-11T17:38:15.623147+07:00"
      }
    ],
    "created_at": "2025-08-11T17:37:29.815148+07:00",
    "updated_at": "2025-08-11T17:37:29.815148+07:00"
  }
}

Lấy trạng thái rút tiền

GET

/wallets/{wallet_id}/withdrawals/{withdrawal_id}

Lấy trạng thái hiện tại của một yêu cầu rút tiền.

Response

Name
success
Type
boolean
Description
Cho biết request có thành công hay không.
Name
data
Type
object
Description
Chứa thông tin chi tiết về lệnh rút tiền.

Name: id
Type: string
Description: UUID của yêu cầu rút tiền.

Name: status
Type: string
Description: Trạng thái hiện tại của lệnh rút tiền.

Name: amount
Type: string
Description: Số tiền rút.

Name: recipient_address
Type: string
Description: Địa chỉ blockchain đích.

Name: creator
Type: object
Description: Thông tin về người dùng đã tạo lệnh rút tiền.

Name: asset
Type: object
Description: Thông tin chi tiết về tài sản được rút.

Name: transaction
Type: object
Description: Thông tin chi tiết đầy đủ của giao dịch sau khi được thực thi.

Request

GET

/wallets/:wallet_id/withdrawals/:withdrawal_id

import { FystackSDK, Environment } from "@fystack/sdk"
  
const apiCredentials = {
  apiKey: process.env.API_KEY,
  apiSecret: process.env.API_SECRET
}

const sdk = new FystackSDK({
  credentials: apiCredentials,
  environment: Environment.Sandbox,
  logger: true
})

// Get withdrawal status
const withdrawal = await sdk.getWithdrawalStatus(
  "e0851607-417a-475a-b399-5f3aa262b81d",
  "4cebc6c3-1e46-4166-ab59-86a59971215f"
)

// Check withdrawal status
if (withdrawal.status === 'SUCCESS') {
  console.log('Transaction hash:', withdrawal.transaction.tx_hash)
  console.log('Amount:', withdrawal.amount)
  console.log('Asset:', withdrawal.asset.symbol)
}

// Check approval status
const approvals = withdrawal.withdrawal_approvals
const pendingApprovals = approvals.filter(a => a.status === 'PENDING')
const approvedCount = approvals.filter(a => a.status === 'APPROVED').length

console.log('Pending approvals:', pendingApprovals.length)
console.log('Approved count:', approvedCount)

Response

200

{
  "success": true,
  "message": "success",
  "code": 0,
  "data": {
    "id": "4cebc6c3-1e46-4166-ab59-86a59971215f",
    "created_at": "2025-07-29T21:44:23.763113+07:00",
    "updated_at": "2025-07-29T21:45:07.204964+07:00",
    "amount": "0.000001622515351558",
    "status": "SUCCESS",
    "recipient_address": "0xf2acfF1D9d576E9b8B7C7d58A449F599A9A54edA",
    "creator_id": "075243c1-962e-4803-83da-d73c78b8b060",
    "creator": {
      "id": "075243c1-962e-4803-83da-d73c78b8b060",
      "username": "Dev team"
    },
    "asset_id": "a469642e-5466-4d69-834d-537f33ee5c81",
    "asset": {
      "id": "a469642e-5466-4d69-834d-537f33ee5c81",
      "name": "Ethereum Sepolia",
      "symbol": "ETH",
      "decimals": 18,
      "logo_url": "https://icons.iconarchive.com/icons/cjdowner/cryptocurrency-flat/512/Ethereum-ETH-icon.png",
      "is_native": true,
      "address_type": "evm",
      "network_id": "23d13c03-1f3c-4e2a-9aef-1771a244b7f6"
    },
    "withdrawal_approvals": [
      {
        "id": "dfa94b32-83f5-4808-8091-9a3c270d4f1d",
        "status": "PENDING",
        "user": {
          "username": "Thi Nguyen",
          "email": "nguyendanganhthi247@gmail.com"
        }
      },
      {
        "id": "776303fd-762e-4593-9f66-93631dd226e0",
        "status": "APPROVED",
        "user": {
          "username": "Dev team",
          "email": "devteam@fystack.io"
        }
      }
    ],
    "transaction": {
      "tx_hash": "0xa1ec8bab32baebad1211e838d655777640e78102b39b008bd00a8b3e5d1f3c00",
      "status": "confirmed",
      "block_number": 8868747,
      "from_address": "0xA793457d84CFD255Ed68295984300C4f799E759F",
      "to_address": "0xf2acfF1D9d576E9b8B7C7d58A449F599A9A54edA",
      "amount": "0.000001622515351558",
      "tx_fee": "0.000001296799854",
      "price_native_token": "3808.475025265875",
      "direction": "out",
      "type": "withdrawal",
      "method": "transfer"
    }
  }
}