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

# List Payment Methods

> List all payment method entities with filtering and pagination — in the gu1 entity model for card, account, and wallet records, with examples for list use.

## Overview

Retrieves a list of payment method entities with optional filtering by owner, type, or other criteria.

## Endpoint

```
GET http://api.gu1.ai/entities?entityType=payment_method
```

## Authentication

Requires a valid API key in the Authorization header:

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Query Parameters

<ParamField query="entityType" type="string" required>
  Must be `"payment_method"` to filter for payment methods
</ParamField>

<ParamField query="relationshipWith" type="string">
  Filter by relationship to another entity (e.g., person or company owner UUID)
</ParamField>

<ParamField query="limit" type="number">
  Number of results to return (default: 50, max: 100)
</ParamField>

<ParamField query="offset" type="number">
  Number of results to skip for pagination (default: 0)
</ParamField>

<ParamField query="sortBy" type="string">
  Field to sort by: `createdAt`, `updatedAt`, `riskScore`
</ParamField>

<ParamField query="sortOrder" type="string">
  Sort order: `asc` or `desc` (default: `desc`)
</ParamField>

## Example Requests

### List All Payment Methods

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "http://api.gu1.ai/entities?entityType=payment_method" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'http://api.gu1.ai/entities?entityType=payment_method',
    {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    }
  );

  const { entities, pagination } = await response.json();
  console.log(`Found ${entities.length} payment methods`);
  ```

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

  response = requests.get(
      'http://api.gu1.ai/entities',
      headers={
          'Authorization': 'Bearer YOUR_API_KEY'
      },
      params={
          'entityType': 'payment_method'
      }
  )

  data = response.json()
  print(f"Found {len(data['entities'])} payment methods")
  ```
</CodeGroup>

### List Payment Methods for a Person

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "http://api.gu1.ai/entities?entityType=payment_method&relationshipWith=person-uuid-123" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const personId = 'person-uuid-123';

  const response = await fetch(
    `http://api.gu1.ai/entities?entityType=payment_method&relationshipWith=${personId}`,
    {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    }
  );

  const { entities } = await response.json();

  console.log(`Person has ${entities.length} payment methods`);

  entities.forEach(pm => {
    const type = pm.entityData.paymentMethod.type;
    const last4 = pm.entityData.paymentMethod.last4;
    console.log(`  - ${type} ending in ${last4}`);
  });
  ```

  ```python Python theme={null}
  person_id = 'person-uuid-123'

  response = requests.get(
      'http://api.gu1.ai/entities',
      headers={'Authorization': 'Bearer YOUR_API_KEY'},
      params={
          'entityType': 'payment_method',
          'relationshipWith': person_id
      }
  )

  entities = response.json()['entities']

  print(f"Person has {len(entities)} payment methods")
  for pm in entities:
      pm_type = pm['entityData']['paymentMethod']['type']
      last4 = pm['entityData']['paymentMethod'].get('last4', 'N/A')
      print(f"  - {pm_type} ending in {last4}")
  ```
</CodeGroup>

### List with Pagination

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "http://api.gu1.ai/entities?entityType=payment_method&limit=25&offset=0&sortBy=createdAt&sortOrder=desc" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  async function listPaymentMethods(page = 0, pageSize = 25) {
    const offset = page * pageSize;

    const response = await fetch(
      `http://api.gu1.ai/entities?` + new URLSearchParams({
        entityType: 'payment_method',
        limit: pageSize,
        offset: offset,
        sortBy: 'createdAt',
        sortOrder: 'desc'
      }),
      {
        headers: {
          'Authorization': 'Bearer YOUR_API_KEY'
        }
      }
    );

    return await response.json();
  }

  // Get first page
  const page1 = await listPaymentMethods(0);
  console.log(`Page 1: ${page1.entities.length} results`);

  // Get second page
  const page2 = await listPaymentMethods(1);
  console.log(`Page 2: ${page2.entities.length} results`);
  ```

  ```python Python theme={null}
  def list_payment_methods(page=0, page_size=25):
      offset = page * page_size

      response = requests.get(
          'http://api.gu1.ai/entities',
          headers={'Authorization': 'Bearer YOUR_API_KEY'},
          params={
              'entityType': 'payment_method',
              'limit': page_size,
              'offset': offset,
              'sortBy': 'createdAt',
              'sortOrder': 'desc'
          }
      )

      return response.json()

  # Get first page
  page1 = list_payment_methods(0)
  print(f"Page 1: {len(page1['entities'])} results")

  # Get second page
  page2 = list_payment_methods(1)
  print(f"Page 2: {len(page2['entities'])} results")
  ```
</CodeGroup>

## Response

<ResponseField name="success" type="boolean">
  Whether the request was successful
</ResponseField>

<ResponseField name="entities" type="array">
  Array of payment method entities

  <Expandable title="properties">
    <ResponseField name="id" type="string">
      UUID of the payment method entity
    </ResponseField>

    <ResponseField name="entityType" type="string">
      Always `"payment_method"`
    </ResponseField>

    <ResponseField name="entityData" type="object">
      Payment method data
    </ResponseField>

    <ResponseField name="relationships" type="array">
      Array of relationships
    </ResponseField>

    <ResponseField name="riskScore" type="number">
      Calculated risk score (if analyzed)
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      ISO 8601 timestamp of creation
    </ResponseField>

    <ResponseField name="updatedAt" type="string">
      ISO 8601 timestamp of last update
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pagination" type="object">
  Pagination information

  <Expandable title="properties">
    <ResponseField name="total" type="number">
      Total number of payment methods matching filters
    </ResponseField>

    <ResponseField name="limit" type="number">
      Number of results returned in this page
    </ResponseField>

    <ResponseField name="offset" type="number">
      Number of results skipped
    </ResponseField>

    <ResponseField name="hasMore" type="boolean">
      Whether there are more results available
    </ResponseField>
  </Expandable>
</ResponseField>

## Response Example

```json theme={null}
{
  "success": true,
  "entities": [
    {
      "id": "payment-method-uuid-123",
      "entityType": "payment_method",
      "entityData": {
        "paymentMethod": {
          "type": "credit_card",
          "last4": "4242",
          "brand": "visa",
          "expiryMonth": "12",
          "expiryYear": "2025",
          "holderName": "John Doe",
          "issuerCountry": "BR",
          "funding": "credit"
        }
      },
      "relationships": [
        {
          "targetEntityId": "person-uuid-123",
          "relationshipType": "owns",
          "strength": 1.0
        }
      ],
      "riskScore": 15,
      "createdAt": "2024-01-15T10:00:00.000Z",
      "updatedAt": "2024-12-23T10:00:00.000Z"
    },
    {
      "id": "payment-method-uuid-456",
      "entityType": "payment_method",
      "entityData": {
        "paymentMethod": {
          "type": "bank_account",
          "accountType": "checking",
          "bank": "Banco do Brasil",
          "currency": "BRL",
          "holderName": "John Doe"
        }
      },
      "relationships": [
        {
          "targetEntityId": "person-uuid-123",
          "relationshipType": "owns",
          "strength": 1.0
        }
      ],
      "riskScore": 5,
      "createdAt": "2024-02-10T14:30:00.000Z",
      "updatedAt": "2024-12-23T10:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 2,
    "limit": 50,
    "offset": 0,
    "hasMore": false
  }
}
```

## Use Cases

### Find All Credit Cards for a Person

```javascript theme={null}
async function findPersonCreditCards(personId) {
  const response = await fetch(
    `http://api.gu1.ai/entities?entityType=payment_method&relationshipWith=${personId}`,
    {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    }
  );

  const { entities } = await response.json();

  // Filter for credit cards only
  const creditCards = entities.filter(
    e => e.entityData.paymentMethod.type === 'credit_card'
  );

  return creditCards;
}
```

### Find High-Risk Payment Methods

```javascript theme={null}
async function findHighRiskPaymentMethods(minRiskScore = 70) {
  let allHighRisk = [];
  let offset = 0;
  const limit = 100;
  let hasMore = true;

  while (hasMore) {
    const response = await fetch(
      `http://api.gu1.ai/entities?` + new URLSearchParams({
        entityType: 'payment_method',
        limit,
        offset,
        sortBy: 'riskScore',
        sortOrder: 'desc'
      }),
      {
        headers: {
          'Authorization': 'Bearer YOUR_API_KEY'
        }
      }
    );

    const { entities, pagination } = await response.json();

    // Filter by risk score
    const highRisk = entities.filter(e => e.riskScore >= minRiskScore);
    allHighRisk = allHighRisk.concat(highRisk);

    // If we got entities with risk score below threshold, stop
    if (entities.length > 0 && entities[entities.length - 1].riskScore < minRiskScore) {
      break;
    }

    hasMore = pagination.hasMore;
    offset += limit;
  }

  return allHighRisk;
}
```

### Group Payment Methods by Type

```javascript theme={null}
async function groupPaymentMethodsByType(personId) {
  const response = await fetch(
    `http://api.gu1.ai/entities?entityType=payment_method&relationshipWith=${personId}`,
    {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    }
  );

  const { entities } = await response.json();

  const grouped = entities.reduce((acc, pm) => {
    const type = pm.entityData.paymentMethod.type;
    if (!acc[type]) {
      acc[type] = [];
    }
    acc[type].push(pm);
    return acc;
  }, {});

  return grouped;
}

// Usage
const grouped = await groupPaymentMethodsByType('person-uuid-123');
console.log(`Credit cards: ${grouped.credit_card?.length || 0}`);
console.log(`Bank accounts: ${grouped.bank_account?.length || 0}`);
console.log(`PIX keys: ${grouped.pix?.length || 0}`);
```

## Error Responses

### 400 Bad Request

```json theme={null}
{
  "error": "Invalid query parameters",
  "details": {
    "limit": "Must be between 1 and 100"
  }
}
```

### 401 Unauthorized

```json theme={null}
{
  "error": "Invalid or missing API key"
}
```

## See Also

* [Create Payment Method](/en/api-reference/payment-methods/create)
* [Get Payment Method](/en/api-reference/payment-methods/get)
* [Update Payment Method](/en/api-reference/payment-methods/update)
* [Analyze Payment Method](/en/api-reference/entities/analyze)