> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentcard.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a card

> Create a one-time virtual card against the member's added card, then key its credentials into your checkout and [close it](/companies/api/reference/member-card-close) when you're done. Sandbox answers `201` with an open test card. Production answers `202 approval_pending` with an `approval_url` the member confirms with a passkey; retry with the SAME `Idempotency-Key` (or watch [flow status](/companies/api/reference/member-flow-status)) until the card is `open`, then read it once on [Get a card](/companies/api/reference/member-card-get). Credentials stay valid for about an hour, so create the card right before checkout.

Create a one-time virtual card against the member's added card. This is the
bring-your-own-checkout flow: create the card, key its `credentials` into
the merchant's payment form yourself, then
[close it](/companies/api/reference/member-card-close).

**Sandbox** answers `201` with an open test card, credentials included.
**Production** answers `202 approval_pending` with an `approval_url` the
member confirms with a passkey; retry with the **same** `Idempotency-Key`
until the card is `open`. Credentials stay valid for about an hour, so
create the card right before checkout, not ahead of time.


## OpenAPI

````yaml openapi.json POST /api/v2/cards
openapi: 3.1.0
info:
  title: Agentcard API
  version: 2.0.0
  description: >-
    The Agentcard v2 API — connect your users and verify their identity from
    your own backend. Every call is authenticated with a platform access token
    minted from your `client_id` + `client_secret`.
servers:
  - url: https://api.agentcard.sh
    description: >-
      There is one base URL. Sandbox vs production is decided by the client
      credential you use, never by the host.
security:
  - platformToken: []
tags:
  - name: Authentication
    description: >-
      Exchange your client credentials for a platform access token, and
      introspect what a token acts as.
  - name: Connect
    description: >-
      Connect a user to your platform: send a one-time code, verify it, record
      consent, and keep the connection alive.
  - name: Identity verification
    description: >-
      Verify a connected user's identity: upload their ID, submit any extra
      fields we ask for, then show a short face scan.
  - name: Wallet funding
    description: >-
      Fund a connected user's wallet from your own UI — request a payment link,
      relay the phone verification code, and poll until the funds land.
  - name: Withdrawals
    description: >-
      Move money out of a connected user's wallet — to a saved bank account or a
      crypto address on Base. Transfers are processed manually by the Agentcard
      team, usually within 1-3 business days.
paths:
  /api/v2/cards:
    post:
      tags:
        - Member cards
      summary: Create a card
      description: >-
        Create a one-time virtual card against the member's added card, then key
        its credentials into your checkout and [close
        it](/companies/api/reference/member-card-close) when you're done.
        Sandbox answers `201` with an open test card. Production answers `202
        approval_pending` with an `approval_url` the member confirms with a
        passkey; retry with the SAME `Idempotency-Key` (or watch [flow
        status](/companies/api/reference/member-flow-status)) until the card is
        `open`, then read it once on [Get a
        card](/companies/api/reference/member-card-get). Credentials stay valid
        for about an hour, so create the card right before checkout.
      operationId: memberCardCreate
      parameters:
        - name: Idempotency-Key
          in: header
          required: true
          schema:
            type: string
          description: >-
            Stable key for THIS card intent (your order id). Retries with the
            same key resume the same card; they never create a second one.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - amount_cents
              properties:
                amount_cents:
                  type: integer
                  minimum: 100
                  maximum: 2000000
                  description: >-
                    Exact amount in cents the card can spend, e.g. 2500 =
                    $25.00.
                currency:
                  type: string
                  enum:
                    - usd
                connected_card_id:
                  type: string
                  description: >-
                    Draw on a specific added card. Omit to use the newest active
                    one.
                merchant:
                  type: object
                  properties:
                    name:
                      type: string
                    url:
                      type: string
                description:
                  type: string
                  maxLength: 200
                metadata:
                  type: object
            example:
              amount_cents: 2500
              currency: usd
              description: 'Order #1042'
      responses:
        '201':
          description: The card is open (sandbox, and frictionless production mints).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MemberCard'
        '202':
          description: >-
            `approval_pending`: share `approval_url` with the member, then retry
            with the same `Idempotency-Key`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MemberCard'
        '400':
          description: >-
            `invalid_request`, `idempotency_key_required`, or
            `multi_use_connected_unsupported`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          description: >-
            `subscription_required`: production needs an active Agentcard
            subscription.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: >-
            `attach_required`: no active added card (start one on Add a card),
            or `request_in_flight`: the same key is still processing; retry in a
            few seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: >-
            `byoc_unavailable`: the card network is briefly unavailable. Retry
            with the same `Idempotency-Key`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - userAccessToken: []
components:
  schemas:
    MemberCard:
      type: object
      description: A one-time virtual card created against the member's added card.
      properties:
        object:
          type: string
          example: card
        id:
          type: string
        status:
          type: string
          enum:
            - approval_pending
            - open
            - in_use
            - paused
            - closed
          description: >-
            Envelope status. `open` carries credentials; `approval_pending`
            carries `approval_url`.
        spend_limit_cents:
          type: integer
        balance_cents:
          type: integer
        connected_card_id:
          type: string
          nullable: true
          description: The attachment this card draws on.
        last4:
          type: string
        expiry:
          type: string
          example: 12/30
        created_at:
          type: string
          format: date-time
        approval_url:
          type: string
          description: >-
            Only while `approval_pending`: the page where the member approves
            this purchase with a passkey.
        expires_at:
          type: string
          format: date-time
          description: 'Only while `approval_pending`: when the approval window closes.'
        closed_reason:
          type: string
          description: 'Only when `closed`: `used`, `canceled`, `expired`, or `declined`.'
        credentials:
          type: object
          description: >-
            Only on an `open` card: the one-time credential to key into a
            checkout. Never persist it.
          properties:
            number:
              type: string
            exp_month:
              type: integer
              nullable: true
            exp_year:
              type: integer
              nullable: true
            cvc:
              type: string
        credentials_status:
          type: string
          description: >-
            `protected` when the member requires an approval per reveal; `retry`
            when the credential read should be retried.
    Error:
      type: object
      description: Every v2 error uses the same envelope.
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: A stable, machine-readable string (snake_case). Branch on this.
            message:
              type: string
              description: A human-readable explanation, safe to log.
            docs:
              type: string
              description: A link back to the reference.
            field_errors:
              type: object
              additionalProperties:
                type: string
              description: Only on `invalid_fields` — names each field to fix.
            warnings:
              type: array
              items:
                type: string
              description: >-
                Only on document upload errors — actionable feedback safe to
                show the user.
  responses:
    Unauthorized:
      description: >-
        `unauthorized` — the platform access token is missing or expired.
        Exchange your client credentials for a fresh one.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    platformToken:
      type: http
      scheme: bearer
      description: >-
        A platform access token. Get one on the **Create an access token**
        endpoint by exchanging your `client_id` + `client_secret`, then send it
        as `Authorization: Bearer <token>`. Tokens live one hour.
    userAccessToken:
      type: http
      scheme: bearer
      description: >-
        The user's connection access_token (user authentication), or an
        org-minted buy_token for org-owned accounts.

````