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

# Crear Método de Pago

> Crear una nueva entidad de método de pago — en el modelo de entidades gu1 para tarjetas, cuentas y billeteras, con ejemplos para create.

## Descripción General

Crea una nueva entidad de método de pago (tarjeta de crédito, cuenta bancaria, billetera, etc.) en el sistema. Los métodos de pago pueden vincularse a entidades de personas o empresas y utilizarse para monitoreo de transacciones y detección de fraude.

## Endpoint

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

## Autenticación

Requiere una clave API válida en el encabezado de Autorización:

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

## Cuerpo de la Solicitud

<ParamField body="entityType" type="string" required>
  Debe ser `"payment_method"` para entidades de método de pago
</ParamField>

<ParamField body="entityData" type="object" required>
  Contenedor para datos del método de pago

  <Expandable title="propiedades">
    <ParamField body="paymentMethod" type="object" required>
      Detalles del método de pago

      <Expandable title="propiedades">
        <ParamField body="type" type="string" required>
          Tipo de método de pago: `credit_card`, `debit_card`, `bank_account`, `digital_wallet`, `crypto_wallet`, `pix`
        </ParamField>

        <ParamField body="last4" type="string">
          Últimos 4 dígitos del número de tarjeta/cuenta
        </ParamField>

        <ParamField body="brand" type="string">
          Marca de la tarjeta (para tarjetas): `visa`, `mastercard`, `amex`, `elo`, `hipercard`, etc.
        </ParamField>

        <ParamField body="expiryMonth" type="string">
          Mes de vencimiento (para tarjetas): `01` a `12`
        </ParamField>

        <ParamField body="expiryYear" type="string">
          Año de vencimiento (para tarjetas): formato `YYYY`
        </ParamField>

        <ParamField body="holderName" type="string">
          Nombre en la tarjeta/cuenta
        </ParamField>

        <ParamField body="issuerCountry" type="string">
          Código de país emisor (ISO 3166-1 alpha-2)
        </ParamField>

        <ParamField body="bin" type="string">
          Número de Identificación Bancaria (primeros 6 dígitos de la tarjeta)
        </ParamField>

        <ParamField body="fingerprint" type="string">
          Huella digital única para este método de pago
        </ParamField>

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

        <ParamField body="accountNumber" type="string">
          Número de cuenta completo (para cuentas bancarias, encriptado)
        </ParamField>

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

        <ParamField body="bank" type="string">
          Nombre del banco (para cuentas bancarias)
        </ParamField>

        <ParamField body="currency" type="string">
          Código de moneda (ISO 4217): `BRL`, `USD`, `ARS`, etc.
        </ParamField>

        <ParamField body="routingNumber" type="string">
          Número de ruta (para cuentas bancarias)
        </ParamField>

        <ParamField body="provider" type="string">
          Nombre del proveedor (para billeteras digitales): `paypal`, `apple_pay`, `google_pay`, etc.
        </ParamField>

        <ParamField body="email" type="string">
          Email asociado con la billetera (para billeteras digitales)
        </ParamField>

        <ParamField body="address" type="string">
          Dirección de la billetera (para billeteras de criptomonedas)
        </ParamField>

        <ParamField body="network" type="string">
          Nombre de la red (para criptomonedas): `bitcoin`, `ethereum`, etc.
        </ParamField>

        <ParamField body="pixKey" type="string">
          Clave PIX (para métodos de pago PIX en Brasil)
        </ParamField>

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

<ParamField body="relationships" type="array">
  Array de relaciones con otras entidades

  <Expandable title="propiedades">
    <ParamField body="targetEntityId" type="string" required>
      UUID de la entidad relacionada (propietario persona o empresa)
    </ParamField>

    <ParamField body="relationshipType" type="string" required>
      Tipo de relación: `owns`, `uses`, `manages`
    </ParamField>

    <ParamField body="strength" type="number">
      Fuerza de la relación (0.0 a 1.0)
    </ParamField>

    <ParamField body="metadata" type="object">
      Metadatos adicionales de la relación
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="metadata" type="object">
  Metadatos adicionales para la entidad de método de pago
</ParamField>

## Ejemplos de Solicitudes

### Crear Tarjeta de Crédito

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

### Crear Cuenta Bancaria

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

### Crear Método de Pago PIX

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

## Respuesta

<ResponseField name="success" type="boolean">
  Si la operación fue exitosa
</ResponseField>

<ResponseField name="id" type="string">
  UUID de la entidad de método de pago creada
</ResponseField>

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

<ResponseField name="entityData" type="object">
  Los datos del método de pago tal como se almacenaron
</ResponseField>

<ResponseField name="relationships" type="array">
  Array de relaciones creadas
</ResponseField>

<ResponseField name="createdAt" type="string">
  Marca de tiempo ISO 8601 de la creación
</ResponseField>

<ResponseField name="updatedAt" type="string">
  Marca de tiempo ISO 8601 de la última actualización
</ResponseField>

## Ejemplo de Respuesta

```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"
}
```

## Respuestas de Error

### 400 Solicitud Incorrecta

```json theme={null}
{
  "error": "Tipo de entidad inválido o campos requeridos faltantes",
  "details": {
    "entityType": "Debe ser 'payment_method'",
    "entityData.paymentMethod.type": "Campo requerido"
  }
}
```

### 401 No Autorizado

```json theme={null}
{
  "error": "Clave API inválida o faltante"
}
```

## Ver También

* [Obtener Método de Pago](/es/api-reference/payment-methods/get)
* [Actualizar Método de Pago](/es/api-reference/payment-methods/update)
* [Listar Métodos de Pago](/es/api-reference/payment-methods/list)
* [Analizar Método de Pago](/en/api-reference/entities/analyze)
* [Tipos de Entidades](/en/api-reference/entities/entity-types)