Guides
英文/English中文/Chinese

钱包查询与链上提现

在 DogPay PAAS 体系中，当用户的支付订单完成清算后，资金将进入您的加密货币钱包（Crypto Wallet）。本指南将向您展示如何查询可用余额，并将资金提现至您指定的外部链上地址。

🔍 1. 查询钱包与可用余额 (Query Wallets)

在执行链上提现之前，您必须先获取对应钱包的唯一 id，并确认其可用余额（available）充足。

您可以调用 获取钱包列表接口 获取您的资产状态。

请求参数说明 该接口为 GET 请求，支持以下常用查询参数：

  • currency: 按币种筛选（例如 USDT, USDC）。
  • nickname: 按您创建钱包时设置的别名筛选。

📦 完整响应样例 响应的 data 数组中将包含您的钱包基础信息以及核心的 balance.available（可用余额）字段。

{
    "code": 0,
    "message": "success",
    "timestamp": 1712350000,
    "data": [
        {
            "id": "1234567890",
            "nickname": "USDT Wallet",
            "currency": "USDT",
            "balance": {
                "id": "bal_00123",
                "available": "5000.50"
            },
            "callId": "req_init_001"
        }
    ]
}

注：请妥善保存此处返回的钱包 id（例如 "1234567890"），它将作为后续提现接口的 cryptoWalletId 入参。

⛽ 2. 估算提现手续费 (Estimate Withdrawal Fee)

由于链上转账需要向区块链网络支付矿工费（Gas Fee），在正式发起提现前，我们建议您先调用 估算提现手续费接口 (POST /open-api/v1/crypto-wallet/withdraw-fee) 获取实时的网络费用估算。

📦 完整请求样例

{
    "cryptoWalletId": "1234567890",
    "currencyConfigId": "config_eth_usdt_001",
    "address": "0xB0a2821fAa9AD8c08D2764EAF85C414518137620",
    "amount": 1000.00
}

📦 完整响应样例

{
    "code": 0,
    "message": "success",
    "timestamp": 1712350500,
    "data": {
        "feeAmount": "2.50",
        "currency": "USDT",
        "estimateNetworkTime": 300
    }
}

🚀 3. 发起链上提现 (Initiate On-Chain Withdrawal)

确认余额与手续费无误后，您可以调用 发起提现接口 (POST /open-api/v1/crypto-wallet/withdraw) 将稳定币提取至您的外部冷钱包、交易所或用户的地址中。

📘

业务场景提示 (Business Use Cases)

提现接口不仅适用于商户日常的利润出金，当您需要处理用户的退单或退款请求时，同样可通过调用本接口，将对应的款项直接汇入用户的原支付地址，从而灵活、高效地完成资金的逆向退回。

🚧

KYT 风控合规提示 (KYT Risk Review)

在您发起提现时，可直接传入任何合法的外部链上地址。为保障合规与资金安全，DogPay 系统将实时对该目标地址进行 KYT (Know Your Transaction) 审查。若该地址命中高风险或黑产地址库，系统的风控引擎将拦截或冻结该笔提现请求。

🛠️ 核心请求参数说明

参数名必填描述说明
callId是您的业务系统生成的唯一请求 ID，用于保证提现请求的幂等性 (Idempotency)。
cryptoWalletId是扣款的加密钱包 ID（通过 Step 1 获取）。
currencyConfigId是链与币种的组合配置 ID，决定了资金将通过哪条公链汇出。
address是接收资金的外部链上地址。
amount是计划提现的金额数量。

📦 完整请求样例

{
    "callId": "withdraw_req_1712360000",
    "cryptoWalletId": "1234567890",
    "currencyConfigId": "config_eth_usdt_001",
    "address": "0xB0a2821fAa9AD8c08D2764EAF85C414518137620",
    "amount": 1000.00
}

📦 完整响应样例

{
    "code": 0,
    "message": "success",
    "timestamp": 1712360005,
    "data": {
        "id": "wd_8899aabbccdd",
        "status": "processing",
        "createdAt": "2026-04-15T14:24:00Z"
    }
}

🔗 4. 追踪提现状态 (Track Withdrawal Status)

链上出块和网络确认需要一定时间。提现接口同步返回的 status 通常为 processing（处理中）。您可以通过监听提现相关的 Webhook 事件，或者轮询查询接口来获取提现是否已最终完成（completed）。

Updated about 14 hours ago