API 参考

参考

路由、对象模型、枚举、设置和错误结构。

路由参考

方法	路由
GET	`/api/partner/v1/companies`
认证会话用途列出用户公司返回已登录 MakeCrypto 用户可用于门户工具的团队。
POST	`/api/partner/v1/onboarding/company`
认证合作伙伴入驻密钥用途创建公司入驻链接创建由合作伙伴预填的公司入驻草稿并返回商户领取 URL。可包含 oauth 区块，在商户完成入驻后自动连接已验证的 OAuth 应用。
GET	`/api/partner/v1/makepay/payment-links`
认证 MakePay API 密钥用途列出或创建支付链接读取 API 密钥所属公司的支付链接，或创建托管 MakePay 结账链接。
POST	`/api/partner/v1/makepay/payment-links`
认证 MakePay API 密钥或公开用途列出或创建支付链接读取 API 密钥所属公司的支付链接，或创建托管 MakePay 结账链接。
POST	`/gateway/pay/{makepayKeyId}`
认证公开表单密钥用途提交 HTML 支付表单接收浏览器表单字段，创建托管支付链接，并将客户重定向到结账页。
GET	`/api/partner/v1/makepay/payment-links/{uid}`
认证 MakePay API 密钥用途获取或更新支付链接读取一个支付链接详情，或将支付链接设为 active、paused 或 archived。
PATCH	`/api/partner/v1/makepay/payment-links/{uid}`
认证 MakePay API 密钥用途获取或更新支付链接读取一个支付链接详情，或将支付链接设为 active、paused 或 archived。
POST	`/api/partner/v1/makepay/payment-links/{uid}/send-request-email`
认证 MakePay API 密钥用途发送支付请求将托管支付链接发送或重新发送到客户邮箱。
GET	`/api/partner/v1/makepay/subscriptions`
认证 MakePay API 密钥用途列出或创建订阅返回周期性 MakePay 订阅计划，或创建订阅和第一张发票。
POST	`/api/partner/v1/makepay/subscriptions`
认证 MakePay API 密钥用途列出或创建订阅返回周期性 MakePay 订阅计划，或创建订阅和第一张发票。
GET	`/api/partner/v1/makepay/customers`
认证 MakePay API 密钥用途列出或更新客户返回 MakePay 客户资料，或按邮箱创建/更新客户。
POST	`/api/partner/v1/makepay/customers`
认证 MakePay API 密钥用途列出或更新客户返回 MakePay 客户资料，或按邮箱创建/更新客户。
POST	`/api/partner/v1/makepay/customers/{customerId}/portal`
认证 MakePay API 密钥用途创建客户门户链接按需生成 24 小时有效的签名 MakePay 客户门户 URL。
GET	`/api/partner/v1/timezones`
认证公开用途列出时区返回支持的 IANA 时区标识符。
GET	`/api/partner/v1/makepay/settings`
认证 MakePay API 密钥用途读取或更新 MakePay 设置读取或更新结算、重定向、费用和少付处理设置。
PUT	`/api/partner/v1/makepay/settings`
认证 MakePay API 密钥用途读取或更新 MakePay 设置读取或更新结算、重定向、费用和少付处理设置。
GET	`/api/partner/v1/makepay/destination-assets`
认证 MakePay API 密钥用途列出目标资产返回支持的结算资产和当前默认资产。
GET	`/api/partner/v1/makepay/webhook-requests`
认证 MakePay API 密钥用途列出 Webhook 投递查看支付和订阅 Webhook 投递尝试及重试状态。

合作伙伴入驻 OAuth

POST /api/partner/v1/onboarding/company 可以包含可选 oauth 对象。MakeCrypto 会在创建入驻链接前验证 OAuth 应用、redirect URI、权限范围和 PKCE challenge。商户完成入驻后，MakeCrypto 创建公司、授予 OAuth 应用访问该公司的权限，并携带授权 code 重定向到注册的 redirectUri。

合作伙伴应用应保存匹配的 PKCE code_verifier，并通过 POST /oauth/token 交换返回的 code。

PaymentLink 对象

字段	类型	说明
`id`	`string`	内部 UUID。
`uid`	`string`	用于托管和嵌入式结账路由的公开支付链接标识符。
`status`	`"active" \| "paused" \| "archived"`	商户管理的链接状态。
`payload`	`PaymentLinkPayload`	商户订单、金额、客户、重定向、metadata、品牌和运行时字段。
`created_at`	`string`	ISO 时间戳。
`updated_at`	`string`	ISO 时间戳。
`expires_at`	`string \| null`	解析后的过期时间戳；无过期时间时为 `null`。
`publicUrl`	`string`	托管 MakePay 结账 URL，会出现在创建、列表、详情和状态更新响应中。

PaymentLinkPayload

字段	类型	说明
`title`	`string`	支付展示标签。
`description`	`string`	面向客户的描述。
`amount`	`string`	要收取的十进制金额。
`fiatCurrency`	`string`	可选展示币种，例如 `USD` 或 `EUR`。
`currency`	`string`	结算 symbol，例如 `USDT`、`USDC` 或 `BTC`。
`asset`	`string`	精确目标资产标识符。同一 symbol 位于多条链时使用它。
`orderId`	`string`	商户订单或发票引用。
`customerEmail`	`string`	用于邮件请求和 Webhook 载荷。
`clientId`	`string`	可选商户侧客户标识符。
`returnUrl`	`string`	通用返回导航的商户 URL。
`successUrl`	`string`	完成支付后的商户 URL。
`failureUrl`	`string`	支付失败或取消后的商户 URL。
`expirationTime`	`"15m" \| "1h" \| "12h" \| "24h" \| "72h" \| "never"`	请求的支付链接生命周期。
`metadata`	`Record<string, unknown>`	商户定义的 metadata，会返回到仪表盘和 Webhook。
`runtimeMode`	`"merchant_target_net_v2"`	新支付链接由 API 注入。
`billingVersion`	`"v2"`	新支付链接由 API 注入。
`merchantName`	`string`	可用时从公司品牌注入。
`merchantPictureUrl`	`string`	可用时从公司资料注入。
`merchantLogoUrl`	`string`	可用时从商户品牌注入。
`merchantPaymentLinkTheme`	`"light" \| "dark" \| "system"`	从商户结账主题设置注入。

Customer 对象

字段	类型	说明
`id`	`string`	内部 UUID。
`uid`	`string`	用于门户链接的公开 MakePay 客户标识符。
`email`	`string`	客户邮箱。
`name`	`string \| null`	客户显示名，可在客户门户编辑。
`clientId`	`string \| null`	商户侧客户标识符，在门户中只读。
`metadata`	`Record<string, unknown>`	商户定义的 metadata。
`createdAt`	`string`	ISO 时间戳。
`updatedAt`	`string`	ISO 时间戳。
`urls`	`{ customerPortal: string }`	出现在门户生成响应中。不要持久化该 URL。

客户门户响应

POST /api/partner/v1/makepay/customers/{customerId}/portal 会为已保存客户返回签名门户 URL。

json

{
  "ok": true,
  "companyId": "acct_123",
  "customer": {
    "id": "b834dd77-69b8-41a9-a4b6-95bc9dd14c2d",
    "uid": "cus_01hzy4k6p4w9y2x7e2z7n8a2xm",
    "email": "buyer@example.com",
    "name": "Ada Lovelace",
    "clientId": "client_1042",
    "metadata": {
      "source": "api"
    },
    "createdAt": "2026-04-20T10:00:00.000Z",
    "updatedAt": "2026-04-20T10:00:00.000Z",
    "urls": {
      "customerPortal": "https://makepay.io/billing?company=acct_123&customer=cus_01hzy4k6p4w9y2x7e2z7n8a2xm&expires=1776765600&signature=8d1f..."
    }
  },
  "expiresAt": "2026-04-21T10:00:00.000Z"
}

该 URL 有效期为 24 小时。如果公司配置了已验证的 payment_link_domain，链接会使用该域名；否则回退到 MakePay 公共源站。

查询参数	说明
`company`	拥有客户的 MakeCrypto 公司账户 ID。
`customer`	MakePay 客户 UID。
`expires`	秒级 Unix 时间戳。
`signature`	基于 `v1:{companyId}:{customerUid}:{expires}` 的 HMAC 签名。

请在客户打开账单时按需生成门户链接。过期、被篡改或跨客户 URL 会在加载门户数据前被拒绝。

Subscription 对象

订阅包含内部 id、商户侧 uid、status、客户邮箱、标签、描述、周期金额、结算资产、计费节奏、开始时间、时区、metadata，以及由列表路由和仪表盘调用返回的 cycles。当未支付周期超过 dueAt 至少 24 小时时，订阅会进入 overdue，状态变化会触发签名的 makepay.subscription.status_changed Webhook。

MakePaySettings

字段	类型	说明
`status`	`"active" \| "paused"`	团队的产品可用状态。
`defaultDestinationAsset`	`string \| null`	支付链接只提供 `currency` 时使用的默认资产标识符。
`feePaidBy`	`"client" \| "merchant"`	决定 MakePay 费用由客户还是商户承担。
`returnRedirectUrl`	`string \| null`	结账后的回退重定向。
`successRedirectUrl`	`string \| null`	完成支付后的重定向。
`failureRedirectUrl`	`string \| null`	取消或失败支付后的重定向。
`underpaymentPercentEnabled`	`boolean`	启用百分比少付容差。
`underpaymentPercentThreshold`	`number`	允许的少付百分比。
`underpaymentFixedEnabled`	`boolean`	启用固定少付容差。
`underpaymentFixedThreshold`	`number`	允许的固定少付金额。

DestinationAsset

字段	类型	说明
`assetIdentifier`	`string`	标准链、symbol 和合约标识符。
`chainCode`	`string`	结算链代码。
`chainName`	`string`	可读链名称。
`symbol`	`string`	资产 symbol。
`name`	`string`	资产名称。
`decimals`	`number`	token 小数位。
`isDefault`	`boolean`	是否为当前公司默认资产。

状态值

active：链接可以打开并支付。
paused：链接仍对商户可见，但不应接受新的支付开始。
archived：链接从活跃视图隐藏，应视为已关闭。
订阅状态包括 active、paused、overdue 和 cancelled。

错误结构

错误会以 JSON 返回 error，可用时也返回 errorCode。

{
  "errorCode": "invalid_destination_asset",
  "error": "payload.asset ETH.USDT-... is not available for supported settlement routes."
}