LinkePay 商户接入文档

面向商户（接入方）的完整接入与使用文档。所有示例均使用 生产环境（主网） 地址。

生产环境信息

项	值
API 网关（Base URL）	https://api.linkepay.shop
客户端接口前缀	/api/v1/client/project/{project_uid}
商户控制台	https://app.linkepay.shop
文档	https://docs.linkepay.shop
平台公钥（用于验签回调）	0xc0b2388188f35c087400575393c124e9c459550f1dfcf848214f47637b599ee08a6b64876c4687e869d070d892b97071fd4c90b0a3491814823b4e97f8e7d50f
生产已开通网络	Ethereum Mainnet (1)、TRON (4)、BSC Mainnet (56)
生产已支持币种	USDC (1)、USDT (2)

平台公钥可随时通过 GET https://api.linkepay.shop/api/v1/public/platform-public-key 获取， 建议接入时以接口返回值为准（平台轮换密钥时无需改代码）。

关于 API 域名变更

API 网关域名已更换为 api.linkepay.shop。

已接入的商户无需立即改动 —— 旧域名 linkepay-api.bestxx.com 继续可用，指向同一套服务，行为完全一致。两个域名会并行运行一段时间。

• 新接入：直接用 api.linkepay.shop
• 已接入：方便时把 Base URL 换过来即可；旧域名下线前会提前通知

⚠️ 换域名不影响签名 —— 参与签名的是路径（/api/v1/client/...）而非域名， 所以切换 Base URL 不需要改签名逻辑，也不需要重新登记公钥。详见 04 · 签名规范。

文档目录

文档	内容
01 · 接入指南	业务流程、准备工作、密钥/API Key/IP 白名单/回调地址配置、联调清单
02 · API 参考	全部商户接口的请求/响应说明与生产环境 curl 示例
03 · 回调通知	充值/提现回调的推送时机、报文、验签、应答规范、重试策略
04 · 签名规范	请求签名（X-Signature）与响应/回调验签算法，含多语言实现
05 · Go SDK	linkepay-sdk-go 的安装与完整用法
06 · 附录：枚举与错误码	网络/币种/状态枚举、精度表、业务错误码

5 分钟看懂

商户后端                        LinkePay                        区块链
   │                               │                              │
   │─① 申请充值地址(签名)──────────▶│                              │
   │◀────────── 地址 ──────────────│                              │
   │                               │                              │
   │  展示地址给终端用户            │◀──── ② 用户转账入账 ──────────│
   │                               │                              │
   │◀─③ 充值回调(平台签名)──────────│  (确认后推送，需应答 HTTP 201) │
   │                               │                              │
   │─④ 发起提现(签名)──────────────▶│───── ⑤ 从归集地址出金 ───────▶│
   │◀─⑥ 提现回调(平台签名)──────────│                              │

• ①④ 写操作：用商户私钥对请求签名，放在 X-Signature 头。
• 查询接口：用 X-API-Key 头。
• ③⑥ 回调：用平台公钥验签；处理完成返回 HTTP 201（停止推送），未到终态返回 200（继续推送）。
• 所有请求的来源 IP 必须先在控制台登记并通过审核（内部组织除外）。

变更记录

日期	变更
2026-08-12	API 网关域名更换为 api.linkepay.shop，文档内所有示例已同步。旧域名 linkepay-api.bestxx.com 继续可用，两者指向同一套服务，已接入商户无需立即改动。控制台迁至 app.linkepay.shop，文档站迁至 docs.linkepay.shop。
2026-08-10	首版发布。同步修复：/user/deposits、/user/withdrawals 现可正常返回数据；/api/v1/public/assets 的 decimals 已与结算精度对齐；API Key 现强制校验与路径项目的归属关系（跨项目使用将返回 403）。

⚠️ 如果你此前用 A 项目的 API Key 查询过 B 项目的数据，请在本次变更后改用对应项目自己的 Key，否则会收到 403 api key does not belong to this project。