curl --request POST \
--url https://uat-api.clinkbill.com/api/billing/session \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: <api-key>' \
--header 'X-Timestamp: <x-timestamp>' \
--data '
{
"customerId": "cus_xxxxx"
}
'{
"code": 200,
"msg": "success",
"data": {
"url": "https://uat-portal.clinkbill.com/session/eyJ0eXAiOffsssxxxxxx",
"expiresAt": 1755152165726
}
}创建客户门户会话
Create a new customer portal session for billing management
curl --request POST \
--url https://uat-api.clinkbill.com/api/billing/session \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: <api-key>' \
--header 'X-Timestamp: <x-timestamp>' \
--data '
{
"customerId": "cus_xxxxx"
}
'{
"code": 200,
"msg": "success",
"data": {
"url": "https://uat-portal.clinkbill.com/session/eyJ0eXAiOffsssxxxxxx",
"expiresAt": 1755152165726
}
}data.url 返回的门户链接默认进入门户首页。如需让客户直接进入指定页面，可在跳转前给 data.url 拼接 redirectUrl 查询参数，参数值为目标页面路径（需做 URL 编码）。常用路径举例如下（非全部页面）：| 目标页面 | redirectUrl 路径 |
|---|---|
| 更新指定订阅 | /subscription/{subscriptionId}/update |
| 添加支付方式 | /payment-methods/new |
| 更新客户信息 | /customer/update |
// 服务端：调用 POST /billing/session 后拼接 redirectUrl
const { url } = response.data;
const subscriptionId = 'sub_xxxxx';
const portalUrl = new URL(url);
// searchParams 会自动编码参数值，无需再手动 encodeURIComponent
portalUrl.searchParams.set('redirectUrl', `/subscription/${subscriptionId}/update`);
// 将 portalUrl.toString() 返回给前端用于跳转，或直接 302 重定向
// https://uat-portal.clinkbill.com/session/eyJ0eXAi...?redirectUrl=%2Fsubscription%2Fsub_xxxxx%2Fupdate
redirectUrl 的值务必做 URL 编码，且需确保拼接的链接正确，否则会导致页面 404。上例为 JavaScript 写法，searchParams 会自动编码。使用其他语言（或不使用 searchParams）时，需要自行对参数值进行编码，例如 Java 的 URLEncoder.encode(path, StandardCharsets.UTF_8)、Python 的 urllib.parse.quote(path, safe='')。编码后应为 %2Fsubscription%2Fsub_xxxxx%2Fupdate，注意只编码一次。授权
Your secret API key obtained from the Clink dashboard (Developers section)
请求头
Current timestamp in milliseconds since Unix epoch (required for request signing)
"1783513683000"
请求体
Parameters required to initialize a customer portal session
Existing customer's unique identifier
Redirect URL when customer click on 'Return to Merchant'
Product IDs allowed for subscription upgrades or downgrades in this customer portal session. When omitted or empty, this session does not restrict eligible products. Blank or invalid product IDs are rejected.
["prd_001", "prd_002"]
响应
Customer portal session created successfully
Response object returned when creating a new checkout session
HTTP status code indicating the request result (200 for success, 4xx for client errors, 5xx for server errors)
200
Human-readable message describing the result ('success' for successful operations, error details for failures)
"success"
Customer Portal session details when successfully created
Show child attributes
Show child attributes