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

# Pix In

> Receba pagamentos PIX de forma instantânea através de QR Codes

O PIX IN permite que você receba pagamentos de forma instantânea através da geração de QR Codes PIX. Ideal para cobranças, vendas online e qualquer situação onde você precisa receber um pagamento.

## 🚀 Como Funciona

O PIX IN funciona através da criação de QR Codes dinâmicos que seus clientes podem escanear para realizar o pagamento:

<CardGroup cols={2}>
  <Card title="📱 QR Code Gerado" color="#ff7e00" icon="qrcode">
    Você cria um QR Code com valor específico através da API
  </Card>

  <Card title="💳 Cliente Paga" color="#ff7e00" icon="credit-card">
    Cliente escaneia o QR Code e confirma o pagamento no app do banco
  </Card>

  <Card title="⚡ Confirmação Instantânea" color="#ff7e00" icon="bolt">
    Você recebe confirmação em tempo real via webhook
  </Card>

  <Card title="💰 Valor Disponível" color="#ff7e00" icon="money-bill">
    Valor fica disponível imediatamente em sua conta
  </Card>
</CardGroup>

## 🛠️ Implementação Rápida

### 1. Criar QR Code PIX

## ⚠️ Validação do valor total da transação

O campo `amountInCents` enviado fora do array `items` representa o **valor total da cobrança**.

Para que a requisição seja aceita, esse valor **deve ser exatamente igual** à soma do valor de cada item multiplicado por sua respectiva quantidade.

Em outras palavras:

> O total da transação precisa corresponder ao somatório de `amountInCents × quantity` de todos os itens informados.

```bash theme={null}
curl -X POST 'https://api.avanttifinance.com/v1/pix/in/qrcode' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <seu_token>' \
  -d '{
    "amountInCents": 8000,
    "postbackUrl": "https://nimble-swan-74.webhook.cool",
    "description": "Teste",
    "customer": {
      "name": "TESTE VENDA",
      "email": "JVTESTE@teste.com",
      "documentType": "cnpj",
      "document": "2222222222222",
      "phone": "(32) 99999-9999"
    },
    "items": [
      {
        "title": "Produto teste",
        "tangible": true,
        "quantity": 1,
        "amountInCents": 2000,
        "shippingAddress": {
          "street": "Rua Teste",
          "number": "293",
          "neighborhood": "Bairro",
          "city": "São Paulo",
          "state": "SP",
          "zipCode": "123982193892183"
        }
      },
      {
        "title": "Produto teste 2",
        "tangible": true,
        "quantity": 2,
        "amountInCents": 3000,
        "shippingAddress": {
          "street": "Rua Teste",
          "number": "293",
          "neighborhood": "Bairro",
          "city": "São Paulo",
          "state": "SP",
          "zipCode": "123982193892183"
        }
      }
    ],
    "seller": {
      "name": "Bruno Ribeiro do Vale",
      "documentType": "cnpj",
      "document": "07628652000114",
      "phone": "(32) 88888-9999"
    }
  }'
```

### 2. Resposta com QR Code

```json theme={null}
{
  "success": true,
  "message": "Transação criada com sucesso",
  "data": {
    "id": "clm8x9y0z1234567890abcdef",
    "pix": {
      "emv": "00020101021226830014br.gov.bcb.pix25225012.paymentcompany.com.br/qr/v2/cobv/9d36b84f58f7e04f12345678901234567890",
      "qrCode": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAABDgAAAJYCAYAAACvNd..."
    },
    "status": "pending",
    "fees": 100
  }
}
```

### 3. Exibir QR Code para Cliente

```html theme={null}
{/*  Mostrar QR Code  */}
<img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAABDgAAAJYCAYAAACvNd..." alt="QR Code PIX">

{/*  Ou usar o código EMV  */}
<div class="pix-code">
  <p>Copie e cole no seu banco:</p>
  <input type="text" value="00020101021226830014br.gov.bcb.pix..." readonly>
</div>
```

## 📊 Parâmetros Detalhados

### Campos Obrigatórios

| Campo                     | Tipo     | Descrição                                  |
| ------------------------- | -------- | ------------------------------------------ |
| `amountInCents`           | `number` | Valor em centavos (ex: 10000 = R\$ 100,00) |
| `customer`                | `object` | Dados do cliente pagador                   |
| `customer.name`           | `string` | Nome completo do cliente                   |
| `customer.email`          | `string` | Email do cliente                           |
| `customer.documentType`   | `string` | Tipo do documento (`cpf` ou `cnpj`)        |
| `customer.phone`          | `string` | Telefone do cliente                        |
| `customer.billingAddress` | `object` | Endereço de cobrança                       |
| `customer.document`       | `string` | Número do documento (apenas números)       |
| `items`                   | `array`  | Lista de itens da compra                   |

### Campos Opcionais

| Campo         | Tipo     | Descrição                                    |
| ------------- | -------- | -------------------------------------------- |
| `description` | `string` | Descrição da transação (máx. 140 caracteres) |
| `postbackUrl` | `string` | URL específica para webhooks desta transação |
| `seller`      | `object` | informações sobre vendedor                   |

### Exemplo Completo

```json theme={null}
{
    "amountInCents": 5000,
    "postbackUrl": "https://nimble-swan-74.webhook.cool",
    "description": "Teste",
    "customer": {
      "name": "TESTE VENDA",
      "email": "JVTESTE@teste.com",
      "documentType": "cnpj",
      "document": "2222222222222",
      "phone": "(32) 99999-9999"
    },
    "items": [
      {
        "title": "Produto teste",
        "tangible": true,
        "quantity": 1,
        "amountInCents": 100,
        "shippingAddress": {
          "street": "Rua Teste",
          "number": "293",
          "neighborhood": "Bairro",
          "city": "São Paulo",
          "state": "SP",
          "zipCode": "123982193892183"
        }
      },
      {
        "title": "Produto teste 2",
        "tangible": true,
        "quantity": 1,
        "amountInCents": 300,
        "shippingAddress": {
          "street": "Rua Teste",
          "number": "293",
          "neighborhood": "Bairro",
          "city": "São Paulo",
          "state": "SP",
          "zipCode": "123982193892183"
        }
      }
    ],
    "seller": {
      "name": "Bruno Ribeiro do Vale",
      "documentType": "cnpj",
      "document": "07628652000114",
      "phone": "(32) 88888-9999"
    }
  }
```

## 📡 Recebendo Confirmações

### Via Webhook

Configure um webhook para receber confirmações automáticas:

```json theme={null}
{
  "id": "wh_64f8a2b1c3d4e5f6g7h8i9j0",
  "type": "transaction",
  "event": "transaction_paid",
  "scope": "user",
  "transaction": {
    "id": "clm8x9y0z1234567890abcdef",
    "amount": 29990,
    "status": "paid",
    "pix": {
      "endToEndId": "E12345678202412011030567890AB123C",
      "payerInfo": {
        "name": "Maria Silva Santos",
        "document": "12345678901"
      }
    }
  }
}
```

## 📋 Status das Transações

| Status     | Descrição            | Próximo Passo                    |
| ---------- | -------------------- | -------------------------------- |
| `pending`  | Aguardando pagamento | Mostrar QR Code para cliente     |
| `paid`     | Pago com sucesso     | Liberar produto/serviço          |
| `canceled` | Cancelado            | Gerar novo QR Code se necessário |
| `refunded` | Estornado            | Valor devolvido ao pagador       |

## 🛡️ Boas Práticas

### Segurança

<AccordionGroup>
  <Accordion title="🔒 Validação de Dados" icon="shield-check">
    * Sempre valide CPF/CNPJ antes de enviar
    * Sanitize dados de entrada
    * Verifique valores mínimos e máximos
    * Use HTTPS obrigatoriamente
  </Accordion>

  <Accordion title="🔄 Idempotência" icon="arrows-rotate">
    * Use IDs únicos para cada transação
    * Implemente verificação de duplicatas
    * Mantenha referências internas
    * Trate reenvios de webhook adequadamente
  </Accordion>

  <Accordion title="📊 Monitoramento" icon="chart-line">
    * Monitore taxa de conversão
    * Acompanhe tempos de pagamento
    * Verifique abandono de carrinho
    * Alerte sobre falhas de webhook
  </Accordion>
</AccordionGroup>

### Performance

* **Cache**: Armazene QR Codes por período limitado
* **Timeout**: Configure timeouts adequados para requisições
* **Retry**: Implemente retry para chamadas falhadas
* **Batch**: Agrupe operações quando possível

***

## 🎯 Próximos Passos

<CardGroup cols={2}>
  <Card title="📝 Criar QR Code" color="#ff7e00" icon="plus" href="/pages/pix-in/create-qrcode">
    Guia detalhado para criar QR Codes PIX
  </Card>

  <Card title="🔗 Configurar Webhooks" color="#ff7e00" icon="webhook" href="/webhook">
    Configure notificações automáticas
  </Card>

  <Card title="🚀 PIX OUT" color="#ff7e00" icon="paper-plane" href="/pages/pix-out/overview">
    Aprenda a enviar transferências PIX
  </Card>

  <Card title="📊 Relatórios" color="#ff7e00" icon="chart-bar" href="/pages/reference/status-codes">
    Monitore suas transações
  </Card>
</CardGroup>