Transferencias

Esta guía explica cómo transferir fondos desde tus billeteras a direcciones externas.

Solicitar un retiro

POST

/wallets/{wallet_id}/request-withdrawal

Crea una nueva solicitud de retiro desde una billetera. El retiro requerirá la aprobación de usuarios autorizados.

Headers

Name
X-Idempotency-Key
Type
header
Recommended
recommended
Description
Un UUID que identifica este retiro para que se procese una sola vez. Si se vuelve a enviar la misma clave dentro de las 24 horas, se devuelve la respuesta almacenada en caché de la solicitud original en lugar de crear un retiro duplicado.
Vincula la clave al retiro en tu propio sistema: usa tu ID interno de retiro o transferencia si es un UUID; de lo contrario, genera un UUID una sola vez al crear ese registro y guárdalo junto a él. Envía la misma clave en cada reintento. No generes una clave nueva por intento, porque cada clave nueva se trata como un retiro nuevo.

Parámetros

Name
asset_id
Type
string
Required
required
Description
El UUID del activo que se va a retirar.
Name
amount
Type
string
Required
required
Description
El monto a retirar, como string en formato decimal.
Name
recipient_address
Type
string
Required
required
Description
La dirección blockchain a la que se enviarán los fondos.

Respuesta

Name
id
Type
string
Description
El UUID de la solicitud de retiro.
Name
status
Type
string
Description
Estado actual del retiro:
- PENDING_APPROVAL: a la espera de las aprobaciones de los usuarios autorizados
- PENDING: aprobado y a la espera de ser procesado
- EXECUTED: la transacción se envió a la blockchain
- SUCCESS: la transacción se confirmó en la blockchain
- REJECTED: un aprobador rechazó el retiro
- FAILED: la transacción no se pudo ejecutar
Name
wallet_id
Type
string
Description
El UUID de la billetera de origen.
Name
asset_id
Type
string
Description
El UUID del activo que se retira.
Name
amount
Type
string
Description
El monto del retiro.
Name
recipient_address
Type
string
Description
La dirección blockchain de destino.
Name
creator_id
Type
string
Description
El UUID del usuario que creó la solicitud de retiro.
Name
withdrawal_approvals
Type
array
Description
Lista de los estados de aprobación de los usuarios autorizados.
Name
created_at
Type
string
Description
Marca de tiempo de la creación de la solicitud.
Name
updated_at
Type
string
Description
Marca de tiempo de la última actualización de estado.

El proceso de retiro sigue este flujo:

PENDING_APPROVAL → a la espera de las aprobaciones requeridas
PENDING → aprobado y en cola para su procesamiento
EXECUTED → transacción enviada a la blockchain
SUCCESS → transacción confirmada

O, si se rechaza o falla:

REJECTED → un aprobador rechazó el retiro
FAILED → la transacción no se pudo ejecutar

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

Obtener el estado de un retiro

GET

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

Obtén el estado actual de una solicitud de retiro.

Respuesta

Name
success
Type
boolean
Description
Indica si la solicitud se realizó correctamente.
Name
data
Type
object
Description
Contiene los detalles del retiro.

Name: id
Type: string
Description: El UUID de la solicitud de retiro.

Name: status
Type: string
Description: Estado actual del retiro.

Name: amount
Type: string
Description: El monto del retiro.

Name: recipient_address
Type: string
Description: La dirección blockchain de destino.

Name: creator
Type: object
Description: Información sobre el usuario que creó el retiro.

Name: asset
Type: object
Description: Detalles del activo que se retira.

Name: transaction
Type: object
Description: Detalles completos de la transacción una vez ejecutada.

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