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

# Get credential

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

The response has two modes, depending on whether your platform has a public key registered with Clink:

* **Registered public key** (`matched: true`): Clink seals the card fields into a `key`/`payload` envelope that only your platform can decrypt with the matching private key.
* **No registered public key** (`matched: false`): when plaintext mode is enabled server-side and gateway response redaction is live, Clink returns the DPAN and dynamic CVV in plaintext in the response. The card can be used directly, but these fields reach your backend in plaintext.

Register a public key with Clink to use the encrypted mode; this is recommended for production.

The response sends no credential deadline: the validity is `dynamicDataExpiration` in `card` (plaintext mode) or in the decrypted payload (sealed mode).

## Public key registration

Contact Clink to register your platform's RSA public key in each environment; it is mapped to your platform client name. The registered key selects the response mode: with a key the credential is sealed to it; without one, Clink returns plaintext card fields only when plaintext mode is enabled server-side and gateway response redaction is live (the MCP-equivalent fallback). With the default gate off, the endpoint fails closed instead. Register the key before production use.

> [!WARNING]
>
> Without a registered public key, when plaintext mode is enabled server-side, the response returns the DPAN and dynamic CVV in plaintext to your backend. Keep these fields out of logs, model input, and ordinary storage, and do not keep them beyond the checkout. Register a public key with Clink (recommended for production) to switch to the sealed `key`/`payload` mode. This plaintext fallback matches MCP `get_credential`. Do not enable plaintext mode in environments where gateway response redaction is not yet active: it is config-gated server-side by `portal-plaintext-enabled` (default off), and with the gate off the endpoint fails closed with `71211012` (`credential_public_key_not_configured`) instead of returning plaintext card fields.

## Decrypt the sealed response

When `matched` is `true`, decrypt `key` and `payload` with your platform private key. The decrypted payload contains `orderId`, `paymentExecutionDetailId`, `clientReferenceId`, `status`, the network credential (DPAN, dynamic CVV, and expiry), and cardholder and address fields. The envelope format and a decryption example are in [Decryption](https://docs.clinkbill.com/guides/agent/browser_pay.md#optional-decryption).

Keep decrypted card fields out of logs, model input, and ordinary records, and use the validity information in the decrypted payload (`dynamicDataExpiration`) to decide when to use the credential. Save `client_reference_id`; [Report credential result](https://docs.clinkbill.com/api-reference/agent-portal/report_credential_result.md) uses it.

## Idempotency

`client_reference_id` is the idempotency key. Retrying with the same `client_reference_id` returns the same credential: the same sealed envelope when `matched` is `true`, and in plaintext mode the same card from the server-side encrypted cache, with no second issuance. Reusing it with different parameters returns `409` with `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.