> ## 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 Payment

> List all payout payments with optional filters

# List Payment

List all payout payments with optional filters.

## Query Parameters

<ParamField query="merchant_id" type="integer">
  Filter by merchant ID.

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

<ParamField query="external_id" type="string">
  Filter by your internal reference ID.

  Max length: `255` characters
</ParamField>

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

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

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

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

<ParamField query="updated_at_end" type="string">
  Filter payments 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 payout payment objects with pagination metadata.

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

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

    <ResponseField name="merchant_id" type="integer">
      Merchant ID that created the payout.
    </ResponseField>

    <ResponseField name="amount" type="integer">
      Payout amount in cents.
    </ResponseField>

    <ResponseField name="currency" type="string">
      Currency code.
    </ResponseField>

    <ResponseField name="country" type="string">
      Country code.
    </ResponseField>

    <ResponseField name="description" type="string">
      Payout description.
    </ResponseField>

    <ResponseField name="recipient" type="object">
      Recipient information.
    </ResponseField>

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

    <ResponseField name="external_id" type="string">
      Your internal reference ID.
    </ResponseField>

    <ResponseField name="notification_url" type="string">
      Webhook notification URL.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      Creation timestamp.
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      Last update timestamp.
    </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 Payments theme={null}
  curl --request GET \
    --url 'https://api.sandbox.wepayout.com.br/v2/payout/payments?page=1&per_page=15' \
    --header 'Accept: application/json' \
    --header 'Authorization: Bearer 123'
  ```

  ```bash cURL - Filter by External ID theme={null}
  curl --request GET \
    --url 'https://api.sandbox.wepayout.com.br/v2/payout/payments?external_id=ORDER-12345' \
    --header 'Accept: application/json' \
    --header 'Authorization: Bearer 123'
  ```

  ```bash cURL - Filter by Status theme={null}
  curl --request GET \
    --url '"https://api.sandbox.wepayout.com.br/v2/payout/payments?status_id=3"' \
    --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/payout/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}
  async function listPayouts(filters = {}) {
    const params = new URLSearchParams({
      page: filters.page || 1,
      per_page: filters.perPage || 15,
      ...filters
    });
    
    const response = await fetch(
      `https://api.sandbox.wepayout.com.br/v2/payout/payments?${params}`,
      {
        method: 'GET',
        headers: {
          'Accept': 'application/json',
          'Authorization': 'Bearer 123'
        }
      }
    );
    
    return await response.json();
  }

  // Usage examples
  // List all payouts
  const allPayouts = await listPayouts();

  // Filter by status
  const paidPayouts = await listPayouts({ status_id: 3 });

  // Filter by external ID
  const orderPayout = await listPayouts({ external_id: 'ORDER-12345' });

  // Filter by date range
  const monthPayouts = await listPayouts({
    created_at_start: '2024-01-01',
    created_at_end: '2024-01-31'
  });

  console.log(`Total payouts: ${allPayouts.meta.total}`);
  console.log(`Current page: ${allPayouts.meta.current_page} of ${allPayouts.meta.last_page}`);
  ```

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

  def list_payouts(filters=None):
      url = 'https://api.sandbox.wepayout.com.br/v2/payout/payments'
      headers = {
          'Accept': 'application/json',
          'Authorization': 'Bearer 123'
      }
      
      params = {
          'page': 1,
          'per_page': 15
      }
      
      if filters:
          params.update(filters)
      
      response = requests.get(url, headers=headers, params=params)
      return response.json()

  # Usage examples
  # List all payouts
  all_payouts = list_payouts()

  # Filter by status
  paid_payouts = list_payouts({'status_id': 3})

  # Filter by external ID
  order_payout = list_payouts({'external_id': 'ORDER-12345'})

  # Filter by date range
  month_payouts = list_payouts({
      'created_at_start': '2024-01-01',
      'created_at_end': '2024-01-31'
  })

  print(f"Total payouts: {all_payouts['meta']['total']}")
  print(f"Current page: {all_payouts['meta']['current_page']} of {all_payouts['meta']['last_page']}")
  ```
</CodeGroup>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "data": [
      {
        "id": 54321,
        "merchant_id": 1234,
        "amount": 10000,
        "currency": "BRL",
        "country": "BR",
        "description": "Payment for services rendered",
        "recipient": {
          "name": "João Silva",
          "email": "joao@example.com",
          "document": {
            "type": "CPF",
            "number": "12345678900"
          },
          "bank_account": {
            "bank_code": "001",
            "branch": "1234",
            "account": "12345678",
            "account_digit": "9",
            "account_type": "checking"
          }
        },
        "status": {
          "id": 3,
          "name": "Paid"
        },
        "external_id": "ORDER-12345",
        "notification_url": "https://your-domain.com/webhook/payout",
        "created_at": "2024-06-13T10:00:00.000000Z",
        "updated_at": "2024-06-13T10:05:00.000000Z"
      }
    ],
    "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/payout/payments?page=1",
      "last": "https://api.sandbox.wepayout.com.br/v2/payout/payments?page=5",
      "prev": null,
      "next": "https://api.sandbox.wepayout.com.br/v2/payout/payments?page=2"
    }
  }
  ```
</ResponseExample>

## Use Cases

<AccordionGroup>
  <Accordion title="List All Payouts">
    Retrieve all payouts with pagination:

    ```javascript theme={null}
    async function getAllPayouts(page = 1, perPage = 15) {
      const response = await listPayouts({ page, perPage });
      return response;
    }
    ```
  </Accordion>

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

    ```javascript theme={null}
    async function getPayoutsByStatus(statusId) {
      const response = await listPayouts({ status_id: statusId });
      return response.data;
    }

    // Get paid payouts (status_id = 3)
    const paidPayouts = await getPayoutsByStatus(3);
    ```
  </Accordion>

  <Accordion title="Search by External ID">
    Find a specific payout by your internal reference:

    ```javascript theme={null}
    async function findPayoutByExternalId(externalId) {
      const response = await listPayouts({ external_id: externalId });
      return response.data[0]; // Return first match
    }
    ```
  </Accordion>

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

    ```javascript theme={null}
    async function getPayoutsReport(startDate, endDate) {
      const response = await listPayouts({
        created_at_start: startDate,
        created_at_end: endDate,
        per_page: 100,
        sort_by: 'created_at',
        sort_order: 'asc'
      });
      
      return response;
    }

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

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

    ```javascript theme={null}
    async function getAllPayoutsWithPagination() {
      let allPayouts = [];
      let currentPage = 1;
      let hasMorePages = true;
      
      while (hasMorePages) {
        const response = await listPayouts({
          page: currentPage,
          per_page: 100
        });
        
        allPayouts = allPayouts.concat(response.data);
        
        hasMorePages = response.meta.current_page < response.meta.last_page;
        currentPage++;
      }
      
      return allPayouts;
    }
    ```
  </Accordion>
</AccordionGroup>

## Status IDs

Common payout status IDs for filtering:

| ID | Status Name | Description                       |
| -- | ----------- | --------------------------------- |
| 1  | Created     | Payout has been created           |
| 2  | Processing  | Payout is being processed         |
| 3  | Paid        | Payout has been paid successfully |
| 4  | Failed      | Payout failed                     |
| 5  | Rejected    | Payout rejected by compliance     |
| 6  | Cancelled   | Payout was cancelled              |

## Best Practices

<Note>
  **Pagination**: Always use pagination when listing payouts 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>

## Related Resources

<CardGroup cols={2}>
  <Card title="Create Payment" icon="plus" href="/api-reference/cash-out/payout/create-payment">
    Create a new payout payment
  </Card>

  <Card title="Callback Payment" icon="webhook" href="/api-reference/cash-out/payout/callback-payment">
    Receive payout status updates
  </Card>

  <Card title="Get Balance" icon="wallet" href="/api-reference/account/get-balance">
    Check your wallet balance
  </Card>

  <Card title="Get Statement" icon="file-invoice" href="/api-reference/account/get-statement">
    View account statement
  </Card>
</CardGroup>