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

# Payment Methods Overview

> Manage payment methods as first-class entities in gu1 — issue cards, link accounts, track usage, and apply fraud and compliance rules.

## Overview

Payment methods in Gu1 are represented as **entities** of type `payment_method`. This allows you to track credit cards, bank accounts, wallets, and other payment instruments associated with persons or companies.

<Info>
  Payment methods are created using the universal `/entities` endpoint with `entityType: "payment_method"`.
</Info>

## What is a Payment Method Entity?

A payment method entity represents any financial instrument used for transactions:

* **Credit Cards** - Visa, Mastercard, Amex, etc.
* **Debit Cards** - Bank-issued debit cards
* **Bank Accounts** - Checking, savings accounts
* **Digital Wallets** - PayPal, Apple Pay, Google Pay, etc.
* **Cryptocurrency Wallets** - Bitcoin, Ethereum addresses

## Key Features

### Entity Relationships

Payment methods can be linked to other entities:

* **Owned by** - Link to the person or company owner
* **Used in** - Link to transactions where this payment method was used
* **Associated with** - Link to devices used for transactions

### Risk Analysis

Payment methods can be analyzed for fraud detection:

* Transaction velocity monitoring
* Geographic anomaly detection
* Device fingerprinting correlation
* Historical usage patterns

### Use Cases

1. **Fraud Detection** - Detect suspicious payment method usage patterns
2. **Card Verification** - Validate card details and ownership
3. **Account Monitoring** - Track unusual account activity
4. **Transaction Tracking** - Link transactions to payment sources
5. **Multi-account Detection** - Identify shared payment methods across users

## Data Structure

Payment method entities contain:

```json theme={null}
{
  "entityType": "payment_method",
  "entityData": {
    "paymentMethod": {
      "type": "credit_card",           // Type of payment method
      "last4": "4242",                  // Last 4 digits
      "brand": "visa",                  // Card brand
      "expiryMonth": "12",              // Expiration month
      "expiryYear": "2025",             // Expiration year
      "holderName": "John Doe",         // Cardholder name
      "issuerCountry": "BR",            // Issuing country
      "bin": "424242",                  // Bank Identification Number
      "fingerprint": "abc123xyz",       // Unique fingerprint
      "funding": "credit",              // Funding type (credit/debit)
      "network": "visa"                 // Payment network
    }
  },
  "relationships": [
    {
      "targetEntityId": "person-uuid-123",
      "relationshipType": "owns",
      "strength": 1.0
    }
  ]
}
```

## Payment Method Types

### Credit Card

```json theme={null}
{
  "type": "credit_card",
  "brand": "visa",
  "last4": "4242",
  "expiryMonth": "12",
  "expiryYear": "2025",
  "holderName": "John Doe",
  "issuerCountry": "BR",
  "bin": "424242",
  "funding": "credit"
}
```

### Bank Account

```json theme={null}
{
  "type": "bank_account",
  "accountNumber": "12345-6",
  "accountType": "checking",
  "bank": "Banco do Brasil",
  "currency": "BRL",
  "routingNumber": "001"
}
```

### Digital Wallet

```json theme={null}
{
  "type": "digital_wallet",
  "provider": "paypal",
  "email": "user@example.com",
  "accountId": "paypal-12345"
}
```

### Cryptocurrency Wallet

```json theme={null}
{
  "type": "crypto_wallet",
  "currency": "BTC",
  "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
  "network": "bitcoin"
}
```

## API Endpoints

Payment method entities use the standard entity endpoints:

* [Create Payment Method](/en/api-reference/payment-methods/create) - Create a new payment method entity
* [Get Payment Method](/en/api-reference/payment-methods/get) - Retrieve payment method details
* [Update Payment Method](/en/api-reference/payment-methods/update) - Update payment method information
* [List Payment Methods](/en/api-reference/payment-methods/list) - List all payment methods
* [Analyze Payment Method](/en/api-reference/entities/analyze) - Run risk analysis on payment method

## Common Patterns

### Creating a Payment Method for a Person

```javascript theme={null}
const response = await fetch('http://api.gu1.ai/entities', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    entityType: 'payment_method',
    entityData: {
      paymentMethod: {
        type: 'credit_card',
        last4: '4242',
        brand: 'visa',
        expiryMonth: '12',
        expiryYear: '2025',
        holderName: 'John Doe'
      }
    },
    relationships: [
      {
        targetEntityId: 'person-uuid-123',
        relationshipType: 'owns',
        strength: 1.0
      }
    ]
  })
});
```

### Checking Payment Method Usage

Find all transactions using a specific payment method:

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

## See Also

* [Entity Types Reference](/en/api-reference/entities/entity-types) - All available entity types
* [Entity Relationships](/en/api-reference/entities/materialize-relationships) - Managing relationships
* [Transaction Monitoring](/en/use-cases/transaction-monitoring/overview) - Fraud detection use cases