> ## 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 card session

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

The returned token is a browser session, not a portal token: keep the portal token on your server. `scope` is `card:manage`, and the token is accepted only on the card-management endpoints listed below. Every other `/a/**` endpoint returns `403` with `browser_scope_forbidden` (`code` `71211020`), including any attempt to read transactions or customer data. `/agent/**` requires a portal token, so the gateway rejects this browser session there with `401`.

There are no body fields. The session is always created for the token's customer.

The default lifetime is 30 minutes. When the token expires, call this endpoint again; do not reuse an expired token.

## Allowed endpoints

* `GET /a/cwallet/card/info`: List the customer's cards.
* `PUT /a/cwallet/card/setDefault`: Set the default card.
* `DELETE /a/cwallet/card/delete`: Delete a card.
* `GET /a/cwallet/get/countryAlpha2Code`: Country code inferred from the caller's IP, used to preselect the card form.
* `GET /a/cwallet/kms/public-key`: Fetch the public key used by the in-page add-card form; submit the encrypted card via `POST /a/cwallet/card/add` in the same session.
* `POST /a/cwallet/card/add`: Add a card; returns a 3-D Secure action when required.
* `POST /a/cwallet/redirect/callback`: Complete the 3-D Secure callback for card add.

Adding a card **is supported** in this card session: `card/add` returns a 3-D Secure action when needed, and `redirect/callback` completes it. The callback can also advance a purchase authorization, so the token must stay in the customer's own browser and must not be shared across customers. The Vault session ([Create a Vault session](https://docs.clinkbill.com/api-reference/agent-portal/create_vault_session.md)) remains an optional hosted add-card path. No other card, transaction, or customer-data endpoint is open to this session.

> [!WARNING]
>
> Treat `access_token` as a credential. Do not write it to logs, share it between users, or send it to a model. Use it only in the customer's own browser session, and request a new one for a different customer.


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