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

# Cadastrar Conta Bancária

> Cadastra uma nova conta bancária ou chave PIX para recebimento de saques

## Visão Geral

Este endpoint permite cadastrar uma conta bancária ou chave PIX para receber transferências dos valores disponíveis em sua conta KlivoPay.

## Endpoint

```
POST https://api.klivopay.com.br/api/public/v1/bank-accounts
```

## Parâmetros

<ParamField body="api_token" type="string" required>
  Seu token de autenticação da API KlivoPay
</ParamField>

<ParamField body="type" type="string" required>
  Tipo de conta: `pix` ou `bank`
</ParamField>

### Parâmetros para PIX (type = "pix")

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

<ParamField body="pix_key" type="string">
  Valor da chave PIX
</ParamField>

### Parâmetros para Conta Bancária (type = "bank")

<ParamField body="bank_code" type="string">
  Código do banco (3 dígitos). Exemplo: `001` para Banco do Brasil
</ParamField>

<ParamField body="account_type" type="string">
  Tipo de conta: `checking` (corrente) ou `savings` (poupança)
</ParamField>

<ParamField body="account_number" type="string">
  Número da conta com dígito
</ParamField>

<ParamField body="agency" type="string">
  Número da agência
</ParamField>

<ParamField body="holder_name" type="string">
  Nome completo do titular da conta
</ParamField>

<ParamField body="holder_document" type="string">
  CPF ou CNPJ do titular (apenas números)
</ParamField>

## Exemplo de Requisição

<CodeGroup>
  ```bash cURL - PIX theme={null}
  curl -X POST 'https://api.klivopay.com.br/api/public/v1/bank-accounts' \
    -H 'Content-Type: application/json' \
    -d '{
      "api_token": "seu_token_aqui",
      "type": "pix",
      "pix_key_type": "cpf",
      "pix_key": "12345678900"
    }'
  ```

  ```bash cURL - Conta Bancária theme={null}
  curl -X POST 'https://api.klivopay.com.br/api/public/v1/bank-accounts' \
    -H 'Content-Type: application/json' \
    -d '{
      "api_token": "seu_token_aqui",
      "type": "bank",
      "bank_code": "001",
      "account_type": "checking",
      "account_number": "12345-6",
      "agency": "1234",
      "holder_name": "João Silva",
      "holder_document": "12345678900"
    }'
  ```

  ```javascript JavaScript - PIX theme={null}
  const response = await fetch('https://api.klivopay.com.br/api/public/v1/bank-accounts', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      api_token: 'seu_token_aqui',
      type: 'pix',
      pix_key_type: 'email',
      pix_key: 'joao@example.com'
    })
  });

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

  ```python Python - Conta Bancária theme={null}
  import requests

  url = 'https://api.klivopay.com.br/api/public/v1/bank-accounts'
  payload = {
      'api_token': 'seu_token_aqui',
      'type': 'bank',
      'bank_code': '001',
      'account_type': 'checking',
      'account_number': '12345-6',
      'agency': '1234',
      'holder_name': 'João Silva',
      'holder_document': '12345678900'
  }

  response = requests.post(url, json=payload)
  print(response.json())
  ```

  ```php PHP theme={null}
  <?php
  $url = 'https://api.klivopay.com.br/api/public/v1/bank-accounts';
  $data = [
      'api_token' => 'seu_token_aqui',
      'type' => 'pix',
      'pix_key_type' => 'phone',
      'pix_key' => '11987654321'
  ];

  $options = [
      'http' => [
          'header'  => "Content-Type: application/json\r\n",
          'method'  => 'POST',
          'content' => json_encode($data)
      ]
  ];

  $context = stream_context_create($options);
  $result = file_get_contents($url, false, $context);
  print_r(json_decode($result));
  ?>
  ```
</CodeGroup>

## Resposta de Sucesso

```json 201 Created theme={null}
{
  "success": true,
  "data": {
    "hash": "bank123abc",
    "type": "pix",
    "pix_key_type": "cpf",
    "pix_key": "123.456.789-00",
    "status": "active",
    "created_at": "2025-01-20T10:15:00Z"
  }
}
```

## Códigos de Resposta

<ResponseField name="201" type="Created">
  Conta bancária cadastrada com sucesso
</ResponseField>

<ResponseField name="400" type="Bad Request">
  Dados inválidos na requisição
</ResponseField>

<ResponseField name="401" type="Unauthorized">
  Token de API inválido ou ausente
</ResponseField>

<ResponseField name="422" type="Unprocessable Entity">
  Erro de validação nos dados enviados
</ResponseField>

<ResponseField name="500" type="Internal Server Error">
  Erro interno do servidor
</ResponseField>

<Info>
  Você pode cadastrar múltiplas contas bancárias e escolher qual usar para cada saque.
</Info>

<Note>
  Contas PIX geralmente processam saques mais rapidamente (até 1 hora) comparado a transferências bancárias tradicionais (1-3 dias úteis).
</Note>