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

# 获取凭证

> Requests a single-use payment credential for one purchase against an activated instruction and mandate. Requires `portal:write`.

响应有两种模式，取决于平台是否已在 Clink 登记公钥：

* **已登记公钥**（`matched: true`）：Clink 把卡字段密封到 `key`/`payload` 信封中，只有持有配对私钥的平台才能解密。
* **未登记公钥**（`matched: false`）：当服务端启用明文模式且 gateway 响应脱敏已生效时，Clink 在响应中以明文返回 DPAN 和动态 CVV。卡可以直接使用，但这些字段会以明文到达平台后端。

在 Clink 登记公钥即可使用加密模式；生产环境建议登记。

响应不下发凭证截止时间：凭证有效期以 `card`（明文模式）或解密后 payload（密文模式）中的 `dynamicDataExpiration` 为准。

## 登记平台公钥

联系 Clink 在目标环境登记平台的 RSA 公钥；公钥按平台 client name 映射。是否登记公钥决定响应模式：已登记时凭证密封到该公钥；未登记时，只有在服务端启用明文模式且 gateway 响应脱敏已生效的情况下才返回明文卡字段（MCP 等价的回退行为）；默认开关关闭时接口会 fail closed。生产使用前请先登记公钥。

> [!WARNING]
>
> 未登记公钥时，在服务端启用明文模式的前提下，响应会以明文把 DPAN 和动态 CVV 返回给平台后端。不要把这些字段写入日志、模型输入或普通存储，也不要在结账后保留。请在 Clink 登记公钥（生产环境建议）以切换到密封的 `key`/`payload` 模式。该明文回退行为与 MCP `get_credential` 一致。在 gateway 响应脱敏尚未生效的环境中不要启用明文模式：该模式由服务端 `portal-plaintext-enabled` 配置开关控制（默认关闭），开关关闭时接口会 fail closed 并返回 `71211012`（`credential_public_key_not_configured`），而不是明文卡字段。

## 解密密封响应

当 `matched` 为 `true` 时，使用平台私钥解密 `key` 和 `payload`。解密后的 payload 包含 `orderId`、`paymentExecutionDetailId`、`clientReferenceId`、`status`、网络凭证（DPAN、动态 CVV 和有效期）以及持卡人和地址字段。信封格式和解密示例见[解密](https://docs.clinkbill.com/cn/guides/agent/browser_pay.md#optional-decryption)。

不要把解密后的卡字段写入日志、模型输入或普通记录，并以解密后 payload 中的有效期信息（`dynamicDataExpiration`）为准判断凭证可用时间。保存 `client_reference_id`；[回报支付结果](https://docs.clinkbill.com/cn/api-reference/agent-portal/report_credential_result.md)会用到它。

## 幂等

`client_reference_id` 是幂等键。使用相同 `client_reference_id` 重试会返回同一凭证：`matched` 为 `true` 时返回同一密封信封，明文模式下从服务端加密缓存返回同一张卡，不会重复签发。携带不同参数复用时返回 `409`，`code` 为 `71211011`（`portal_conflict`）。


## OpenAPI

````yaml POST /agent/platform/credential
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/credential:
    post:
      summary: Get credential
      description: >-
        Requests a single-use payment credential for one purchase against an
        activated instruction and mandate. Requires `portal:write`.
      operationId: getCredential
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetCredentialRequest'
            example:
              instruction_id: inst_...
              mandate_id: mand_...
              client_reference_id: platform-ref-001
              amount: '12.50'
              currency_code: USD
              merchant_url: https://shop.example.com/checkout
              merchant_name: Example Store
              merchant_country_code: US
              merchant_order_id: shop-order-1
              products:
                - product_id: item-001
                  product_name: Example item
                  quantity: 1
                  unit_price: '12.50'
                  currency_code: USD
                  product_url: https://shop.example.com/item-001
              shipping_address:
                name: Example User
                line1: 1 Market Street
                city: San Francisco
                state: CA
                zip: '94105'
                country_code: US
      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:
                    oneOf:
                      - $ref: '#/components/schemas/SealedCredential'
                      - $ref: '#/components/schemas/PlaintextCredential'
              examples:
                sealed:
                  summary: 'Sealed (matched: true)'
                  value:
                    code: 200
                    msg: Success
                    data:
                      matched: true
                      key: <RSA-OAEP wrapped AES key, Base64>
                      payload: <AES-256-GCM ciphertext, Base64>
                plaintext:
                  summary: 'Plaintext (matched: false)'
                  value:
                    code: 200
                    msg: Success
                    data:
                      matched: false
                      order_id: order_...
                      payment_execution_detail_id: ped_...
                      client_reference_id: ...
                      card:
                        number: <DPAN>
                        securityCode: <dynamic CVV>
                        expiryMonth: '12'
                        expiryYear: '2028'
                        expiry: 12/2028
                        dynamicDataType: DAVV
                        dynamicDataExpiration: 1792380808
                        eci: '05'
                        paymentAccountReference: PAR-1
                      display:
                        brand: VISA
                        last4: '3797'
        '400':
          description: Invalid request body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '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'
        '409':
          description: >-
            `client_reference_id` was reused with different parameters
            (`portal_conflict`, `code` `71211011`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    GetCredentialRequest:
      type: object
      required:
        - instruction_id
        - mandate_id
        - client_reference_id
        - amount
        - currency_code
        - merchant_url
      properties:
        instruction_id:
          type: string
          description: '`ACTIVE` instruction owned by the token''s customer.'
          example: inst_...
        mandate_id:
          type: string
          description: Mandate under that instruction that covers the purchase.
          example: mand_...
        client_reference_id:
          type: string
          description: >-
            Platform-side reference and idempotency key for this purchase. Store
            it; the result report uses the same value.
          example: platform-ref-001
        amount:
          type: string
          description: Transaction amount, decimal string in major currency units.
          example: '12.50'
        currency_code:
          type: string
          description: Three-letter currency code.
          example: USD
        merchant_url:
          type: string
          description: Merchant checkout URL. Must use HTTPS.
          example: https://shop.example.com/checkout
        merchant_name:
          type: string
          description: Merchant display name. Defaults to the host of `merchant_url`.
          example: Example Store
        merchant_country_code:
          type: string
          description: Merchant country, ISO 3166-1 alpha-2.
          default: US
          example: US
        merchant_order_id:
          type: string
          description: Merchant-side order ID, when available.
          example: shop-order-1
        products:
          type: array
          description: Line items for the purchase.
          items:
            $ref: '#/components/schemas/Product'
        shipping_address:
          $ref: '#/components/schemas/ShippingAddress'
    SealedCredential:
      type: object
      title: 'Sealed (matched: true)'
      description: >-
        Returned when your platform has a registered public key. Contains only
        `matched`, `key`, and `payload`; the IDs are inside the decrypted
        payload.
      required:
        - matched
        - key
        - payload
      properties:
        matched:
          type: boolean
          description: '`true`: Clink sealed the credential with your registered public key.'
          example: true
        key:
          type: string
          description: RSA-OAEP-wrapped AES key, Base64.
          example: <RSA-OAEP wrapped AES key, Base64>
        payload:
          type: string
          description: >-
            AES-256-GCM ciphertext of the credential payload, Base64. The
            decrypted payload contains `orderId`, `paymentExecutionDetailId`,
            `clientReferenceId`, `status`, the network credential (DPAN, dynamic
            CVV, and expiry), and cardholder and address fields.
          example: <AES-256-GCM ciphertext, Base64>
    PlaintextCredential:
      type: object
      title: 'Plaintext (matched: false)'
      description: >-
        Returned when no public key is registered and plaintext mode is enabled
        server-side. Contains no `key` or `payload`.
      properties:
        matched:
          type: boolean
          description: >-
            `false`: no public key is registered and plaintext mode is enabled
            server-side, so the card fields are returned in plaintext.
          example: false
        order_id:
          type: string
          description: Order created for this credential.
          example: order_...
        payment_execution_detail_id:
          type: string
          description: Payment execution detail created for this credential.
          example: ped_...
        client_reference_id:
          type: string
          description: The `client_reference_id` you sent. Store it for result reporting.
          example: platform-ref-001
        card:
          $ref: '#/components/schemas/PlaintextCard'
        display:
          $ref: '#/components/schemas/CardDisplay'
    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.
    Product:
      type: object
      properties:
        product_id:
          type: string
          description: Product identifier.
          example: item-001
        product_name:
          type: string
          description: Product name.
          example: Example item
        quantity:
          type: integer
          description: Quantity.
          example: 1
        unit_price:
          type: string
          description: Unit price, decimal string in major currency units.
          example: '12.50'
        currency_code:
          type: string
          description: Three-letter currency code.
          example: USD
        product_url:
          type: string
          description: Product page URL.
          example: https://shop.example.com/item-001
    ShippingAddress:
      type: object
      description: Shipping address.
      properties:
        name:
          type: string
          description: Recipient name.
          example: Example User
        line1:
          type: string
          description: Address line 1.
          example: 1 Market Street
        line2:
          type: string
          description: Address line 2.
          example: Suite 100
        line3:
          type: string
          description: Address line 3.
        city:
          type: string
          description: City.
          example: San Francisco
        state:
          type: string
          description: State or province.
          example: CA
        zip:
          type: string
          description: Postal code.
          example: '94105'
        country_code:
          type: string
          description: Country code.
          example: US
    PlaintextCard:
      type: object
      description: >-
        Plaintext card fields. `number` and `securityCode` are always present;
        the other fields are omitted when not provided.
      required:
        - number
        - securityCode
      properties:
        number:
          type: string
          description: DPAN (the credential card number); it is never the underlying PAN.
          example: <DPAN>
        securityCode:
          type: string
          description: Dynamic security code (CVV) for the credential.
          example: <dynamic CVV>
        expiryMonth:
          type: string
          description: Expiry month as `MM`. All expiry fields may be absent.
          example: '12'
        expiryYear:
          type: string
          description: >-
            Expiry year as four digits. A two-digit network value is expanded to
            `20YY`.
          example: '2028'
        expiry:
          type: string
          description: >-
            Raw expiry string from the network, either `MM/YYYY` or `MM/YY`; it
            is not normalized.
          example: 12/2028
        dynamicDataType:
          type: string
          description: How the dynamic data must be used at checkout, for example `DAVV`.
          example: DAVV
        dynamicDataExpiration:
          type: integer
          description: >-
            Dynamic data expiry in Unix epoch seconds. This is the credential's
            validity; the response sends no separate deadline. Omitted when the
            network does not provide it.
          example: 1792380808
        eci:
          type: string
          description: Electronic commerce indicator.
          example: '05'
        paymentAccountReference:
          type: string
          description: Payment account reference.
          example: PAR-1
    CardDisplay:
      type: object
      description: Card display metadata.
      properties:
        brand:
          type: string
          description: Card scheme.
          example: VISA
        last4:
          type: string
          description: Last four digits of the credential card number.
          example: '3797'
  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.