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

# List Charge

> List all charges with optional filters

# List Charge

List all charges with optional filters.

## Query Parameters

<ParamField query="merchant_id" type="integer">
  Merchant id of the account that is creating the payin.

  Min: `2`, Max: `10000`
</ParamField>

<ParamField query="invoice" type="string">
  Your identification number.

  Max length: `255` characters
</ParamField>

<ParamField query="payment_method" type="string">
  Payment method that will be used in payin.

  Allowed values: `pix`, `boleto`
</ParamField>

<ParamField query="status_id" type="integer">
  Filter by status ID.
</ParamField>

<ParamField query="created_at_start" type="string">
  Filter charges created after this date. Format: `YYYY-MM-DD`
</ParamField>

<ParamField query="created_at_end" type="string">
  Filter charges created before this date. Format: `YYYY-MM-DD`
</ParamField>

<ParamField query="updated_at_start" type="string">
  Filter charges updated after this date. Format: `YYYY-MM-DD`
</ParamField>

<ParamField query="updated_at_end" type="string">
  Filter charges updated before this date. Format: `YYYY-MM-DD`
</ParamField>

<ParamField query="page" type="integer">
  Page number for pagination.

  Default: `1`
</ParamField>

<ParamField query="per_page" type="integer">
  Number of items per page.

  Default: `15`, Max: `100`
</ParamField>

<ParamField query="sort_by" type="string">
  Field to sort by.

  Allowed values: `id`, `created_at`, `updated_at`, `amount`

  Default: `id`
</ParamField>

<ParamField query="sort_order" type="string">
  Sort order.

  Allowed values: `asc`, `desc`

  Default: `desc`
</ParamField>

## Response

Returns an array of charge objects with pagination metadata.

<ResponseField name="data" type="array">
  Array of charge objects.

  <Expandable title="Charge Object">
    <ResponseField name="id" type="integer">
      WEpayment's auto generated id.
    </ResponseField>

    <ResponseField name="merchant" type="object">
      Merchant object.
    </ResponseField>

    <ResponseField name="hash" type="string">
      WEpayments auto generated hash.
    </ResponseField>

    <ResponseField name="payment_page" type="string">
      The WEpayments payment page URL.
    </ResponseField>

    <ResponseField name="our_number" type="string">
      The bank identification number.
    </ResponseField>

    <ResponseField name="invoice" type="string">
      Your identification number.
    </ResponseField>

    <ResponseField name="notification_url" type="string">
      The url where we will submit the callbacks.
    </ResponseField>

    <ResponseField name="payment_method" type="string">
      Payment method: `pix` or `boleto`.
    </ResponseField>

    <ResponseField name="amount" type="integer">
      The payin total amount in cents.
    </ResponseField>

    <ResponseField name="paid_amount" type="integer">
      The total amount of the payin paid.
    </ResponseField>

    <ResponseField name="refunded_amount" type="integer">
      Amount refunded from this charge.
    </ResponseField>

    <ResponseField name="description" type="string">
      Instructions displayed to the user.
    </ResponseField>

    <ResponseField name="buyer" type="object">
      The person you are charging object.
    </ResponseField>

    <ResponseField name="originator_legal_entity" type="object">
      Final Beneficiary object.
    </ResponseField>

    <ResponseField name="pix" type="object">
      Pix QRCode specific instructions (when payment\_method is pix).
    </ResponseField>

    <ResponseField name="boleto" type="object">
      Boleto specific instructions (when payment\_method is boleto).
    </ResponseField>

    <ResponseField name="status" type="object">
      Status object.
    </ResponseField>

    <ResponseField name="status_history" type="array">
      Status History object.
    </ResponseField>

    <ResponseField name="substatus" type="object">
      Sub status object.
    </ResponseField>

    <ResponseField name="refunds" type="array">
      Refund object.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      Cash-in created date.
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      Cash-in update date.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta" type="object">
  Pagination metadata.

  <Expandable title="Pagination">
    <ResponseField name="current_page" type="integer">
      Current page number.
    </ResponseField>

    <ResponseField name="from" type="integer">
      First item number on current page.
    </ResponseField>

    <ResponseField name="last_page" type="integer">
      Last page number.
    </ResponseField>

    <ResponseField name="per_page" type="integer">
      Items per page.
    </ResponseField>

    <ResponseField name="to" type="integer">
      Last item number on current page.
    </ResponseField>

    <ResponseField name="total" type="integer">
      Total number of items.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="links" type="object">
  Pagination links.

  <Expandable title="Links">
    <ResponseField name="first" type="string">
      URL to first page.
    </ResponseField>

    <ResponseField name="last" type="string">
      URL to last page.
    </ResponseField>

    <ResponseField name="prev" type="string">
      URL to previous page (null if on first page).
    </ResponseField>

    <ResponseField name="next" type="string">
      URL to next page (null if on last page).
    </ResponseField>
  </Expandable>
</ResponseField>

## Request Example

<CodeGroup>
  ```bash cURL - All Charges theme={null}
  curl --request GET \
    --url '"https://api.sandbox.wepayout.com.br/v2/payin/payments?page=1&per_page=15"' \
    --header 'Accept: application/json' \
    --header 'Authorization: Bearer 123'
  ```

  ```bash cURL - Filter by Invoice theme={null}
  curl --request GET \
    --url 'https://api.sandbox.wepayout.com.br/v2/payin/payments?invoice=YOUR-CODE1234' \
    --header 'Accept: application/json' \
    --header 'Authorization: Bearer 123'
  ```

  ```bash cURL - Filter by Payment Method theme={null}
  curl --request GET \
    --url 'https://api.sandbox.wepayout.com.br/v2/payin/payments?payment_method=pix' \
    --header 'Accept: application/json' \
    --header 'Authorization: Bearer 123'
  ```

  ```bash cURL - Filter by Date Range theme={null}
  curl --request GET \
    --url 'https://api.sandbox.wepayout.com.br/v2/payin/payments?created_at_start=2024-01-01&created_at_end=2024-12-31' \
    --header 'Accept: application/json' \
    --header 'Authorization: Bearer 123'
  ```

  ```javascript JavaScript theme={null}
  const params = new URLSearchParams({
    page: 1,
    per_page: 15,
    payment_method: 'pix',
    sort_by: 'created_at',
    sort_order: 'desc'
  });

  const response = await fetch(`https://api.sandbox.wepayout.com.br/v2/payin/payments?${params}`, {
    method: 'GET',
    headers: {
      'Accept': 'application/json',
      'Authorization': 'Bearer 123'
    }
  });

  const data = await response.json();
  console.log(`Total charges: ${data.meta.total}`);
  console.log(`Current page: ${data.meta.current_page} of ${data.meta.last_page}`);
  console.log('Charges:', data.data);
  ```

  ```python Python theme={null}
  import requests

  params = {
      'page': 1,
      'per_page': 15,
      'payment_method': 'pix',
      'sort_by': 'created_at',
      'sort_order': 'desc'
  }

  headers = {
      'Accept': 'application/json',
      'Authorization': 'Bearer 123'
  }

  response = requests.get(
      'https://api.sandbox.wepayout.com.br/v2/payin/payments',
      params=params,
      headers=headers
  )

  data = response.json()
  print(f"Total charges: {data['meta']['total']}")
  print(f"Current page: {data['meta']['current_page']} of {data['meta']['last_page']}")
  print('Charges:', data['data'])
  ```
</CodeGroup>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "data": [
      {
        "id": 32457,
        "merchant": {
          "id": 1234,
          "name": "Merchant Name"
        },
        "hash": "885fc0a0fb0e678b82a998daafbc081cbb03c1c862f8e57d580b3b7af152cf47",
        "payment_page": "https://pagar.sandbox.wepayout.co/?hash=885fc0a0fb0e678b82a998daafbc081cbb03c1c862f8e57d580b3b7af152cf47",
        "our_number": "20230",
        "invoice": "YOUR-CODE1234",
        "notification_url": "https://client.callback.com/notify-payin",
        "payment_method": "pix",
        "amount": 5000,
        "paid_amount": 5000,
        "refunded_amount": 0,
        "description": "Esse Pix é referente ao pedido 123 na loja abcd",
        "created_at": "2024-06-12T23:04:24.000000Z",
        "updated_at": "2024-06-12T23:04:27.000000Z",
        "buyer": {
          "name": "Buyer Name",
          "email": "buyer-email@wepayments.com.br",
          "document": {
            "type": "CPF",
            "number": "34960826312"
          }
        },
        "status": {
          "id": 4,
          "name": "Pago"
        }
      }
    ],
    "meta": {
      "current_page": 1,
      "from": 1,
      "last_page": 5,
      "per_page": 15,
      "to": 15,
      "total": 73
    },
    "links": {
      "first": "https://api.sandbox.wepayout.com.br/v2/payin/payments?page=1",
      "last": "https://api.sandbox.wepayout.com.br/v2/payin/payments?page=5",
      "prev": null,
      "next": "https://api.sandbox.wepayout.com.br/v2/payin/payments?page=2"
    }
  }
  ```
</ResponseExample>

## Use Cases

<AccordionGroup>
  <Accordion title="List All Charges">
    Retrieve all charges with pagination:

    ```javascript theme={null}
    async function getAllCharges(page = 1, perPage = 15) {
      const response = await fetch(
        `https://api.sandbox.wepayout.com.br/v2/payin/payments?page=${page}&per_page=${perPage}`,
        {
          headers: {
            'Authorization': 'Bearer YOUR_TOKEN',
            'Accept': 'application/json'
          }
        }
      );
      
      return await response.json();
    }
    ```
  </Accordion>

  <Accordion title="Filter by Status">
    Get charges by specific status:

    ```javascript theme={null}
    async function getChargesByStatus(statusId) {
      const response = await fetch(
        `https://api.sandbox.wepayout.com.br/v2/payin/payments?status_id=${statusId}`,
        {
          headers: {
            'Authorization': 'Bearer YOUR_TOKEN',
            'Accept': 'application/json'
          }
        }
      );
      
      return await response.json();
    }

    // Get paid charges (status_id = 4)
    const paidCharges = await getChargesByStatus(4);
    ```
  </Accordion>

  <Accordion title="Search by Invoice">
    Find a specific charge by invoice number:

    ```javascript theme={null}
    async function findChargeByInvoice(invoice) {
      const response = await fetch(
        `https://api.sandbox.wepayout.com.br/v2/payin/payments?invoice=${invoice}`,
        {
          headers: {
            'Authorization': 'Bearer YOUR_TOKEN',
            'Accept': 'application/json'
          }
        }
      );
      
      const data = await response.json();
      return data.data[0]; // Return first match
    }
    ```
  </Accordion>

  <Accordion title="Date Range Report">
    Generate a report for a specific date range:

    ```javascript theme={null}
    async function getChargesReport(startDate, endDate) {
      const params = new URLSearchParams({
        created_at_start: startDate,
        created_at_end: endDate,
        per_page: 100,
        sort_by: 'created_at',
        sort_order: 'asc'
      });
      
      const response = await fetch(
        `https://api.sandbox.wepayout.com.br/v2/payin/payments?${params}`,
        {
          headers: {
            'Authorization': 'Bearer YOUR_TOKEN',
            'Accept': 'application/json'
          }
        }
      );
      
      return await response.json();
    }

    // Get charges from January 2024
    const report = await getChargesReport('2024-01-01', '2024-01-31');
    ```
  </Accordion>

  <Accordion title="Pagination Handler">
    Handle pagination to retrieve all charges:

    ```javascript theme={null}
    async function getAllChargesWithPagination() {
      let allCharges = [];
      let currentPage = 1;
      let hasMorePages = true;
      
      while (hasMorePages) {
        const response = await fetch(
          `https://api.sandbox.wepayout.com.br/v2/payin/payments?page=${currentPage}&per_page=100`,
          {
            headers: {
              'Authorization': 'Bearer YOUR_TOKEN',
              'Accept': 'application/json'
            }
          }
        );
        
        const data = await response.json();
        allCharges = allCharges.concat(data.data);
        
        hasMorePages = data.meta.current_page < data.meta.last_page;
        currentPage++;
      }
      
      return allCharges;
    }
    ```
  </Accordion>
</AccordionGroup>

## Status IDs

Common status IDs for filtering:

| ID | Status Name          | Description      |
| -- | -------------------- | ---------------- |
| 1  | Criado               | Charge created   |
| 2  | Processando          | Processing       |
| 3  | Aguardando Pagamento | Awaiting payment |
| 4  | Pago                 | Paid             |
| 5  | Cancelado            | Cancelled        |
| 6  | Expirado             | Expired          |
| 7  | Rejeitado            | Rejected         |
| 8  | Estornado            | Refunded         |

## Best Practices

<Note>
  **Pagination**: Always use pagination when listing charges to avoid performance issues. The default page size is 15, with a maximum of 100 items per page.
</Note>

<Warning>
  **Date Filters**: When using date range filters, ensure the range is not too large to avoid timeouts. For large date ranges, consider breaking them into smaller chunks.
</Warning>

<Tip>
  **Caching**: Consider caching the results for frequently accessed pages to reduce API calls and improve performance.
</Tip>