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

# Bind a card

> Creates a short-lived card-binding session for the token's customer and returns a URL that the user opens to add a card. Requires `portal:write`.

This endpoint does not create an instruction and does not authorize spending. Use it when the user only needs to add a card. To bind a card and sign in one flow, omit `payment_instrument_id` in [Create instruction](https://docs.clinkbill.com/api-reference/agent-portal/create_instruction.md) instead. There are no body fields for choosing a customer; the session is always created for the token's customer.

Each call creates a new, independent session with a short TTL. When the user opens the link and completes the card-binding ceremony, the card is added to the customer's payment methods ([List payment methods](https://docs.clinkbill.com/api-reference/agent-portal/list_payment_methods.md)). No instruction or authorization is created. The link can be reopened or re-exchanged while the session is still pending; it stops working once the card-binding ceremony completes or the session expires.

> [!WARNING]
>
> Treat the card-binding link as a credential. Do not forward it, screenshot it, or write it to logs; anyone who has the link can open it while it is valid and complete card binding for that customer. Deliver it only to the intended user.


## OpenAPI

````yaml POST /agent/platform/bind-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/bind-sessions:
    post:
      summary: Bind a card
      description: >-
        Creates a short-lived card-binding session for the token's customer and
        returns a URL that the user opens to add a card. Requires
        `portal:write`.
      operationId: createBindSession
      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/BindSession'
              example:
                code: 200
                msg: Success
                data:
                  session_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:
    BindSession:
      type: object
      properties:
        session_id:
          type: string
          description: Opaque short-lived card-binding session ID.
          example: vs_...
        url:
          type: string
          description: >-
            Short-lived card-binding link the user opens in a browser. It
            contains the session ID and does not contain a portal token.
          example: https://agent.clinkbill.dev/vault/vs_...
        expires_at:
          type: string
          description: Time after which the link no longer works.
          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.