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

# Cartão de Crédito

> Como funciona a tokenização e cobrança de cartão de crédito

# Cartão de Crédito

> Tokenize o cartão no navegador do cliente e finalize a cobrança com aprovação em tempo real

Diferente do PIX e do boleto, o cartão de crédito acontece em **duas etapas separadas**, para que os dados sensíveis do cartão nunca passem pelo seu backend.

## Como funciona

<Steps>
  <Step title="Cliente digita o cartão">
    No seu checkout, o comprador informa número, nome, validade e CVV do cartão.
  </Step>

  <Step title="Tokenização no navegador">
    O próprio navegador do cliente chama a Velfy diretamente, usando apenas a sua **Public Key**, e recebe de volta um token de curta duração.
  </Step>

  <Step title="Seu backend cria a cobrança">
    Você envia esse token no campo `card.hash` ao criar a transação, autenticado com sua Secret + Public Key.
  </Step>

  <Step title="Resposta imediata">
    Diferente do PIX/boleto, o cartão é processado de forma síncrona: a própria resposta já informa se a cobrança foi `paid` ou `refused`.
  </Step>
</Steps>

<Warning>
  Nunca envie o número do cartão diretamente para o seu backend. A tokenização — feita com a Public Key, no navegador — existe justamente para que dados sensíveis nunca cheguem no seu servidor.
</Warning>

## Exemplo rápido

```bash theme={null}
# 1. Tokenizar (no navegador do cliente, com a Public Key)
curl -X POST 'https://api.velfy.com/api/v1/card-token?publicKey=pk_xxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "number": "4111111111111111",
    "holderName": "JOAO DA SILVA",
    "expirationMonth": "12",
    "expirationYear": "2030",
    "cvv": "123"
  }'
```

```bash theme={null}
# 2. Criar a cobrança (no seu backend, com Public + Secret Key)
curl -X POST 'https://api.velfy.com/api/v1/transactions' \
  -u "pk_xxx:sk_xxx" \
  -H 'Content-Type: application/json' \
  -d '{
    "paymentMethod": "credit_card",
    "amount": 15000,
    "installments": "3",
    "ip": "200.100.50.1",
    "card": { "hash": "<token_recebido_na_etapa_1>" },
    "customer": {
      "name": "João da Silva",
      "email": "joao@example.com",
      "document": { "type": "cpf", "number": "12345678900" }
    },
    "items": [
      { "title": "Produto X", "unitPrice": 15000, "quantity": 1, "tangible": true }
    ]
  }'
```

## Resultado da cobrança

| Status     | O que significa                                             |
| ---------- | ----------------------------------------------------------- |
| `paid`     | Aprovada — libere o produto/serviço                         |
| `refused`  | Recusada pela operadora — ofereça outro método de pagamento |
| `refunded` | Estornada — valor devolvido ao cliente                      |

## Boas práticas

* Sempre tokenize no navegador do cliente, nunca no seu backend
* Informe o `ip` do comprador — é obrigatório e ajuda na análise antifraude
* Gere o token imediatamente antes de criar a transação — ele tem validade curta

## Próximos passos

<CardGroup cols={2}>
  <Card title="Referência técnica" icon="book" href="/api-reference/payments/credit-card">
    Veja todos os campos e exemplos completos de resposta
  </Card>

  <Card title="Boleto" icon="barcode" href="/guides/boleto">
    Aceite também pagamentos via boleto
  </Card>
</CardGroup>