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

# 创建 Vault 会话

> Creates a short-lived Vault (hosted card-binding) session for the token's customer and returns its `vault_id`, the hosted page `url`, and the expiry. Requires `portal:write`.

它和[绑定银行卡](https://docs.clinkbill.com/cn/api-reference/agent-portal/bind_card.md)是同一个托管绑卡流程，只是以 `vault_id` 契约提供给平台设置页，便于统一卡管理：创建会话 → 打开托管页面 → 重新读取卡列表。每次调用都会创建新的独立会话；不会创建购买授权，也不会创建指令。

`POST /agent/platform/vault-sessions` 与既有的[绑定银行卡](https://docs.clinkbill.com/cn/api-reference/agent-portal/bind_card.md) `POST /agent/platform/bind-sessions` 创建的是**同一个** Vault 绑定会话，只是响应字段名不同（这里是 `vault_id`，那里是 `session_id`）。新接入请使用 `vault-sessions`；`bind-sessions` 保留给既有接入，两者都不废弃。

请求中没有用于指定其他用户的 body 字段。会话始终为该 token 对应用户创建。

> [!WARNING]
>
> 把 `vault_id` 和 `url` 当作凭证处理。不要转发、截图或写入日志；拿到其中任意一个的人可以在会话有效期内为该用户完成绑卡。只把它们发给目标用户。

## 用 `vault_id` 换取页面登录态

如果不想直接打开链接，可以用 `vault_id` 在既有兑换接口换取 Vault 页面登录态后再打开托管页面：

```http theme={null}
POST {API_BASE_URL}/a/cwallet/vault/session/exchange
Content-Type: application/json

{
  "session_id": "vs_..."
}
```

兑换接口返回 Vault 页面会话 `token` 及其 `expire_in`；该 token 只用于托管页面。会话有效期沿用 Clink 的 Vault 会话配置，过期后请重新创建会话。Vault 会话是绑卡会话，不是购买授权，不能用于向该用户扣款。


## OpenAPI

````yaml POST /agent/platform/vault-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/vault-sessions:
    post:
      summary: Create a Vault session
      description: >-
        Creates a short-lived Vault (hosted card-binding) session for the
        token's customer and returns its `vault_id`, the hosted page `url`, and
        the expiry. Requires `portal:write`.
      operationId: createVaultSession
      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/VaultSession'
              example:
                code: 200
                msg: Success
                data:
                  vault_id: vs_...
                  url: https://agent.clinkbill.dev/vault/vs_...
                  expires_at: '2026-11-09T10:30:00Z'
        '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:
    VaultSession:
      type: object
      properties:
        vault_id:
          type: string
          description: Opaque short-lived Vault session ID.
          example: vs_...
        url:
          type: string
          description: >-
            Hosted card-binding page URL built from Clink's configured page
            template. It contains `vault_id` and does not contain a portal
            token.
          example: https://agent.clinkbill.dev/vault/vs_...
        expires_at:
          type: string
          description: Time after which the session and the link no longer work.
          format: date-time
          example: '2026-11-09T10:30:00Z'
    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.