Marqeta Transactions API

openapi: 3.0.3
info:
  contact:
    email: support@marqeta.com
    name: Marqeta
  description: Marqeta's Core API endpoints, conveniently annotated to enable code generation (including SDKs), test cases, and documentation. Currently in beta.
  termsOfService: https://www.marqeta.com/api-terms
  title: Core accepted countries Transactions API
  version: 3.0.39
servers:
- url: /v3
security:
- mqAppAndAccessToken: []
tags:
- description: '// Conditional snippet for beta or internal content

    include::../../maturity-admonition-banner.adoc[]


    // This source file is used by InfoDev to generate API reference documentation.

    // File location in GitHub is:

    // https://github.marqeta.com/openapi/coreapi/blob/main/openapi/transactions/openapi.yaml


    The `/transactions` resource represents the electronic messages that carry information used for payment processing.

    A transaction usually originates when a cardholder attempts to make a payment, either online or at a physical point of sale.


    You can receive information about transactions as they occur by configuring webhooks.

    Learn about configuring webhooks in the <</developer-guides/about-webhooks, About Webhooks>> guide.

    See the transaction events for which you can set up webhooks in the <</core-api/event-types, Event Types>> API reference page.


    You can also retrieve transactions associated with specific cards, merchants, and account holders using the endpoints described here.


    For an overview of transactions and the `transaction` object, including the complete list of <</developer-guides/about-transactions#_transaction_response_codes, transaction response codes>>, see <</developer-guides/about-transactions, About Transactions>>.


    [TIP]

    Use the `/transactions` endpoint to retrieve smaller datasets (up to one page).

    For best performance when requesting larger datasets, use the <</diva-api/introduction, DiVA API>>.'
  name: Transactions
paths:
  /accounts/{account_token}/transactions:
    get:
      description: Retrieve an array of transactions on a credit account.
      operationId: ListAccountTransactions
      parameters:
      - description: Unique identifier of the credit account for which you want to retrieve transactions.
        explode: false
        in: path
        name: account_token
        required: true
        schema:
          type: string
        style: simple
      - description: Number of transaction resources to retrieve.
        explode: true
        in: query
        name: count
        required: false
        schema:
          default: 20
          maximum: 100
          minimum: 1
          type: integer
        style: form
      - description: Starting index for pagination.
        explode: true
        in: query
        name: start_index
        required: false
        schema:
          default: 0
          minimum: 0
          type: integer
        style: form
      - description: Start date for transaction filter. Defaults to 30 days ago if not provided.
        explode: true
        in: query
        name: start_date
        required: false
        schema:
          format: date
          type: string
        style: form
      - description: End date for transaction filter. Defaults to current date if not provided.
        explode: true
        in: query
        name: end_date
        required: false
        schema:
          format: date
          type: string
        style: form
      - description: Filter by transaction status. Allowed values are PENDING, POSTED, DECLINED, and ERROR. When no status is provided, PENDING, POSTED, DECLINED, and ERROR transactions are returned by default.
        explode: true
        in: query
        name: status
        required: false
        schema:
          enum:
          - PENDING
          - POSTED
          - DECLINED
          - ERROR
          type: string
        style: form
      - description: Filter transactions by card token.
        explode: true
        in: query
        name: card_token
        required: false
        schema:
          type: string
        style: form
      - description: Filter transactions by user token.
        explode: true
        in: query
        name: user_token
        required: false
        schema:
          type: string
        style: form
      responses:
        '200':
          content:
            application/json:
              example:
                count: 1
                data:
                - account_token: 019b3f13-751b-7aef-8a3c-8d57a3a229e7
                  amount: 12.5
                  created_at: 2025-12-20 02:29:24
                  merchant:
                    address:
                      city: Seattle
                      country: US
                    mcc: null
                    name: Online Bookstore Inc.
                  status: PENDING
                  token: 650a5643-7f0f-45dc-a91f-dea195e420c7
                  type: authorization
                is_more: true
                start_index: 0
              schema:
                $ref: '#/components/schemas/AccountTransactionPageResponse'
          description: Expected response to a valid request.
      summary: List account transactions
      tags:
      - Transactions
  /transactions:
    get:
      description: 'List all transactions.


        By default, this endpoint returns transactions conducted within the last 30 days.

        To return transactions older than 30 days, you must include the `start_date` and `end_date` query parameters in your request.


        By default, `GET /transactions` returns transactions having either `PENDING` or `COMPLETION` states.


        This endpoint supports <</core-api/field-filtering, field filtering>> and <</core-api/sorting-and-pagination, pagination>>.'
      operationId: getTransactions
      parameters:
      - description: The number of transactions to retrieve.
        explode: true
        in: query
        name: count
        required: false
        schema:
          default: 10
          format: int32
          type: integer
        style: form
      - description: The sort order index of the first resource in the returned array.
        explode: true
        in: query
        name: start_index
        required: false
        schema:
          default: 0
          format: int32
          type: integer
        style: form
      - description: 'Comma-delimited list of fields to return (`field_1,field_2`, and so on).

          Leave blank to return all fields.'
        explode: true
        in: query
        name: fields
        required: false
        schema:
          type: string
        style: form
      - description: 'Field on which to sort.

          Use any field in the resource model, or one of the system fields `lastModifiedTime` or `createdTime`.

          Prefix the field name with a hyphen (`-`) to sort in descending order.

          Omit the hyphen to sort in ascending order.'
        explode: true
        in: query
        name: sort_by
        required: false
        schema:
          default: -user_transaction_time
          enum:
          - -created_time
          - created_time
          - -user_transaction_time
          - user_transaction_time
          type: string
        style: form
      - description: 'The starting date (or date-time) of a date range from which to return transactions.

          To return transactions for a single day, enter the same date in both the `start_date` and `end_date` fields.'
        explode: true
        in: query
        name: start_date
        required: false
        schema:
          type: string
        style: form
      - description: 'The ending date (or date-time) of a date range from which to return transactions.

          To return transactions for a single day, enter the same date in both the `end_date` and `start_date` fields.'
        explode: true
        in: query
        name: end_date
        required: false
        schema:
          type: string
        style: form
      - description: Comma-delimited list of transaction types to include.
        explode: true
        in: query
        name: type
        required: false
        schema:
          type: string
        style: form
      - description: The unique identifier of the user account holder.
        explode: true
        in: query
        name: user_token
        required: false
        schema:
          type: string
        style: form
      - description: The unique identifier of the business account holder.
        explode: true
        in: query
        name: business_token
        required: false
        schema:
          type: string
        style: form
      - description: The unique identifier of the acting user.
        explode: true
        in: query
        name: acting_user_token
        required: false
        schema:
          type: string
        style: form
      - description: The unique identifier of the card.
        explode: true
        in: query
        name: card_token
        required: false
        schema:
          type: string
        style: form
      - description: Account token
        explode: true
        in: query
        name: account_token
        required: false
        schema:
          type: string
        style: form
      - description: Comma-delimited list of transaction states to display.
        explode: true
        in: query
        name: state
        required: false
        schema:
          default: PENDING,COMPLETION
          type: string
        style: form
      - description: Specifies the API version for the request.
        explode: true
        in: query
        name: version
        required: false
        schema:
          type: string
        style: form
      - description: Start identifier
        explode: true
        in: query
        name: start_identifier
        required: false
        schema:
          format: int64
          type: integer
        style: form
      responses:
        '200':
          content:
            application/json:
              example:
                count: 2
                data:
                - acquirer:
                    institution_country: '840'
                    institution_id_code: '428399181'
                    retrieval_reference_number: '528294182583'
                    system_trace_audit_number: '656761'
                  acting_user_token: 99f323d4-298f-4b0c-93b1-19b2d9921eb8
                  amount: 10.0
                  card:
                    metadata: null
                  card_security_code_verification:
                    response:
                      code: '0000'
                      memo: Card security code match
                    type: CVV1
                  card_token: 02cc766c-24a5-4c3b-adcf-0e5e27b09329
                  created_time: 2024-08-21 17:26:29+00:00
                  currency_code: USD
                  duration: 537
                  fraud:
                    network:
                      account_risk_score: '7'
                      transaction_risk_score: 97
                  gpa:
                    available_balance: 0.0
                    balances:
                      USD:
                        available_balance: 0.0
                        credit_balance: 0.0
                        currency_code: USD
                        impacted_amount: 10.0
                        ledger_balance: 20.0
                        pending_credits: 0.0
                    credit_balance: 0.0
                    currency_code: USD
                    impacted_amount: 10.0
                    ledger_balance: 20.0
                    pending_credits: 0.0
                  gpa_order:
                    amount: 10.0
                    created_time: 2024-08-21 17:26:30+00:00
                    currency_code: USD
                    funding:
                      amount: 10.0
                      gateway_log:
                        duration: 481
                        message: Approved or completed successfully
                        order_number: '1200'
                        response:
                          code: '200'
                          data:
                            jit_funding:
                              address_verification:
                                gateway:
                                  on_file:
                                    postal_code: '94601'
                                    street_address: 2000 High St
                                  response:
                                    code: '0000'
                                    memo: Address and postal code match
                              amount: 10.0
                              method: pgfs.authorization
                              original_jit_funding_token: your-jit-funding-token
                              token: your-jit-funding-token
                              user_token: your-jit-funding-user
                        timed_out: false
                        transaction_id: your-jit-funding-token
                      source:
                        active: true
                        created_time: 2024-08-21 17:25:43+00:00
                        is_default_account: false
                        last_modified_time: 2024-08-21 17:25:43+00:00
                        name: PGFS for simulating transactions
                        token: '**********dd5f'
                        type: programgateway
                    funding_source_token: '**********dd5f'
                    jit_funding:
                      acting_user_token: 99f323d4-298f-4b0c-93b1-19b2d9921eb8
                      amount: 10.0
                      method: pgfs.authorization
                      token: 251bdc52-588a-4291-8c5d-6ded3a67e1a8
                      user_token: 99f323d4-298f-4b0c-93b1-19b2d9921eb8
                    last_modified_time: 2024-08-21 17:26:30+00:00
                    response:
                      code: '0000'
                      memo: Approved or completed successfully
                    state: PENDING
                    token: 592b8164-a4af-45ee-ab24-13a4bb43e6b2
                    transaction_token: cd22cff7-2845-4508-a916-cf89fd9edae1
                    user_token: 99f323d4-298f-4b0c-93b1-19b2d9921eb8
                  issuer_payment_node: b9a60cd41a2cc1c23090ed3666bdbf1z
                  issuer_received_time: 2024-08-21 17:26:29+00:00
                  network: MARQETA
                  pos:
                    card_holder_presence: false
                    card_presence: false
                    is_recurring: false
                    pan_entry_mode: MAG_STRIPE
                    partial_approval_capable: false
                    pin_entry_mode: 'TRUE'
                    purchase_amount_only: false
                    terminal_attendance: ATTENDED
                  preceding_related_transaction_token: 06a8fe88-58b1-4682-a8ad-96eb973e1d74
                  response:
                    code: '0000'
                    memo: Approved or completed successfully
                  state: PENDING
                  subnetwork: GATEWAY_JIT
                  token: cd22cff7-2845-4508-a916-cf89fd9edae1
                  transaction_metadata:
                    payment_channel: OTHER
                  type: gpa.credit.authorization
                  user:
                    metadata: null
                  user_token: 99f323d4-298f-4b0c-93b1-19b2d9921eb8
                  user_transaction_time: 2024-08-21 17:26:29+00:00
                - acquirer:
                    institution_country: '840'
                    institution_id_code: '428399181'
                    retrieval_reference_number: '528294182583'
                    system_trace_audit_number: '656761'
                  acquirer_fee_amount: 0.0
                  acting_user_token: 99f323d4-298f-4b0c-93b1-19b2d9921eb8
                  amount: 10.0
                  approval_code: '761515'
                  card:
                    metadata: null
                  card_acceptor:
                    city: Berkeley
                    country_code: USA
                    mcc: '6411'
                    mid: '000000000011111'
                    name: Aegis Fleet Services
                    street_address: 111 Main St
                  card_security_code_verification:
                    response:
                      code: '0000'
                      memo: Card security code match
                    type: CVV1
                  card_token: 02cc766c-24a5-4c3b-adcf-0e5e27b09329
                  created_time: 2024-08-21 17:26:29+00:00
                  currency_code: USD
                  duration: 622
                  fraud:
                    network:
                      account_risk_score: '7'
                      transaction_risk_score: 97
                  gpa:
                    available_balance: 0.0
                    balances:
                      USD:
                        available_balance: 0.0
                        credit_balance: 0.0
                        currency_code: USD
                        impacted_amount: -10.0
                        ledger_balance: 20.0
                        pending_credits: 0.0
                    credit_balance: 0.0
                    currency_code: USD
                    impacted_amount: -10.0
                    ledger_balance: 20.0
                    pending_credits: 0.0
                  gpa_order:
                    amount: 10.0
                    created_time: 2024-08-21 17:26:30+00:00
                    funding:
                      amount: 10.0
                      currency_code: USD
                      funding_source_token: '**********dd5f'
                      gateway_log:
                        duration: 481
                        message: Approved or completed successfully
                        order_number: '1200'
                        response:
                          code: '200'
                          data:
                            jit_funding:
                              address_verification:
                                gateway:
                                  on_file:
                                    postal_code: '94601'
                                    street_address: 2000 High St
                                  response:
                                    code: '0000'
                                    memo: Address and postal code match
                              amount: 10.0
                              method: pgfs.authorization
                              original_jit_funding_token: your-jit-funding-token
                              token: your-jit-funding-token
                              user_token: your-jit-funding-user
                        timed_out: false
                        transaction_id: your-jit-funding-token
                      jit_funding:
                        acting_user_token: 99f323d4-298f-4b0c-93b1-19b2d9921eb8
                        amount: 10.0
                        method: pgfs.authorization
                        token: 251bdc52-588a-4291-8c5d-6ded3a67e1a8
                        user_token: 99f323d4-298f-4b0c-93b1-19b2d9921eb8
                      source:
                        active: true
                        created_time: 2024-08-21 17:25:43+00:00
                        is_default_account: false
                        last_modified_time: 2024-08-21 17:25:43+00:00
                        name: PGFS for simulating transactions
                        token: '**********dd5f'
                        type: programgateway
                      user_token: 99f323d4-298f-4b0c-93b1-19b2d9921eb8
                    last_modified_time: 2024-08-21 17:26:30+00:00
                    response:
                      code: '0000'
                      memo: Approved or completed successfully
                    state: PENDING
                    token: 592b8164-a4af-45ee-ab24-13a4bb43e6b2
                    transaction_token: cd22cff7-2845-4508-a916-cf89fd9edae1
                  issuer_payment_node: b9a60cd41a2cc1c23090ed3666bdbf1z
                  issuer_received_time: 2024-08-21 17:26:29+00:00
                  network: VISA
                  pos:
                    card_holder_presence: false
                    card_presence: false
                    is_recurring: false
                    pan_entry_mode: MAG_STRIPE
                    partial_approval_capable: false
                    pin_entry_mode: 'TRUE'
                    purchase_amount_only: false
                    terminal_attendance: ATTENDED
                    terminal_id: TR100000
                  request_amount: 10.0
                  response:
                    code: '0000'
                    memo: Approved or completed successfully
                  settlement_date: 2024-08-21 00:00:00+00:00
                  state: PENDING
                  subnetwork: VISANET
                  token: 06a8fe88-58b1-4682-a8ad-96eb973e1d74
                  transaction_metadata:
                    payment_channel: OTHER
                  type: authorization
                  user:
                    metadata: null
                  user_token: 99f323d4-298f-4b0c-93b1-19b2d9921eb8
                  user_transaction_time: 2024-08-21 17:26:29+00:00
                end_index: 1
                is_more: true
                start_index: 0
              schema:
                $ref: '#/components/schemas/TransactionModelListResponse'
          description: Success
        '400':
          content: {}
          description: User input error/Bad request
        '500':
          content: {}
          description: Server error
      summary: List transactions
      tags:
      - Transactions
  /transactions/fundingsource/{funding_source_token}:
    get:
      description: 'List transactions for a specific funding source.


        By default, this endpoint returns transactions conducted within the last 30 days.

        To return transactions older than 30 days, you must include the `start_date` and `end_date` query parameters in your request.


        By default, `GET /transactions/fundingsource/{funding_source_token}` returns transactions having either `PENDING` or `COMPLETION` states.


        This endpoint supports <</core-api/field-filtering, field filtering>> and <</core-api/sorting-and-pagination, pagination>>.'
      operationId: getTransactionsFundingsourceFundingsourcetoken
      parameters:
      - description: The unique identifier of the funding account.
        explode: false
        in: path
        name: funding_source_token
        required: true
        schema:
          type: string
        style: simple
      - description: The number of transactions to retrieve.
        explode: true
        in: query
        name: count
        required: false
        schema:
          default: 10
          format: int32
          type: integer
        style: form
      - description: The sort order index of the first resource in the returned array.
        explode: true
        in: query
        name: start_index
        required: false
        schema:
          default: 0
          format: int32
          type: integer
        style: form
      - description: 'Comma-delimited list of fields to return (`field_1,field_2`, and so on).

          Leave blank to return all fields.'
        explode: true
        in: query
        name: fields
        required: false
        schema:
          type: string
        style: form
      - description: 'Field on which to sort.

          Use any field in the resource model, or one of the system fields `lastModifiedTime` or `createdTime`.

          Prefix the field name with a hyphen (`-`) to sort in descending order.

          Omit the hyphen to sort in ascending order.'
        explode: true
        in: query
        name: sort_by
        required: false
        schema:
          default: -user_transaction_time
          enum:
          - -created_time
          - created_time
          - -user_transaction_time
          - user_transaction_time
          type: string
        style: form
      - description: 'The starting date (or date-time) of a date range from which to return transactions.

          To return transactions for a single day, enter the same date in both the `start_date` and `end_date` fields.'
        explode: true
        in: query
        name: start_date
        required: false
        schema:
          type: string
        style: form
      - description: 'The ending date (or date-time) of a date range from which to return transactions.

          To return transactions for a single day, enter the same date in both the `end_date` and `start_date` fields.'
        explode: true
        in: query
        name: end_date
        required: false
        schema:
          type: string
        style: form
      - description: Comma-delimited list of transaction types to include.
        explode: true
        in: query
        name: type
        required: false
        schema:
          type: string
        style: form
      - description: Specifies whether to return credit or debit transactions.
        explode: true
        in: query
        name: polarity
        required: false
        schema:
          enum:
          - CREDIT
          - DEBIT
          - PENDING_CREDIT
          - PENDING_DEBIT
          type: string
        style: form
      - description: Specifies the API version for the request.
        explode: true
        in: query
        name: version
        required: false
        schema:
          type: string
        style: form
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionModelListResponse'
          description: Success
        '400':
          content: {}
          description: User input error/Bad request
        '500':
          content: {}
          description: Server error
      summary: List transactions for a funding account
      tags:
      - Transactions
  /transactions/{token}:
    get:
      description: 'Retrieve a specific transaction.

        Include the `token` path parameter to identify the transaction.


        [NOTE]

        Transactions are not available in real time via this endpoint, and typically appear after 30 seconds.

        On occasion, a transaction may require up to four hours to appear.'
      operationId: getTransactionsToken
      parameters:
      - description: The unique identifier of the transaction.
        explode: false
        in: path
        name: token
        required: true
        schema:
          type: string
        style: simple
      - description: 'Comma-delimited list of fields to return (`field_1,field_2`, and so on).

          Leave blank to return all fields.'
        explode: true
        in: query
        name: fields
        required: false
        schema:
          type: string
        style: form
      - description: Specifies the API version for the request.
        explode: true
        in: query
        name: version
        required: false
        schema:
          type: string
        style: form
      responses:
        '200':
          content:
            application/json:
              example:
                acquirer:
                  institution_country: '840'
                  institution_id_code: '428399181'
                  retrieval_reference_number: '528294182583'
                  system_trace_audit_number: '656761'
                acquirer_fee_amount: 0.0
                acting_user_token: 99f323d4-298f-4b0c-93b1-19b2d9921eb8
                amount: 10.0
                approval_code: '761515'
                card:
                  metadata: null
                card_acceptor:
                  city: Berkeley
                  country_code: USA
                  mcc: '6411'
                  mid: '000000000011111'
                  name: Aegis Fleet Services
                  street_address: 111 Main St
                card_security_code_verification:
                  response:
                    code: '0000'
                    memo: Card security code match
                  type: CVV1
                card_token: 02cc766c-24a5-4c3b-adcf-0e5e27b09329
                cardholder_authentication_data:
                  electronic_commerce_indicator: authentication_successful
                  verification_result: verified
                  verification_value_created_by: issuer_acs
                created_time: 2024-08-21 17:26:29+00:00
                currency_code: USD
                currency_conversion:
                  network:
                    conversion_rate: 1.0
                    dynamic_currency_conversion: false
                    original_amount: 10.0
                    original_currency_code: '840'
                duration: 622
                fraud:
                  network:
                    account_risk_score: '7'
                    transaction_risk_score: 97
                gpa:
                  available_balance: 0.0
                  balances:
                    USD:
                      available_balance: 0.0
                      credit_balance: 0.0
                      currency_code: USD
                      impacted_amount: -10.0
                      ledger_balance: 20.0
                      pending_credits: 0.0
                  credit_balance: 0.0
                  currency_code: USD
                  impacted_amount: -10.0
                  ledger_balance: 20.0
                  pending_credits: 0.0
                gpa_order:
                  amount: 10
                  created_time: 2024-08-21 17:26:30+00:00
                  currency_code: USD
                  funding:
                    amount: 10.0
                    gateway_log:
                      duration: 481
                      message: Approved or completed successfully
                      order_number: '1200'
                      response:
                        code: '200'
                        data:
                        - jit_funding:
                            address_verification:
                              gateway:
                                on_file:
                                  postal_code: '94601'
                                  street_address: 2000 High St
                                response:
                                  code: '0000'
                                  memo: Address and postal code match
                            amount: 10.0
                            method: pgfs.authorization
                            original_jit_funding_token: your-jit-funding-token
                            token: your-jit-funding-token
                            user_token: your-jit-funding-user
                      timed_out: false
                      transaction_id: your-jit-funding-token
                    source:
                      active: true
                      created_time: 2024-08-21 17:25:43+00:00
                      is_default_account: false
                      last_modified_time: 2024-08-21 17:25:43+00:00
                      name: PGFS for simulating transactions
                      token: '**********dd5f'
                      type: programgateway
                  funding_source_token: '**********dd5f'
                  jit_funding:
                    acting_user_token: 99f323d4-298f-4b0c-93b1-19b2d9921eb8
                    amount: 10.0
                    method: pgfs.authorization
                    token: 251bdc52-588a-4291-8c5d-6ded3a67e1a8
                    user_token: 99f323d4-298f-4b0c-93b1-19b2d9921eb8
                  last_modified_time: 2024-08-21 17:26:30+00:00
                  response:
                    code: '0000'
                    memo: Approved or completed successfully
                  state: PENDING
                  token: 592b8164-a4af-45ee-ab24-13a4bb43e6b2
                  transaction_token: cd22cff7-2845-4508-a916-cf89fd9edae1
                  user_token: 99f323d4-298f-4b0c-93b1-19b2d9921eb8
                issuer_payment_node: b9a60cd41a2cc1c23090ed3666bdbf1z
                issuer_received_time: 2024-08-21 17:26:29+00:00
                network: VISA
                pos:
                  card_holder_presence: false
                  card_presence: false
                  is_recurring: false
                  pan_entry_mode: MAG_STRIPE
                  partial_approval_capable: false
                  pin_entry_mode: 'TRUE'
                  purchase_amount_only: false
                  terminal_attendance

# --- truncated at 32 KB (224 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/marqeta/refs/heads/main/openapi/marqeta-transactions-api-openapi.yml