Home
Guides

Onramp流程

本页完整介绍电汇入金流程：客户通过银行转账向 Legend 充值法币余额，购买加密货币，并最终收到所购资产。

请将该流程按三个独立阶段跟踪——法币到账、交易执行、数字货币结算。三者由不同通知驱动，不可合并为一个状态。

一、核心 Webhook 交互概览

入金流程中，平台与交易所通过以下 Webhook 实现实时同步：

  • settlement-update：法币到账后推送结算状态，放币时再次推送
  • balance-update：用户法币余额变更时推送更新
  • trade-notify：交易发起时通知交易所
  • trade-execute：交易执行后返回结果

流程一览

%%{init: {"flowchart": {"htmlLabels": true, "curve": "basis"}, "themeVariables": {"fontSize": "16px"}}}%%
flowchart LR
    A["1. KYC 通过<br/>+ 展示入金指引"] --> B["2. 客户发起<br/>银行转账"]
    B --> C["3. 法币到账<br/>settlement-update<br/>WIRE_RECEIVED"]
    C --> D["4. 余额同步<br/>balance-update<br/>（可选）"]
    D --> E["5. 报价 + 下单<br/>/app/rfqbyfiat<br/>/app/orderbyfiat"]
    E --> F["6. 交易通知<br/>trade-notify<br/>trade-execute"]
    F --> G["7. 按约定结算<br/>模式交付"]
    G --> H["8. 数字货币结算<br/>settlement-update<br/>CRYPTO_SENT"]
%%{init: {"sequence": {"actorMargin": 55, "messageMargin": 32}, "themeVariables": {"fontSize": "15px"}}}%%
sequenceDiagram
    autonumber
    participant U as 客户
    participant P as 你的平台
    participant L as Legend

    Note over U,L: 阶段 1–4 · 法币到账
    U->>P: 完成 KYC
    P->>L: GET /app/depositmethods、/app/depositaccount
    L-->>P: 入金方式 + 银行账户 + Reference Code
    P-->>U: 展示汇款指引
    U->>L: 银行转账（本人/联名账户，附 Reference Code）
    L->>P: settlement-update（WIRE_RECEIVED, settled）
    L->>P: balance-update

    Note over U,L: 阶段 5–6 · 交易执行
    P->>L: GET /app/rfqbyfiat（取报价）
    L-->>P: 报价
    P->>L: POST /app/orderbyfiat（提交订单）
    L->>P: trade-notify（started）
    P-->>L: 客户收款钱包地址
    L->>P: trade-execute（succeeded / failed）

    Note over U,L: 阶段 7–8 · 数字货币结算
    L->>P: settlement-update（CRYPTO_SENT, settled）+ txid

二、流程与 Webhook 调用节点

1. 完成 KYC 并展示入金指引

客户须先完成 Legend KYC，之后才能展示银行账户信息。先通过 /app/depositmethods 获取支持的入金方式与币种，再通过 /app/depositaccount 展示 Legend 指定银行账户与所需的 Reference Code。

若用户未完成 KYC，需引导其完成——见 KYC Connect。

2. 客户发起银行转账

客户从其本人名下账户或联名账户向 Legend 指定账户转账。客户必须填写正确的 Reference Code，以便 Legend 将款项与用户匹配。Legend 不接受第三方电汇。

符合条件的 EEA 用户以 EUR 入金时，/app/depositaccount 返回的是专属 vIBAN 而非 Pooled Account，无需填写 Reference code——账户类型规则见该接口页。

3. Legend 确认到账并记入法币余额

Legend 收到并确认资金后，将款项记入用户在 Legend 的法币余额，并推送 settlement-update Webhook：

  • Settlement category：WIRE_RECEIVED
  • Status：
    • settled：资金已到账并确认
    • in progress：入金仍在处理中

4. 同步客户法币余额 —— 可选

用户法币余额发生任何变动时，Legend 通过 balance-update Webhook 实时推送最新余额，确保双方系统数据一致。你也可以调用 /app/fiatbalances 主动查询用户在 Legend 持有的法币余额。

已有法币余额的客户可直接进入购买环节。直存入金流程也允许在余额校验之前先取报价，需要充值时才展示入金指引。

5. 请求报价并提交订单

客户选择币种与法币金额。先调用 /app/rfqbyfiat 获取报价，并按流程要求收集补充信息。客户确认报价且法币余额充足后，调用 /app/orderbyfiat 提交购买。

6. 交易通知

交易发起时，Legend 以 trade_status=started 调用你的 /trade-notify Webhook。在标准买入流程中，你需返回客户对该币种的收款钱包地址。交易执行后，Legend 以 trade_status=succeeded 或 failed 调用 /trade-execute。请更新订单并确认收到通知。

报文与确认规则见 /trade-notify 与 /trade-execute。

7. 按约定结算模式交付数字货币

标准流程下，购买成功后 Legend 将数字货币转入此前由你的平台提供的客户收款地址。

若合同约定由你的平台先行记入客户、之后再与 Legend 结算，则该安排遵循已签署的合同与集成配置。任何垫资义务、结算周期与资金划转均须在该协议中明确。两种结算模式见服务概览。

8. 跟踪最终数字货币结算状态

Legend 会再次推送 settlement-update Webhook，category 为 CRYPTO_SENT：

  • Status：
    • settled：已经完成结算
    • in progress：处理中

可选字段 txid 在有链上交易时提供链上交易 ID。即使是交易所结算的模式，Legend 也会发送这个 Webhook。

如何确认放币成功

当你收到 category: CRYPTO_SENT 且 status: settled 的 settlement-update webhook 时，即表示放币成功——txid 字段携带链上交易哈希。你也可以用 trade_id 与此前 trade-notify webhook 中收到的交易 ID 进行关联。完整字段说明见 settlement-update 接口文档。

示例报文：

{
  "uid": "123",
  "settlement_id": "cf95fa45-b2e9-4b10-afec-8c48b09136f4",
  "category": "CRYPTO_SENT",
  "asset": "USDC",
  "amount": 56.9646,
  "status": "settled",
  "updated_at": "2026-09-09T03:48:57.000000Z",
  "reference": "123-a5b8-4a76-92dc-133",
  "txid": "123",
  "trade_id": "4839a6e4-d844-42a8-8ca8-fdf30ae27dfa",
  "payment_source": "balance"
}

三、其他集成注意点

订单状态与结算状态须分开。 /trade-execute 通知成功仅确认交易已执行；数字货币结算仍须通过 /settlement-update 跟踪。你可以向客户呈现三个阶段：法币已到账、交易已完成、数字货币结算已完成。

未转换法币的自动兑换。 根据合规要求，Legend 不会长期存储用户法币余额。若用户法币资金到账后一个月内未转换为数字货币，系统将自动执行交易，将该笔法币转换为 USDT/USDC。直存入金流程对 Virtual IBAN（专属虚拟 IBAN）用户另有例外——请与 Legend 对接人员在集成配置阶段确认适用规则。

Updated 9 days ago