> ## Documentation Index
> Fetch the complete documentation index at: https://docs.killb.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Contas

> Entendendo contas bancárias, carteiras cripto e contas pré-financiadas

## O que é uma Conta?

Uma **Conta** na KillB representa um destino ou origem de fundos em uma transação ramp. As contas podem ser contas bancárias, carteiras cripto ou contas custodiais.

<Info>
  Os usuários podem ter múltiplas contas de diferentes tipos. Cada conta está vinculada a um usuário específico.
</Info>

## Tipos de Conta

<Tabs>
  <Tab title="Contas Bancárias">
    Contas bancárias fiat tradicionais para receber moeda local

    **Tipos:**

    * **PSE** - Contas bancárias colombianas
    * **SPEI** - Contas bancárias mexicanas (CLABE)
    * **ACH** - Contas bancárias dos EUA
    * **WIRE** - Transferências wire internacionais
    * **TRANSFIYA** - Carteiras móveis colombianas

    **Casos de Uso:**

    * Destinos de off-ramp (cripto → fiat)
    * Recebimento de moeda local
    * Saques bancários
  </Tab>

  <Tab title="Carteiras Cripto">
    Endereços de carteira blockchain para receber criptomoeda

    **Suportado:**

    * USDC em múltiplas redes
    * USDT em múltiplas redes
    * Polygon, Solana, Ethereum, Arbitrum, Tron, BSC

    **Casos de Uso:**

    * Destinos de on-ramp (fiat → cripto)
    * Recebimento de stablecoins
    * Saques cripto
  </Tab>

  <Tab title="Contas Custodiais">
    Contas gerenciadas pela KillB para programas de poupança

    **Recursos:**

    * Denominadas em USD
    * Seguradas pela FDIC (através de bancos parceiros)
    * Não é necessário gerenciamento de carteira
    * Depósitos ACH/Wire

    **Casos de Uso:**

    * Contas poupança
    * Obtenção de rendimento
    * Custódia simplificada
  </Tab>
</Tabs>

## Status da Conta

| Status     | Descrição                      | Pode Transacionar? |
| ---------- | ------------------------------ | ------------------ |
| `ACTIVE`   | Conta verificada e pronta      | ✅ Sim              |
| `PENDING`  | Aguardando verificação         | ❌ Não              |
| `REJECTED` | Verificação falhou             | ❌ Não              |
| `INACTIVE` | Desabilitada por usuário/admin | ❌ Não              |

## Criando Contas

### Conta PSE (Colômbia)

Conta bancária colombiana para receber COP:

```json theme={null}
{
  "type": "PSE",
  "userId": "user-id-aqui",
  "externalId": "account-123",
  "data": {
    "firstName": "Juan",
    "lastName": "García",
    "email": "juan@example.com",
    "phone": "+573001234567",
    "accountNumber": "1234567890",
    "bankCode": "0001",
    "type": "savings",
    "countryCode": "CO",
    "document": {
      "type": "NUIP",
      "number": "1234567890",
      "issuedCountryCode": "CO"
    }
  }
}
```

### Conta SPEI (México)

Conta bancária mexicana usando CLABE:

```json theme={null}
{
  "type": "SPEI",
  "userId": "user-id-aqui",
  "externalId": "account-456",
  "data": {
    "firstName": "María",
    "lastName": "López",
    "email": "maria@example.com",
    "phone": "+525512345678",
    "clabe": "012345678901234567",
    "clabeType": "CLABE",
    "countryCode": "MX",
    "document": {
      "type": "RFC",
      "number": "LOMM900515ABC",
      "issuedCountryCode": "MX"
    }
  }
}
```

<Tip>
  SPEI suporta três tipos de CLABE: `CLABE` padrão de 18 dígitos, `DEBIT_CARD` de 16 dígitos ou `PHONE_NUMBER` de 10 dígitos
</Tip>

### Conta de Carteira

Carteira cripto para receber USDC/USDT:

```json theme={null}
{
  "type": "WALLET",
  "userId": "user-id-aqui",
  "externalId": "wallet-789",
  "data": {
    "firstName": "João",
    "lastName": "Silva",
    "email": "joao@example.com",
    "phone": "+5511987654321",
    "currency": "USDC",
    "network": "POLYGON",
    "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "countryCode": "BR",
    "document": {
      "type": "PASSPORT",
      "number": "AB123456",
      "issuedCountryCode": "BR"
    }
  }
}
```

### Conta ACH (EUA)

Conta bancária dos EUA para USD:

```json theme={null}
{
  "type": "ACH",
  "userId": "user-id-aqui",
  "externalId": "ach-001",
  "data": {
    "firstName": "Jane",
    "lastName": "Smith",
    "email": "jane@example.com",
    "phone": "+12125551234",
    "bankName": "Chase Bank",
    "routingNumber": "021000021",
    "accountNumber": "123456789",
    "type": "checking",
    "countryCode": "US",
    "document": {
      "type": "SSN",
      "number": "123-45-6789",
      "issuedCountryCode": "US"
    }
  }
}
```

## Validação de Conta

A KillB valida contas antes de permitir transações:

### Validação de Conta Bancária

* Código do banco existe nos bancos suportados
* Formato do número da conta está correto
* Número de roteamento é válido (para ACH/Wire)
* CLABE é formato válido de 18 dígitos (para SPEI)
* Nome do titular da conta corresponde ao usuário

### Validação de Carteira

* Endereço é válido para a rede especificada
* Checksum do endereço está correto (para chains EVM)
* Rede é suportada para a moeda
* Endereço não é um contrato inteligente (a menos que permitido)

## Consultando Contas

### Obter Todas as Contas do Usuário

```bash theme={null}
GET /api/v2/accounts/userId/{userId}
```

### Pesquisar Contas

```bash theme={null}
GET /api/v2/accounts?type=WALLET&userId=user-id
```

**Opções de Filtro:**

* `ids` - IDs de conta específicos
* `userId` - Filtrar por usuário
* `type` - Tipo de conta
* `accountNumber` - Número da conta bancária
* `address` - Endereço da carteira

## Atualizando Contas

Atualizar informações da conta (campos limitados):

```bash theme={null}
PATCH /api/v2/accounts/{accountId}
```

**Campos Atualizáveis:**

* Informações de documento
* Número CLABE (SPEI)
* Endereço da carteira
* Número da conta
* Código do banco

<Warning>
  Algumas atualizações podem exigir re-verificação e definir temporariamente o status da conta como PENDING.
</Warning>

## Excluindo Contas

```bash theme={null}
DELETE /api/v2/accounts/{accountId}
```

<Note>
  Contas usadas em ramps pendentes ou em processamento não podem ser excluídas até que essas transações sejam concluídas.
</Note>

## Melhores Práticas

<AccordionGroup>
  <Accordion title="Verificar Antes de Criar" icon="check-double">
    * Valide códigos bancários usando o endpoint `/api/v2/banks`
    * Verifique o formato do endereço da carteira no lado do cliente
    * Confirme que o usuário possui a conta
    * Teste com uma transação pequena primeiro
  </Accordion>

  <Accordion title="Usar IDs Externos" icon="hashtag">
    * Forneça um `externalId` único para cada conta
    * Use seu identificador de conta interno
    * Permite pesquisa fácil de conta
    * Previne contas duplicadas
  </Accordion>

  <Accordion title="Lidar com Múltiplas Contas" icon="layer-group">
    * Permita que os usuários salvem múltiplas contas
    * Deixe os usuários definirem contas padrão/preferidas
    * Suporte troca de conta
    * Mostre o status de verificação da conta
  </Accordion>

  <Accordion title="Segurança" icon="lock">
    * Nunca armazene detalhes bancários sensíveis
    * Use IDs de conta da KillB em seu banco de dados
    * Implemente verificações de propriedade de conta
    * Valide o acesso à conta em cada uso
  </Accordion>
</AccordionGroup>

## Próximos Passos

<CardGroup cols={2}>
  <Card title="Guia de Gerenciamento de Contas" icon="folder-open" href="/pt/guides/accounts/overview">
    Guia completo para gerenciar contas
  </Card>

  <Card title="Configuração de Contas Bancárias" icon="building-columns" href="/pt/guides/accounts/bank-accounts">
    Configure contas bancárias para diferentes países
  </Card>

  <Card title="Carteiras Cripto" icon="wallet" href="/pt/guides/accounts/crypto-wallets">
    Configure contas de carteira de criptomoeda
  </Card>

  <Card title="Contas Pré-Financiadas" icon="bolt" href="/pt/concepts/pre-funded-accounts">
    Aprenda sobre execução instantânea com liquidez pré-depositada
  </Card>

  <Card title="Referência da API" icon="code" href="/api-reference/endpoint/accounts-create">
    Veja a documentação da API de Contas
  </Card>
</CardGroup>