> ## 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.

# 创建卡管理会话

> Issues a restricted Clink browser session (the same kind of session the Clink wallet frontend uses) for the token's customer, so the platform's own settings page can list, set a default, and delete cards, resolve the country code used to preselect the card form (inferred from the caller's IP), fetch the public key used to encrypt card data in the card form, add a card, and complete its 3-D Secure challenge. Requires `portal:write`.

返回的 token 是浏览器会话，不是 portal token：portal token 仍只保留在服务端。`scope` 为 `card:manage`，该 token 只能访问下方列出的卡管理接口；其他 `/a/**` 接口会返回 `403` 和 `browser_scope_forbidden`（`code` `71211020`），包括读取交易、客户资料或执行其他卡片操作。`/agent/**` 需要 portal token，网关会以 `401` 拒绝该浏览器会话。

请求没有 body 字段。会话始终为该 token 对应用户创建。

默认有效期为 30 分钟。token 过期后请重新调用本接口；不要复用已过期的 token。

## 允许访问的接口

* `GET /a/cwallet/card/info`：查询用户的卡列表。
* `PUT /a/cwallet/card/setDefault`：设置默认卡。
* `DELETE /a/cwallet/card/delete`：删除卡片。
* `GET /a/cwallet/get/countryAlpha2Code`：按客户端 IP 解析的二字国家码，用于卡片表单预选国家。
* `GET /a/cwallet/kms/public-key`：获取页内加卡表单加密卡数据所需的公钥；加密结果通过同一会话的 `POST /a/cwallet/card/add` 提交。
* `POST /a/cwallet/card/add`：添加卡片；需要 3-D Secure 时返回 action。
* `POST /a/cwallet/redirect/callback`：完成加卡的 3-D Secure 回调。

添加卡片**支持**在本卡管理会话内完成：`card/add` 返回 3-D Secure action 后，由 `redirect/callback` 收口。该回调接口同时可能推进购买授权，因此 token 只能用于客户自己的浏览器，不能跨客户共享。Vault 会话（见[创建 Vault 会话](https://docs.clinkbill.com/cn/api-reference/agent-portal/create_vault_session.md)）仍然是可选的托管绑卡路径。除上述 7 个接口外，本会话不开放其他卡片/交易/客户数据操作。

> [!WARNING]
>
> 把 `access_token` 当作凭证处理。不要写入日志、在用户之间共享或发送给模型。只在用户自己的浏览器会话中使用，并为不同用户重新申请。


## OpenAPI

````yaml POST /agent/platform/card-sessions
openapi: 3.1.0
info:
  title: Clink Agent Portal API
  description: >-
    Agent Portal APIs let an Agent platform read and manage one user's Clink
    account with a portal user token: payment methods, orders, refunds, purchase
    instructions, payment credentials, payment results, and settings.
  version: 1.0.0
servers:
  - url: https://uat-api.clinkbill.com
    description: Sandbox
security:
  - PortalToken: []
paths:
  /agent/platform/card-sessions:
    post:
      summary: Create a card session
      description: >-
        Issues a restricted Clink browser session (the same kind of session the
        Clink wallet frontend uses) for the token's customer, so the platform's
        own settings page can list, set a default, and delete cards, resolve the
        country code used to preselect the card form (inferred from the caller's
        IP), fetch the public key used to encrypt card data in the card form,
        add a card, and complete its 3-D Secure challenge. Requires
        `portal:write`.
      operationId: createCardSession
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    format: int32
                    description: '`200` on success.'
                    example: 200
                  msg:
                    type: string
                    description: Result message.
                    example: Success
                  data:
                    $ref: '#/components/schemas/CardSession'
              example:
                code: 200
                msg: Success
                data:
                  access_token: <CARD_SESSION_TOKEN>
                  token_type: Bearer
                  expires_in: 1800
                  scope: card:manage
        '401':
          description: Missing, expired, or invalid portal token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: >-
            Wrong token audience, missing `portal:write` scope, or a platform
            client token used instead of a portal token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    CardSession:
      type: object
      properties:
        access_token:
          type: string
          description: >-
            Restricted browser session token for the platform's card-management
            UI. Use it only in that customer's browser and only on the allowed
            card-management endpoints.
          example: <CARD_SESSION_TOKEN>
        token_type:
          type: string
          description: Always `Bearer`.
          enum:
            - Bearer
          example: Bearer
        expires_in:
          type: integer
          description: >-
            Remaining lifetime in seconds. Read this value instead of assuming a
            fixed lifetime.
          example: 1800
        scope:
          type: string
          description: Always `card:manage`.
          enum:
            - card:manage
          example: card:manage
    ErrorResponse:
      type: object
      description: Business errors use the standard envelope without `data`.
      properties:
        code:
          type: integer
          description: >-
            Numeric business error code. Judge an error by the HTTP status
            together with `code`, not by a string error code.
        msg:
          type: string
          description: Human-readable description.
  securitySchemes:
    PortalToken:
      type: http
      scheme: bearer
      description: >-
        Portal user token from `POST /agent/cwallet/platform/portal/tokens`.
        Reads require `portal:read`; writes require `portal:write`.

````

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