> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clinkbill.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 创建客户门户会话

> Create a new customer portal session for billing management

<Tip>
  `data.url` 返回的门户链接默认进入门户首页。如需让客户直接进入指定页面，可在跳转前给 `data.url` 拼接 `redirectUrl` 查询参数，参数值为目标页面路径（需做 URL 编码）。常用路径举例如下（非全部页面）：

  | 目标页面 | `redirectUrl` 路径 |
  | - | - |
  | 更新指定订阅 | `/subscription/{subscriptionId}/update` |
  | 添加支付方式 | `/payment-methods/new` |
  | 更新客户信息 | `/customer/update` |

  ```javascript theme={null}
  // 服务端：调用 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
  ```
</Tip>

<Warning>
  `redirectUrl` 的值务必做 URL 编码，且需确保拼接的链接正确，否则会导致页面 404。

  上例为 JavaScript 写法，`searchParams` 会自动编码。使用其他语言（或不使用 `searchParams`）时，需要自行对参数值进行编码，例如 Java 的 `URLEncoder.encode(path, StandardCharsets.UTF_8)`、Python 的 `urllib.parse.quote(path, safe='')`。编码后应为 `%2Fsubscription%2Fsub_xxxxx%2Fupdate`，注意只编码一次。
</Warning>


## OpenAPI

````yaml POST /billing/session
openapi: 3.1.0
info:
  title: Clink API
  description: >-
    Official API documentation for Clink's payment processing platform. This API
    enables merchants to create and manage payment sessions, handle
    subscriptions, and process transactions.
  version: 1.0.0
servers:
  - url: https://uat-api.clinkbill.com/api/
security:
  - ApiKeyAuth: []
paths:
  /billing/session:
    post:
      description: Create a new customer portal session for billing management
      parameters:
        - $ref: '#/components/parameters/TimestampHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerPortalCreateReq'
            examples:
              example:
                summary: Create a customer portal session
                value:
                  customerId: cus_xxxxx
              customSubscriptionUpgrade:
                summary: >-
                  Create a session with custom subscription upgrade and
                  downgrade products
                value:
                  customerId: cus_xxxxx
                  subscriptionUpdateProductIds:
                    - prd_001
                    - prd_002
      responses:
        '200':
          description: Customer portal session created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerPortalCreateRes'
components:
  parameters:
    TimestampHeader:
      name: X-Timestamp
      in: header
      required: true
      description: >-
        Current timestamp in milliseconds since Unix epoch (required for request
        signing)
      schema:
        type: string
        example: '1783513683000'
  schemas:
    CustomerPortalCreateReq:
      description: Parameters required to initialize a customer portal session
      required:
        - customerId
      type: object
      properties:
        customerId:
          type: string
          description: Existing customer's unique identifier
        returnUrl:
          type: string
          description: Redirect URL when customer click on 'Return to Merchant'
        subscriptionUpdateProductIds:
          type: array
          description: >-
            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.
          items:
            type: string
            example: prd_001
          example:
            - prd_001
            - prd_002
    CustomerPortalCreateRes:
      type: object
      description: Response object returned when creating a new checkout session
      properties:
        code:
          type: integer
          description: >-
            HTTP status code indicating the request result (200 for success, 4xx
            for client errors, 5xx for server errors)
          format: int32
          example: 200
        msg:
          type: string
          description: >-
            Human-readable message describing the result ('success' for
            successful operations, error details for failures)
          example: success
        data:
          $ref: '#/components/schemas/CustomerPortalSessionVo'
          description: Customer Portal session details when successfully created
    CustomerPortalSessionVo:
      type: object
      properties:
        url:
          type: string
          description: The magic link for customer to access the portal
          example: https://uat-portal.clinkbill.com/session/eyJ0eXAiOffsssxxxxxx
        expiresAt:
          type: integer
          description: Link expiry time
          format: int64
          example: 1755152165726
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
      description: >-
        Your secret API key obtained from the Clink dashboard (Developers
        section)

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.