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

# Update Payment Method

> Update a payment method entity — in the gu1 entity model for card, account, and wallet records, with examples for update use cases.

## Overview

Updates an existing payment method entity. This endpoint allows partial updates - you only need to provide the fields you want to change.

## Endpoint

```
PATCH http://api.gu1.ai/entities/{id}
```

## Authentication

Requires a valid API key in the Authorization header:

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

## Path Parameters

<ParamField path="id" type="string" required>
  UUID of the payment method entity to update
</ParamField>

## Request Body

<ParamField body="entityData" type="object">
  Container for payment method data to update

  <Expandable title="properties">
    <ParamField body="paymentMethod" type="object">
      Partial payment method data to update (only include fields you want to change)
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="relationships" type="array">
  Array of relationships to add or update
</ParamField>

<ParamField body="metadata" type="object">
  Additional metadata to update
</ParamField>

## Example Requests

### Update Card Expiration Date

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PATCH "http://api.gu1.ai/entities/payment-method-uuid-123" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "entityData": {
        "paymentMethod": {
          "expiryMonth": "06",
          "expiryYear": "2026"
        }
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'http://api.gu1.ai/entities/payment-method-uuid-123',
    {
      method: 'PATCH',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        entityData: {
          paymentMethod: {
            expiryMonth: '06',
            expiryYear: '2026'
          }
        }
      })
    }
  );

  const updated = await response.json();
  console.log('Updated expiration date');
  ```

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

  response = requests.patch(
      'http://api.gu1.ai/entities/payment-method-uuid-123',
      headers={
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json'
      },
      json={
          'entityData': {
              'paymentMethod': {
                  'expiryMonth': '06',
                  'expiryYear': '2026'
              }
          }
      }
  )

  updated = response.json()
  print('Updated expiration date')
  ```
</CodeGroup>

### Add Fingerprint to Payment Method

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PATCH "http://api.gu1.ai/entities/payment-method-uuid-123" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "entityData": {
        "paymentMethod": {
          "fingerprint": "abc123xyz456"
        }
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'http://api.gu1.ai/entities/payment-method-uuid-123',
    {
      method: 'PATCH',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        entityData: {
          paymentMethod: {
            fingerprint: 'abc123xyz456'
          }
        }
      })
    }
  );
  ```

  ```python Python theme={null}
  response = requests.patch(
      'http://api.gu1.ai/entities/payment-method-uuid-123',
      headers={'Authorization': 'Bearer YOUR_API_KEY'},
      json={
          'entityData': {
              'paymentMethod': {
                  'fingerprint': 'abc123xyz456'
              }
          }
      }
  )
  ```
</CodeGroup>

### Update Holder Name

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PATCH "http://api.gu1.ai/entities/payment-method-uuid-123" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "entityData": {
        "paymentMethod": {
          "holderName": "Jane Smith"
        }
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'http://api.gu1.ai/entities/payment-method-uuid-123',
    {
      method: 'PATCH',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        entityData: {
          paymentMethod: {
            holderName: 'Jane Smith'
          }
        }
      })
    }
  );
  ```

  ```python Python theme={null}
  response = requests.patch(
      'http://api.gu1.ai/entities/payment-method-uuid-123',
      headers={'Authorization': 'Bearer YOUR_API_KEY'},
      json={
          'entityData': {
              'paymentMethod': {
                  'holderName': 'Jane Smith'
              }
          }
      }
  )
  ```
</CodeGroup>

### Add Metadata

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PATCH "http://api.gu1.ai/entities/payment-method-uuid-123" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "metadata": {
        "isDefault": true,
        "addedVia": "mobile_app",
        "verifiedAt": "2024-12-23T10:00:00Z"
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'http://api.gu1.ai/entities/payment-method-uuid-123',
    {
      method: 'PATCH',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        metadata: {
          isDefault: true,
          addedVia: 'mobile_app',
          verifiedAt: new Date().toISOString()
        }
      })
    }
  );
  ```

  ```python Python theme={null}
  from datetime import datetime

  response = requests.patch(
      'http://api.gu1.ai/entities/payment-method-uuid-123',
      headers={'Authorization': 'Bearer YOUR_API_KEY'},
      json={
          'metadata': {
              'isDefault': True,
              'addedVia': 'mobile_app',
              'verifiedAt': datetime.utcnow().isoformat() + 'Z'
          }
      }
  )
  ```
</CodeGroup>

## Response

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

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

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

<ResponseField name="entityData" type="object">
  The complete updated payment method data
</ResponseField>

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

<ResponseField name="metadata" type="object">
  Complete metadata after update
</ResponseField>

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

## Response Example

```json theme={null}
{
  "success": true,
  "id": "payment-method-uuid-123",
  "entityType": "payment_method",
  "entityData": {
    "paymentMethod": {
      "type": "credit_card",
      "last4": "4242",
      "brand": "visa",
      "expiryMonth": "06",
      "expiryYear": "2026",
      "holderName": "John Doe",
      "issuerCountry": "BR",
      "bin": "424242",
      "funding": "credit",
      "fingerprint": "abc123xyz456"
    }
  },
  "relationships": [
    {
      "targetEntityId": "person-uuid-123",
      "relationshipType": "owns",
      "strength": 1.0
    }
  ],
  "metadata": {
    "isDefault": true,
    "addedVia": "mobile_app",
    "verifiedAt": "2024-12-23T10:00:00Z"
  },
  "createdAt": "2024-01-15T10:00:00.000Z",
  "updatedAt": "2024-12-23T10:15:00.000Z"
}
```

## Use Cases

### Update Expired Card

```javascript theme={null}
async function updateExpiredCard(paymentMethodId, newExpiry) {
  const response = await fetch(
    `http://api.gu1.ai/entities/${paymentMethodId}`,
    {
      method: 'PATCH',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        entityData: {
          paymentMethod: {
            expiryMonth: newExpiry.month,
            expiryYear: newExpiry.year
          }
        },
        metadata: {
          updatedReason: 'card_renewal',
          updatedAt: new Date().toISOString()
        }
      })
    }
  );

  return await response.json();
}

// Usage
await updateExpiredCard('payment-method-uuid-123', {
  month: '12',
  year: '2027'
});
```

### Mark as Default Payment Method

```javascript theme={null}
async function setDefaultPaymentMethod(personId, paymentMethodId) {
  // First, remove default flag from all other payment methods
  const listResponse = await fetch(
    `http://api.gu1.ai/entities?entityType=payment_method&relationshipWith=${personId}`,
    {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    }
  );

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

  // Update all to not default
  await Promise.all(
    entities.map(pm =>
      fetch(`http://api.gu1.ai/entities/${pm.id}`, {
        method: 'PATCH',
        headers: {
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          metadata: { isDefault: false }
        })
      })
    )
  );

  // Set new default
  const response = await fetch(
    `http://api.gu1.ai/entities/${paymentMethodId}`,
    {
      method: 'PATCH',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        metadata: { isDefault: true }
      })
    }
  );

  return await response.json();
}
```

### Add Verification Status

```javascript theme={null}
async function markPaymentMethodVerified(paymentMethodId, verificationData) {
  const response = await fetch(
    `http://api.gu1.ai/entities/${paymentMethodId}`,
    {
      method: 'PATCH',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        metadata: {
          verified: true,
          verifiedAt: new Date().toISOString(),
          verificationMethod: verificationData.method,
          verificationId: verificationData.id
        }
      })
    }
  );

  return await response.json();
}
```

## Error Responses

### 404 Not Found

```json theme={null}
{
  "error": "Entity not found",
  "entityId": "payment-method-uuid-123"
}
```

### 400 Bad Request

```json theme={null}
{
  "error": "Invalid update data",
  "details": {
    "entityData.paymentMethod.expiryMonth": "Must be between 01 and 12"
  }
}
```

### 401 Unauthorized

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

## Important Notes

<Warning>
  * This is a partial update endpoint - only fields provided will be updated
  * Other fields will remain unchanged
  * To remove a field, explicitly set it to `null`
  * Updates to sensitive fields (like card numbers) may be restricted
</Warning>

<Info>
  * The `updatedAt` timestamp is automatically set to the current time
  * Risk scores may be recalculated after updates
  * Related transactions are not affected by payment method updates
</Info>

## See Also

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