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

# Criar Método de Pagamento

> Criar uma nova entidade de método de pagamento — no modelo de entidades gu1 para cartões, contas e carteiras, com exemplos para create.

## Visão Geral

Cria uma nova entidade de método de pagamento (cartão de crédito, conta bancária, carteira, etc.) no sistema. Os métodos de pagamento podem ser vinculados a entidades de pessoas ou empresas e usados para monitoramento de transações e detecção de fraude.

## Endpoint

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

## Autenticação

Requer uma chave API válida no cabeçalho de Autorização:

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

## Corpo da Requisição

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

<ParamField body="entityData" type="object" required>
  Container para dados do método de pagamento

  <Expandable title="propriedades">
    <ParamField body="paymentMethod" type="object" required>
      Detalhes do método de pagamento

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

        <ParamField body="last4" type="string">
          Últimos 4 dígitos do número de cartão/conta
        </ParamField>

        <ParamField body="brand" type="string">
          Marca do cartão (para cartões): `visa`, `mastercard`, `amex`, `elo`, `hipercard`, etc.
        </ParamField>

        <ParamField body="expiryMonth" type="string">
          Mês de vencimento (para cartões): `01` a `12`
        </ParamField>

        <ParamField body="expiryYear" type="string">
          Ano de vencimento (para cartões): formato `YYYY`
        </ParamField>

        <ParamField body="holderName" type="string">
          Nome no cartão/conta
        </ParamField>

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

        <ParamField body="bin" type="string">
          Número de Identificação Bancária (primeiros 6 dígitos do cartão)
        </ParamField>

        <ParamField body="pixKey" type="string">
          Chave PIX (para métodos de pagamento PIX no Brasil)
        </ParamField>

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

<ParamField body="relationships" type="array">
  Array de relacionamentos com outras entidades
</ParamField>

## Exemplos de Requisições

### Criar Cartão 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>

### Criar Método de Pagamento 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>

## Resposta

<ResponseField name="success" type="boolean">
  Se a operação foi bem-sucedida
</ResponseField>

<ResponseField name="id" type="string">
  UUID da entidade de método de pagamento criada
</ResponseField>

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

<ResponseField name="entityData" type="object">
  Os dados do método de pagamento conforme armazenados
</ResponseField>

<ResponseField name="createdAt" type="string">
  Timestamp ISO 8601 da criação
</ResponseField>

## Exemplo de Resposta

```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"
    }
  },
  "createdAt": "2024-12-23T10:00:00.000Z"
}
```

## Veja Também

* [Obter Método de Pagamento](/pt/api-reference/payment-methods/get)
* [Atualizar Método de Pagamento](/pt/api-reference/payment-methods/update)
* [Listar Métodos de Pagamento](/pt/api-reference/payment-methods/list)