---
title: "List transactions (charges / refunds)"
description: "Paginated."
canonical_url: "https://twominutebilling.com/help/developers/api-reference/webhooks/list-transactions"
---
# List transactions (charges / refunds)

> Paginated.

<api-operation method="GET" path="/v1/businesses/{biz}/transactions">
<template v-slot:docs="">

Cursor-paginated. This list used to cap at 50 rows with no way to reach the rest.

Five flat shorthands still work and fold into the same filter set: `?type=`, `?status=`, `?customer=`, `?invoice=` and `?gateway=`, each taking a single value. They are described here rather than listed as parameters because each shares its name with the filter of the same name below, and a parameter name may only be declared once. `?status=succeeded` and `?status[is]=succeeded` are equivalent; only the filter form takes operators, so `?status[in]=succeeded,failed` needs the bracket form.

## Path parameters

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Required
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        biz
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <strong>
        yes
      </strong>
    </td>
    
    <td>
      Business id (biz_…)
    </td>
  </tr>
</tbody>
</table>

## Query parameters

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Required
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        limit
      </code>
    </td>
    
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Maximum number of transactions to return.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        starting_after
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Opaque cursor from a previous next_cursor
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        offset
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      The previous page's next_offset — the same token as next_cursor under a second name. Pass one of offset or starting_after, not two different values.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        include_deleted
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Accepted; transactions are never deleted, so it changes nothing.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        q
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Free-text over transaction id / gateway / error code / customer (id, any name column, email) / invoice
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        sort_by[asc]
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Sort ascending by this field.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        sort_by[desc]
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Sort descending by this field.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        id
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Filter on <code>
        id
      </code>
      
      . Send as <code>
        id[<operator>]=<value>
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        type
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Filter on <code>
        type
      </code>
      
      . Send as <code>
        type[<operator>]=<value>
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        status
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      One of <code>
        in_progress
      </code>
      
      , <code>
        succeeded
      </code>
      
      , <code>
        failed
      </code>
      
      , <code>
        voided
      </code>
      
      , <code>
        timeout
      </code>
      
      , <code>
        needs_attention
      </code>
      
      , <code>
        late_failed
      </code>
      
      . The old spellings <code>
        success
      </code>
      
      , <code>
        failure
      </code>
      
       and <code>
        late_failure
      </code>
      
       are still accepted as deprecated aliases and match the same rows; responses never use them.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        currency
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Filter on <code>
        currency
      </code>
      
      . Send as <code>
        currency[<operator>]=<value>
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        gateway
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Filter by the gateway's key.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        gateway_key
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Filter on <code>
        gateway_key
      </code>
      
      . Send as <code>
        gateway_key[<operator>]=<value>
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        gateway_account
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Filter by the gateway account's id (gwa_…).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        reference_payment
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Filter by the id of the payment a refund refers to.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        id_at_gateway
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Filter on <code>
        id_at_gateway
      </code>
      
      . Send as <code>
        id_at_gateway[<operator>]=<value>
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        error_code
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Filter on <code>
        error_code
      </code>
      
      . Send as <code>
        error_code[<operator>]=<value>
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        error_text
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Filter on <code>
        error_text
      </code>
      
      . Send as <code>
        error_text[<operator>]=<value>
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        retriable
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Filter on <code>
        retriable
      </code>
      
      . Send as <code>
        retriable[<operator>]=<value>
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        trace_id
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Filter by the trace id of the gateway request.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        amount_minor
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Filter on <code>
        amount_minor
      </code>
      
      . Send as <code>
        amount_minor[<operator>]=<value>
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        created_at
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Filter on <code>
        created_at
      </code>
      
      . Send as <code>
        created_at[<operator>]=<value>
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        occurred_at
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      When the gateway says the money moved, which is not when we recorded it (<code>
        created_at
      </code>
      
      ) — reconcile against this one.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        settled_at
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Null until settlement is confirmed.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        updated_at
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Filter on <code>
        updated_at
      </code>
      
      . Send as <code>
        updated_at[<operator>]=<value>
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        customer
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Filter by the customer's id (cus_…).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        customer_name
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Compares the customer's RESOLVED display name — <code>
        first_name last_name
      </code>
      
      , else <code>
        company
      </code>
      
      , else the legacy <code>
        name
      </code>
      
       — the same string <code>
        customer_name
      </code>
      
       is reported as, so <code>
        contains=priya raghunathan
      </code>
      
       matches a customer who has only the two structured columns. Not a column: <code>
        is_present=false
      </code>
      
       means no name of any kind (filter <code>
        customer_email
      </code>
      
       for the address a nameless row displays instead).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        customer_email
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Filter on <code>
        customer_email
      </code>
      
      . Send as <code>
        customer_email[<operator>]=<value>
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        invoice
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Filter by the invoice's id (inv_…).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        subscription
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Filter by the subscription's id (sub_…).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        credit_note
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Filter by the credit note's id (cn_…).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        payment_method_brand
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Filter on <code>
        payment_method_brand
      </code>
      
      . Send as <code>
        payment_method_brand[<operator>]=<value>
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        payment_method_last4
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Filter on <code>
        payment_method_last4
      </code>
      
      . Send as <code>
        payment_method_last4[<operator>]=<value>
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        payment_method_type
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Filter on <code>
        payment_method_type
      </code>
      
      . Send as <code>
        payment_method_type[<operator>]=<value>
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        payment_method
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      The payment method's id (<code>
        pm_…
      </code>
      
      ) the attempt was made against.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        payment_intent
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Filter by the payment intent's id (pi_…).
    </td>
  </tr>
</tbody>
</table>

## Response

<table>
<thead>
  <tr>
    <th>
      Field
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      The object type; always <code>
        list
      </code>
      
      . One of <code>
        list
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        data
      </code>
    </td>
    
    <td>
      <code>
        array of object
      </code>
    </td>
    
    <td>
      The rows on this page.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        data.object
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      The object type.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        data.id
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      The transaction's id (txn_…).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        data.type
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      The transaction's type.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        data.status
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      The gateway outcome, in the same words payments and refunds use. Renamed from <code>
        success
      </code>
      
       / <code>
        failure
      </code>
      
       / <code>
        late_failure
      </code>
      
      , which are accepted on input only. One of <code>
        in_progress
      </code>
      
      , <code>
        succeeded
      </code>
      
      , <code>
        failed
      </code>
      
      , <code>
        voided
      </code>
      
      , <code>
        timeout
      </code>
      
      , <code>
        needs_attention
      </code>
      
      , <code>
        late_failed
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        data.amount_minor
      </code>
    </td>
    
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      The amount in minor units (integer), e.g. 2900 = $29.00.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        data.currency
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      The transaction's currency (ISO-4217 code).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        data.gateway_key
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      The gateway that processed the payment.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        data.customer
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      The customer's id (cus_…).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        data.invoice
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      The invoice's id (inv_…).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        data.reference_payment
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      The payment this transaction belongs to (a charge) or reverses (a refund) — the id payment events carry as <code>
        content.payment.id
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        data.unapplied_reason
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      Set when the payment settled after its invoice could take it, so the money went to the customer's excess balance instead. <code>
        invoice
      </code>
      
       still names the invoice the charge was made for; this field says the charge did not pay it. Null on refunds and on applied payments. One of <code>
        async_overpay
      </code>
      
      , <code>
        abandoned_debit
      </code>
      
      , <code>
        second_checkout
      </code>
      
      , <code>
        late_authorization
      </code>
      
      , <code>
        null
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        data.payment_method
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      The payment method used.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        data.instrument
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      The instrument class behind this transaction. Null when unknown.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        data.method_type
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      The payment method type that the payer used for the payment that this transaction belongs to (a charge) or reverses (a refund). It comes from the gateway's answer when the gateway gives one, else from the saved payment method that was charged. It can be different from <code>
        instrument.type
      </code>
      
       when one checkout offers several methods. Null when not known. One of <code>
        card
      </code>
      
      , <code>
        upi
      </code>
      
      , <code>
        wallet
      </code>
      
      , <code>
        bank_transfer
      </code>
      
      , <code>
        paypal
      </code>
      
      , <code>
        venmo
      </code>
      
      , <code>
        us_bank_account
      </code>
      
      , <code>
        sepa_debit
      </code>
      
      , <code>
        bacs_debit
      </code>
      
      , <code>
        au_becs_debit
      </code>
      
      , <code>
        nz_becs_debit
      </code>
      
      , <code>
        acss_debit
      </code>
      
      , <code>
        autogiro
      </code>
      
      , <code>
        betalingsservice
      </code>
      
      , <code>
        payto
      </code>
      
      , <code>
        null
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        data.pending_debit_cancel
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      Set on the single read of an in-progress payment whose gateway can cancel a pending debit. Then you can call <code>
        POST /v1/businesses/{biz}/payments/{pay}/cancel_pending_debit
      </code>
      
      . Null when you cannot.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        data.dispute_recording
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      Set on the single read of a succeeded payment whose gateway sends no dispute events. Then you can record a dispute with <code>
        POST /v1/businesses/{biz}/payments/{pay}/disputes
      </code>
      
      . Null when you cannot.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        data.awaiting_authentication
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      True only while <code>
        status: in_progress
      </code>
      
       and the debit is paused for the payer's additional-factor authentication. It is waiting on the CUSTOMER, not on the network. Set when the gateway stated it for this debit — at ANY amount, since an issuer may challenge whatever it likes — and otherwise predicted from the RBI/NPCI rule (INR above ₹15,000, card and UPI rails) for a rail that states nothing. A netbanking e-mandate debit is not predicted, because that rail authenticates once at registration; it is still reported if the gateway says this debit stopped.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        data.created_at
      </code>
    </td>
    
    <td>
      <code>
        string · ISO-8601
      </code>
    </td>
    
    <td>
      When the transaction was created (ISO-8601 UTC).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        has_more
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      Whether more rows exist after this page.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        next_cursor
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      Opaque; pass as starting_after
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        next_offset
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      Present only while has_more; the same opaque token as next_cursor — pass as offset
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        total
      </code>
    </td>
    
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      Filtered-set count; first page only
    </td>
  </tr>
</tbody>
</table>

## Status codes

<table>
<thead>
  <tr>
    <th>
      Status
    </th>
    
    <th>
      Meaning
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        200
      </code>
    </td>
    
    <td>
      Success
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        400
      </code>
    </td>
    
    <td>
      Bad limit / unknown filter field, operator or sort key
    </td>
  </tr>
</tbody>
</table>
</template>

<template v-slot:request="">

```bash [Request]
curl "$TMBILLING_URL/v1/businesses/biz_XXXXXXXXXXXX01/transactions?limit=10" \
  -H "Authorization: Bearer $TMBILLING_API_KEY"
```

</template>

<template v-slot:response="">
<code-group>

```json [200 OK]
{
  "object": "list",
  "data": [
    {
      "object": "transaction",
      "id": "txn_XXXXXXXXXXXX01",
      "type": "payment",
      "status": "in_progress",
      "amount_minor": 2900,
      "currency": "USD"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "next_offset": "eyJvZmZzZXQiOjEwfQ",
  "total": 2900
}
```

```json [400 Bad Request]
{
  "error": {
    "type": "invalid_request_error",
    "message": "Bad limit / unknown filter field, operator or sort key"
  }
}
```

</code-group>
</template>
</api-operation>


## Sitemap

See the full [sitemap](https://twominutebilling.com/sitemap.md) for all pages.