post
https://exchange.com/api/settlement-update
结算状态变更回调接口
合作平台可通过实现此 Webhook 接口，接收用户结算状态变更的实时通知。
功能描述
当用户的结算状态（如充值、提现等）发生变化时，Legend 系统将通过此回调地址向交易所推送最新的状态信息。
实现要求
- 交易所需按约定规范部署并暴露此接口
- 接口需具备验证签名、处理状态更新及返回标准响应的能力
典型应用场景
- 接收用户充值和提现的成功/失败状态
- 同步结算记录的审核、处理中、已完成等状态流转
提示：此接口为双方系统联调的重要组成部分，请确保其稳定性和安全性。
回调报文说明
| 参数名 | 类型 | 必传 | 说明 | 示例值 |
|---|---|---|---|---|
uid | string | 是 | 与此结算记录关联的用户ID | user_12345 |
settlement_id | uuid | 是 | 在Legend系统中的唯一结算标识符 | 987ddf77-a9ad-4bd |
category | string | 是 | 结算类型分类，例如 "WIRE_SENT"。详见结算分类表 | WIRE_SENT |
asset | string | 是 | 结算资产名称（法币或加密货币） | USD |
amount | string | 是 | 结算资产金额（法币金额或加密货币数量） | 1000.00 |
status | string | 是 | 结算状态：'pending'（待处理）、 'settled'（已完成）、 'canceled'（已取消）、 'in progress'（处理中）、 'rejected'（已拒绝） | settled |
updated_at | string | 是 | 记录的最后更新时间（ISO 8601格式） | 2024-01-15T10:30:00Z |
reference | string | 否 | 合作方创建此结算记录时传递的参考ID（将原样返回） | partner123456 |
txid | string | 否 | 当分类为 CRYPTO_SENT 或 CRYPTO_SENT_FROM_AUTOTRADE 时的链上交易ID。空值表示尚未有交易ID | 0x4a5b6c |
| payment_source | string | 否 | 支付方式默认不开启， card 信用卡/借记卡,balance 余额，card_google 谷歌Pay，card_apple 苹果Pay | |
| trade_id | string | 否 | 交易编号 | |
note | string | 否 | 仅当 category 为 CREDIT_CARD_RECEIVED（卡支付）时附带。失败时该字段为支付服务提供商的拒付原因或 Legend 内部处理结果的原文，取值见下方「卡支付常见 note 取值」表 | Suspected Fraud (Visa) |
说明：
- 所有金额字段均使用字符串类型，确保数值精度
- 时间字段需使用 ISO 8601 标准格式（UTC 时区）
reference字段最大长度不超过 255 个字符txid字段仅在加密货币转出相关的分类中有效
卡支付常见 note 取值
note 取值category 为 CREDIT_CARD_RECEIVED（卡支付）的结算记录，note 为支付服务提供商的拒付原因或 Legend 内部处理结果的原文。常见取值：
「归因方」列说明该失败由哪一方的决定造成：
- 发卡行——用户所持卡片的发卡银行。绝大多数卡拒付属于此类，包括泛化拒付与限额/欺诈/安全类拒绝。归因发卡行的拒付不是 Legend 侧的限额、余额校验或系统故障。
- 用户——用户自身行为导致（如未完成 3DS 验证）。
- Legend——Legend 自身的风控判断或技术处理结果，也包括 Legend 未识别的拒付码（未映射）。
note 取值 | 含义 | 归因方 | 建议后续操作 |
|---|---|---|---|
LIMIT EXCEEDED OR Insufficient funds OR Insufficient funds/over credit limit | 用户卡内余额不足或超出信用额度 | 发卡行 | 请用户确认卡内余额或额度，或换一张卡 |
Suspected Fraud (Visa) | 发卡行风控拦截（疑似欺诈） | 发卡行 | 请用户联系发卡行确认交易；同一张卡短期内勿重复尝试 |
Negative CAM, dCVV, iCVV, or CVV results (Visa) OR Policy reasons (Mastercard) | CVV/安全码校验失败 | 发卡行 | 请用户核对卡安全码，或换一张卡 |
3ds_unauthenticated | 3DS 验证未完成（用户未完成验证或中途放弃） | 用户 | 引导用户在验证页面完成短信/银行 App 验证 |
Blocked by cardholder/contact cardholder | 卡被持卡人冻结 | 发卡行 | 请用户联系发卡行解冻 |
Exceeds withdrawal amount limit | 超出该卡自身设定的单笔或单日限额——是卡的限额，不是 Legend 侧的订单限额 | 发卡行 | 降低金额，或请用户联系发卡行提额 |
Exceeds withdrawal count limit OR Authentication requested | 超出该卡的交易次数限制，或需要补充验证 | 发卡行 | 稍后重试，或请用户联系发卡行 |
REFUSED OR Do not honor OR Declined | 发卡行泛化拒付（未给出具体原因） | 发卡行 | 请用户联系发卡行了解具体原因 |
Transaction cannot be completed violation of law | 发卡行基于政策性原因拒付，未给出具体原因。支付服务提供商在发卡行出于监管或政策原因（而非卡片本身原因）拒绝时返回该值。 | 发卡行 | 不要用同一张卡重试，结果不会改变。请用户改用其他发卡行的卡支付，或改用银行转账。 |
Unable to authorise OR ERROR | 发卡行未能授权该笔支付 | 发卡行 | 请用户联系发卡行确认交易，或换一张卡重试 |
Expired card OR DECLINED, EXPIRED CARD | 卡已过期 | 发卡行 | 请用户换一张卡 |
STIP cannot approve (Visa) OR Fraud/Security related reasons (Mastercard) | 发卡行无法核准，或因欺诈/安全原因拒绝 | 发卡行 | 请用户联系发卡行确认交易 |
Transaction not supported/blocked by issuer | 该卡种不支持此类交易 | 发卡行 | 请用户更换支持 Visa/Mastercard 的卡 |
INVALID ACCEPTOR OR Invalid merchant OR Invalid merchant or service provider | 发卡行不识别或不允许该商户——通常是发卡行侧的策略性拒绝（如该行不支持该商户类别），与用户卡片无关；若大面积出现则可能是商户配置问题 | 发卡行（若大面积出现则为 Legend） | 请用户更换其他发卡行的卡或其他支付方式；若大量用户遇到，联系 Legend 排查商户配置 |
CREDITCARD ISSUER TEMPORARILY NOT REACHABLE OR Issuer unavailable or switch inoperative (STIP not applicable or available for this transaction) OR Authorization System or issuer system inoperative OR Authorization System or issuer system inop | 发卡行或其授权系统暂时无法接通——发卡行侧的临时技术故障，并非针对用户或卡片的拒绝决定（可重试） | 发卡行 | 稍后使用同一张卡重试；若持续出现，请用户更换卡片或联系发卡行 |
fraud_control | 被 Legend 风控判定为高风险并拦截 | Legend | 同一张卡勿重试；用户认为误拦时联系 Legend 核实 |
fraud_assessment_unavailable | 风控评估服务暂时不可用，交易被保守终止（非欺诈判定，可重试） | Legend | 稍后重试；持续出现请联系 Legend |
Unknown | 服务商返回了 Legend 未识别的拒付码（未映射） | Legend | 反馈 Legend 核实映射 |
payment_failed | 技术类兜底（如收单行拒绝请求格式），无具体拒付原因 | Legend | 反馈 Legend 排查 |
（无 note 字段） | 未回传失败原因 | — | 反馈 Legend 排查 |
说明：
- 上表覆盖常见取值，支付服务提供商的其他拒付描述也可能原样出现在
note中 note还可能带有 Legend 内部合规流程标注（以后缀形式追加，如| EDD Triggered、| TM Completed），或运营人工审核时填写的备注——这类内容属于结算的合规审查流程信息，与支付结果本身无关- 若用户在完成支付授权前放弃（从未发起扣款），不会生成结算记录，该订单也不会触发本回调