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

# Cartão de Crédito

> Receba pagamentos via cartão de crédito de forma fácil e segura.

O **Cartão de Crédito** permite que você receba pagamentos online de forma imediata através de transações com cartões de crédito das principais bandeiras. Ideal para e-commerce, assinaturas, serviços digitais e vendas onde a confirmação instantânea é necessária.

A aprovação ocorre em tempo real, permitindo liberar o produto ou serviço imediatamente após a autorização.

## 🚀 Como Funciona

O Card funciona através da criação de uma transação utilizando os dados do cartão do cliente. Esses dados são enviados de forma segura e tokenizados antes de serem processados na rede adquirente.

<CardGroup cols={2}>
  <Card title="📱 Você cria uma cobrança na API" color="#ff7e00" icon="qrcode">
    Você gera uma cobrança com valor específico através da API
  </Card>

  <Card title="💳 Os dados do cartão são enviados com segurança" color="#ff7e00" icon="credit-card">
    Tokenizamos o cartão para que os dados sejam enviados de forma segura. 
  </Card>

  <Card title="⚡A transação é autorizada pela operadora do cartão" color="#ff7e00" icon="bolt">
    Você recebe confirmação assim que o pagamento for validado
  </Card>

  <Card title="💰 Retornamos o resultado imediatamente" color="#ff7e00" icon="money-bill">
    Valor fica disponível imediatamente em sua conta para antecipação.
  </Card>
</CardGroup>

## 🛠️ Implementação Rápida

### 1. Criar Token do cartão

```bash theme={null}
curl -X POST 'https://api.avanttifinance.com/v1/card-token' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <seu_token>' \
  -d '{
  "number": "4111111111111111",
  "holderName": "JOAO SILVA",
  "expirationMonth": "12",
  "expirationYear": "28",
  "cvv": "123"
}'
```

### 2. Resposta com token gerado

```json theme={null}
{
  "success": true,
  "token": "ct_AbCdEfGhIjKlMnOpQrStUvWxYz1234567890"
}
```

## 📊 Parâmetros Detalhados

### Campos Obrigatórios

| Campo             | Tipo     | Descrição                                     |
| ----------------- | -------- | --------------------------------------------- |
| `number`          | `string` | Número do cartão (13–19 dígitos, Luhn válido) |
| `holderName`      | `string` | Nome do titular (mín. 2 caracteres)           |
| `expirationMonth` | `string` | Mês (01–12)                                   |
| `expirationYear`  | `string` | Ano (2 dígitos ex: "28" ou 4 ex: "2028")      |
| `cvv`             | `string` | Código de segurança (3 ou 4 dígitos)          |

### 3. Criar transação

## ⚠️ 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/card' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <seu_token>' \
  -d '{
  "postbackUrl": "https://seu-sistema.com/webhooks/avantti",
  "amountInCents": 9990,
  "description": "Compra Produto X",
  "card": {
    "cardToken": "ct_AbCdEfGhIjKlMnOpQrStUvWxYz1234567890",
    "installments": 1,
    "holderName": "JOAO SILVA"
  },
  "customer": {
    "name": "João da Silva",
    "email": "joao@email.com",
    "documentType": "cpf",
    "document": "12345678909",
    "phone": "11999999999",
    "billingAddress": {
      "street": "Rua das Flores",
      "number": "100",
      "neighborhood": "Centro",
      "city": "São Paulo",
      "state": "SP",
      "zipCode": "01310100"
    }
  },
  "items": [
    {
      "title": "Produto X",
      "tangible": false,
      "quantity": 1,
      "amountInCents": 9990
    }
  ]
}'
```

### 4. Resposta Transação Aprovada

```json theme={null}
{
  "success": true,
  "message": "Transação criada com sucesso",
  "data": {
    "id": "clxyz123abc456",
    "card": {
      "token": "tok_xxxx",
      "brand": "Visa",
      "last4": "1111"
    },
    "status": "paid",
    "fees": 350
  }
}
```

### 4. Resposta Transação Recusada

```json theme={null}
{
  "success": false,
  "message": "Erro ao criar transação"
}
```

## 📊 Parâmetros Detalhados

### Campos Obrigatórios

| Campo                     | Tipo       | Descrição                                                                    |
| :------------------------ | :--------- | :--------------------------------------------------------------------------- |
| `amountInCents`           | `number`   | Valor total em centavos (9990 = R\$ 99,90)                                   |
| `card.cardToken`          | `string`   | Token retornado por `/v1/card-token` ou token da [Pagar.me](http://Pagar.me) |
| `expirationYear`          | `string`   | Ano (2 dígitos ex: "28" ou 4 ex: "2028")                                     |
| `items`                   | `array`    | Itens da venda                                                               |
| `customer`                | `object`   | Dados do comprador (documentType: cpf/cnpj, document válido)                 |
| `customer.billingAddress` | `object`   | Endereço de cobrança (recomendado para [Pagar.me](http://Pagar.me))          |
| `customer.email`          | `string`   | Email do cliente                                                             |
| `customer.documentType`   | `string`   | Tipo do documento (`cpf` ou `cnpj`)                                          |
| `customer.document`       | `string`   | Números do documento do cliente                                              |
| `customer.phone`          | `string`   | Telefone do cliente                                                          |
| `customer.name`           | `customer` | Nome completo do cliente                                                     |

### 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                   |
| `card.installments` | `number` | Parcelas (default: 1)                        |
| `card.holderNamer`  | `string` | Nome do titular                              |

## 📡 Recebendo Confirmações

### Via Webhook

Criado:

```json theme={null}
{
  "id": "uuid-do-webhook",
  "type": "transaction",
  "event": "transaction_created",
  "scope": "postback",
  "transaction": {
    "id": "clxyz123abc456",
    "amount": 9990,
    "status": "paid",
    "pix": null
  }
}
```

Recusado:

```json theme={null}
{
  "id": "uuid-do-webhook",
  "type": "transaction",
  "event": "card_declined",
  "scope": "postback",
  "transaction": {
    "id": "clxyz123abc456",
    "amount": 9990,
    "status": "refused",
    "pix": null
  }
}
```

Chargeback:

```json theme={null}
{
  "id": "uuid-do-webhook",
  "type": "transaction",
  "event": "transaction_refunded",
  "scope": "postback",
  "transaction": {
    "id": "clxyz123abc456",
    "amount": 9990,
    "status": "refund",
    "pix": null
  }
}
```

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

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