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

# List transactions

> List every charge and Vault checkout on your company, newest first.

Every charge on your company's cards and every Vault checkout your agents
opened, newest first, in your credential's mode.

To read everything, keep passing the `cursor` from each page until `has_more`
is `false`. A charge that lands while you page never shifts or repeats a row.

A `card_id` or `user_id` that isn't yours reads as an empty list, the same as
one with no transactions yet.


## OpenAPI

````yaml openapi.json GET /api/v2/transactions
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.
paths:
  /api/v2/transactions:
    get:
      tags:
        - Transactions
      summary: List transactions
      description: >-
        Every charge on your company's cards and every Vault checkout your
        agents opened, newest first, in your credential's mode: sandbox
        credentials read sandbox transactions, production credentials read live
        ones. A purchase is listed once.
      operationId: transactionsList
      parameters:
        - name: limit
          in: query
          required: false
          description: Rows per page, 1 to 100. Defaults to 50.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
        - name: cursor
          in: query
          required: false
          description: >-
            The `cursor` from the previous page. Leave it out for the newest
            rows.
          schema:
            type: string
        - name: status
          in: query
          required: false
          description: Only transactions in this status.
          schema:
            type: string
            enum:
              - pending
              - authorized
              - cleared
              - declined
              - voided
              - refunded
        - name: card_id
          in: query
          required: false
          description: >-
            Only charges on this card. Leaves Vault checkouts out, since they
            aren't on a card of yours.
          schema:
            type: string
        - name: user_id
          in: query
          required: false
          description: Only this user's transactions.
          schema:
            type: string
        - name: created_after
          in: query
          required: false
          description: Only transactions at or after this ISO 8601 time.
          schema:
            type: string
            format: date-time
        - name: created_before
          in: query
          required: false
          description: Only transactions before this ISO 8601 time.
          schema:
            type: string
            format: date-time
      responses:
        '200':
          description: One page of transactions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionList'
        '400':
          description: >-
            `invalid_request`: a filter isn't one this endpoint accepts.
            `invalid_cursor`: the cursor isn't one this API returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
      security:
        - platformToken: []
components:
  schemas:
    TransactionList:
      type: object
      required:
        - object
        - data
        - cursor
        - has_more
      properties:
        object:
          type: string
          description: Always `list`.
          enum:
            - list
        data:
          type: array
          items:
            $ref: '#/components/schemas/Transaction'
        cursor:
          type:
            - string
            - 'null'
          description: Pass it as `cursor` to read the next page. Null on the last page.
        has_more:
          type: boolean
          description: Whether another page follows.
    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.
    Transaction:
      type: object
      required:
        - object
        - id
        - source
        - status
        - amount
        - currency
        - merchant
        - created_at
      properties:
        object:
          type: string
          description: Always `transaction`.
          enum:
            - transaction
        id:
          type: string
          description: The transaction's id, the `transaction_id` its webhook events carry.
        source:
          type: string
          description: >-
            What paid: `issued`, a card your company issued; `added`, a one-time
            card made from a card the user added; `vault`, a checkout with a
            card in the user's Vault.
          enum:
            - issued
            - added
            - vault
        status:
          type: string
          description: >-
            `pending`, waiting for the user's approval; `authorized`, approved
            and not settled yet; `cleared`, settled; `declined`; `voided`,
            cancelled, expired or reversed, so no money moved; `refunded`.
          enum:
            - pending
            - authorized
            - cleared
            - declined
            - voided
            - refunded
        amount:
          type:
            - integer
            - 'null'
          description: The figure billed, in the smallest unit of `currency`.
        currency:
          type:
            - string
            - 'null'
          description: The billing currency, lowercase ISO 4217.
        amount_display:
          type:
            - string
            - 'null'
          description: '`amount` and `currency` ready to show, such as `$12.50`.'
        merchant_amount:
          type:
            - integer
            - 'null'
          description: The merchant's own figure, when it charged in another currency.
        merchant_currency:
          type:
            - string
            - 'null'
          description: The currency of `merchant_amount`.
        merchant:
          type: string
          description: The merchant's name.
        mcc:
          type:
            - string
            - 'null'
          description: The merchant category code. Null on a Vault checkout.
        decline_reason:
          type:
            - string
            - 'null'
          description: Why it was declined, when it was.
        user_id:
          type:
            - string
            - 'null'
          description: The user it belongs to. Null on a card nobody has claimed yet.
        card_id:
          type:
            - string
            - 'null'
          description: The card charged. Null on a Vault checkout.
        vault_card_id:
          type:
            - string
            - 'null'
          description: The Vault card used. Null on a card charge.
        last4:
          type:
            - string
            - 'null'
          description: The last four digits of the card charged. Null on a Vault checkout.
        processor_transaction_id:
          type:
            - string
            - 'null'
          description: >-
            The processor's reference, the `id` a `transaction.*` webhook event
            carries. Null on a Vault checkout.
        created_at:
          type: string
          description: When it happened.
          format: date-time
  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.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.