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

# Create Payment Method

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

## Overview

Creates a new payment method entity (credit card, bank account, wallet, etc.) in the system. Payment methods can be linked to person or company entities and used for transaction monitoring and fraud detection.

## Endpoint

```
POST http://api.gu1.ai/entities
```

## Authentication

Requires a valid API key in the Authorization header:

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

## Request Body

<ParamField body="entityType" type="string" required>
  Must be `"payment_method"` for payment method entities
</ParamField>

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

  <Expandable title="properties">
    <ParamField body="paymentMethod" type="object" required>
      Payment method details

      <Expandable title="properties">
        <ParamField body="type" type="string" required>
          Type of payment method: `credit_card`, `debit_card`, `bank_account`, `digital_wallet`, `crypto_wallet`, `pix`
        </ParamField>

        <ParamField body="last4" type="string">
          Last 4 digits of card/account number
        </ParamField>

        <ParamField body="brand" type="string">
          Card brand (for cards): `visa`, `mastercard`, `amex`, `elo`, `hipercard`, etc.
        </ParamField>

        <ParamField body="expiryMonth" type="string">
          Expiration month (for cards): `01` to `12`
        </ParamField>

        <ParamField body="expiryYear" type="string">
          Expiration year (for cards): `YYYY` format
        </ParamField>

        <ParamField body="holderName" type="string">
          Name on card/account
        </ParamField>

        <ParamField body="issuerCountry" type="string">
          Issuing country code (ISO 3166-1 alpha-2)
        </ParamField>

        <ParamField body="bin" type="string">
          Bank Identification Number (first 6 digits of card)
        </ParamField>

        <ParamField body="fingerprint" type="string">
          Unique fingerprint for this payment method
        </ParamField>

        <ParamField body="funding" type="string">
          Funding type: `credit`, `debit`, `prepaid`, `unknown`
        </ParamField>

        <ParamField body="accountNumber" type="string">
          Full account number (for bank accounts, encrypted)
        </ParamField>

        <ParamField body="accountType" type="string">
          Account type: `checking`, `savings`, `business`
        </ParamField>

        <ParamField body="bank" type="string">
          Bank name (for bank accounts)
        </ParamField>

        <ParamField body="currency" type="string">
          Currency code (ISO 4217): `BRL`, `USD`, `ARS`, etc.
        </ParamField>

        <ParamField body="routingNumber" type="string">
          Routing number (for bank accounts)
        </ParamField>

        <ParamField body="provider" type="string">
          Provider name (for digital wallets): `paypal`, `apple_pay`, `google_pay`, etc.
        </ParamField>

        <ParamField body="email" type="string">
          Email associated with wallet (for digital wallets)
        </ParamField>

        <ParamField body="address" type="string">
          Wallet address (for cryptocurrency wallets)
        </ParamField>

        <ParamField body="network" type="string">
          Network name (for cryptocurrency): `bitcoin`, `ethereum`, etc.
        </ParamField>

        <ParamField body="pixKey" type="string">
          PIX key (for PIX payment methods in Brazil)
        </ParamField>

        <ParamField body="pixKeyType" type="string">
          PIX key type: `cpf`, `cnpj`, `email`, `phone`, `random`
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="relationships" type="array">
  Array of relationships to other entities

  <Expandable title="properties">
    <ParamField body="targetEntityId" type="string" required>
      UUID of the related entity (person or company owner)
    </ParamField>

    <ParamField body="relationshipType" type="string" required>
      Type of relationship: `owns`, `uses`, `manages`
    </ParamField>

    <ParamField body="strength" type="number">
      Relationship strength (0.0 to 1.0)
    </ParamField>

    <ParamField body="metadata" type="object">
      Additional relationship metadata
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="metadata" type="object">
  Additional metadata for the payment method entity
</ParamField>

## Example Requests

### Create Credit Card

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST http://api.gu1.ai/entities \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "entityType": "payment_method",
      "entityData": {
        "paymentMethod": {
          "type": "credit_card",
          "last4": "4242",
          "brand": "visa",
          "expiryMonth": "12",
          "expiryYear": "2025",
          "holderName": "John Doe",
          "issuerCountry": "BR",
          "bin": "424242",
          "funding": "credit"
        }
      },
      "relationships": [
        {
          "targetEntityId": "person-uuid-123",
          "relationshipType": "owns",
          "strength": 1.0
        }
      ]
    }'
  ```

  ```javascript 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',
          issuerCountry: 'BR',
          bin: '424242',
          funding: 'credit'
        }
      },
      relationships: [
        {
          targetEntityId: 'person-uuid-123',
          relationshipType: 'owns',
          strength: 1.0
        }
      ]
    })
  });

  const paymentMethod = await response.json();
  console.log(paymentMethod.id);
  ```

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

  response = requests.post(
      'http://api.gu1.ai/entities',
      headers={
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json'
      },
      json={
          'entityType': 'payment_method',
          'entityData': {
              'paymentMethod': {
                  'type': 'credit_card',
                  'last4': '4242',
                  'brand': 'visa',
                  'expiryMonth': '12',
                  'expiryYear': '2025',
                  'holderName': 'John Doe',
                  'issuerCountry': 'BR',
                  'bin': '424242',
                  'funding': 'credit'
              }
          },
          'relationships': [
              {
                  'targetEntityId': 'person-uuid-123',
                  'relationshipType': 'owns',
                  'strength': 1.0
              }
          ]
      }
  )

  payment_method = response.json()
  print(payment_method['id'])
  ```
</CodeGroup>

### Create Bank Account

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST http://api.gu1.ai/entities \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "entityType": "payment_method",
      "entityData": {
        "paymentMethod": {
          "type": "bank_account",
          "accountNumber": "12345-6",
          "accountType": "checking",
          "bank": "Banco do Brasil",
          "currency": "BRL",
          "routingNumber": "001",
          "holderName": "John Doe"
        }
      },
      "relationships": [
        {
          "targetEntityId": "person-uuid-123",
          "relationshipType": "owns",
          "strength": 1.0
        }
      ]
    }'
  ```

  ```javascript 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: 'bank_account',
          accountNumber: '12345-6',
          accountType: 'checking',
          bank: 'Banco do Brasil',
          currency: 'BRL',
          routingNumber: '001',
          holderName: 'John Doe'
        }
      },
      relationships: [
        {
          targetEntityId: 'person-uuid-123',
          relationshipType: 'owns',
          strength: 1.0
        }
      ]
    })
  });
  ```

  ```python Python theme={null}
  response = requests.post(
      'http://api.gu1.ai/entities',
      headers={'Authorization': 'Bearer YOUR_API_KEY'},
      json={
          'entityType': 'payment_method',
          'entityData': {
              'paymentMethod': {
                  'type': 'bank_account',
                  'accountNumber': '12345-6',
                  'accountType': 'checking',
                  'bank': 'Banco do Brasil',
                  'currency': 'BRL',
                  'routingNumber': '001',
                  'holderName': 'John Doe'
              }
          },
          'relationships': [{
              'targetEntityId': 'person-uuid-123',
              'relationshipType': 'owns',
              'strength': 1.0
          }]
      }
  )
  ```
</CodeGroup>

### Create PIX Payment Method

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST http://api.gu1.ai/entities \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "entityType": "payment_method",
      "entityData": {
        "paymentMethod": {
          "type": "pix",
          "pixKey": "john.doe@example.com",
          "pixKeyType": "email",
          "holderName": "John Doe",
          "currency": "BRL"
        }
      },
      "relationships": [
        {
          "targetEntityId": "person-uuid-123",
          "relationshipType": "owns",
          "strength": 1.0
        }
      ]
    }'
  ```

  ```javascript 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: 'pix',
          pixKey: 'john.doe@example.com',
          pixKeyType: 'email',
          holderName: 'John Doe',
          currency: 'BRL'
        }
      },
      relationships: [{
        targetEntityId: 'person-uuid-123',
        relationshipType: 'owns',
        strength: 1.0
      }]
    })
  });
  ```

  ```python Python theme={null}
  response = requests.post(
      'http://api.gu1.ai/entities',
      headers={'Authorization': 'Bearer YOUR_API_KEY'},
      json={
          'entityType': 'payment_method',
          'entityData': {
              'paymentMethod': {
                  'type': 'pix',
                  'pixKey': 'john.doe@example.com',
                  'pixKeyType': 'email',
                  'holderName': 'John Doe',
                  'currency': 'BRL'
              }
          },
          'relationships': [{
              'targetEntityId': 'person-uuid-123',
              'relationshipType': 'owns',
              'strength': 1.0
          }]
      }
  )
  ```
</CodeGroup>

## Response

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

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

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

<ResponseField name="entityData" type="object">
  The payment method data as stored
</ResponseField>

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

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

<ResponseField name="updatedAt" type="string">
  ISO 8601 timestamp of last 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": "12",
      "expiryYear": "2025",
      "holderName": "John Doe",
      "issuerCountry": "BR",
      "bin": "424242",
      "funding": "credit"
    }
  },
  "relationships": [
    {
      "targetEntityId": "person-uuid-123",
      "relationshipType": "owns",
      "strength": 1.0
    }
  ],
  "createdAt": "2024-12-23T10:00:00.000Z",
  "updatedAt": "2024-12-23T10:00:00.000Z"
}
```

## Error Responses

### 400 Bad Request

```json theme={null}
{
  "error": "Invalid entity type or missing required fields",
  "details": {
    "entityType": "Must be 'payment_method'",
    "entityData.paymentMethod.type": "Required field"
  }
}
```

### 401 Unauthorized

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

## See Also

* [Get Payment Method](/en/api-reference/payment-methods/get)
* [Update Payment Method](/en/api-reference/payment-methods/update)
* [List Payment Methods](/en/api-reference/payment-methods/list)
* [Analyze Payment Method](/en/api-reference/entities/analyze)
* [Entity Types](/en/api-reference/entities/entity-types)