API 参考

客户门户 API

为已保存的客户生成签名 MakePay 客户门户 URL。

生成门户链接

从已保存的 MakePay 客户资料创建 MakePay 客户门户链接。只在客户或商户点击进入账单时生成链接，然后重定向或打开返回的 URL。

POST /api/partner/v1/makepay/customers/{customerId}/portal

customerId 接受已保存的客户 UUID 或客户 UID。请求体为空。

curl

curl -X POST "https://www.makecrypto.io/api/partner/v1/makepay/customers/CUSTOMER_ID/portal" \
  -H "x-makecrypto-key-id: MAKEPAY_API_KEY_ID" \
  -H "x-makecrypto-key-secret: MAKEPAY_API_SECRET" \
  -H "Accept: application/json"

身份验证

服务器集成使用 MakePay API 密钥认证。当已登录用户对所选团队拥有 settings.manage 权限时，浏览器会话也可以调用按公司限定的仪表盘路由。API key 请求不在 URL 中传公司 ID，因为密钥已经归属于一个公司。

请求头	值	说明
`x-makecrypto-key-id`	MakePay API 密钥 ID	MakePay 支付 API 使用 `mk_makepay_` 前缀。
`x-makecrypto-key-secret`	一次性 API 密钥	只会在创建密钥时显示。请保存在服务器端密钥管理器中。

响应

路由返回客户对象，以及签名后的 urls.customerPortal 链接。

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 参数

返回的门户 URL 形如：

https://{makepay-or-verified-merchant-domain}/billing?company={companyId}&customer={customerUid}&expires={unixSeconds}&signature={hexHmac}

参数	说明
`company`	拥有该客户的 MakeCrypto 公司账户 ID。
`customer`	限定到该公司的 MakePay 客户 UID。
`expires`	秒级 Unix 时间戳。链接有效期为 24 小时。
`signature`	基于版本、公司、客户和过期值的 HMAC 签名。

MakePay 会在加载任何门户数据前验证签名和过期时间。不要永久保存门户 URL。每次按钮点击都应重新生成新链接。

门户范围

门户只显示与签名公司和客户匹配的数据：

客户资料摘要和可编辑显示名。
通过客户邮箱或 client ID 匹配的支付历史。
带托管 MakePay URL 的 active 或 unpaid 支付链接。
通过客户邮箱或 metadata client ID 匹配的订阅。
对支持订阅状态执行暂停、重新激活和取消操作。

第一版客户门户不支持修改邮箱、client ID、PDF、支付方式、许可证密钥、套餐切换和已取消订阅恢复流程。