> ## 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 tokenizar um cartão e criar uma cobrança de cartão de crédito

# Cartão de Crédito

> Tokenize os dados do cartão no navegador do cliente e finalize a cobrança no seu backend

O fluxo de cobrança em cartão acontece em duas etapas: **tokenização** do cartão (feita no navegador do comprador, usando apenas sua Public Key) e **criação da transação** (feita no seu backend, com o token gerado).

## 🚀 Como Funciona

<CardGroup cols={2}>
  <Card title="💳 Cliente digita o cartão" color="#631286" icon="credit-card">
    No seu checkout, o comprador informa os dados do cartão
  </Card>

  <Card title="🔒 Cartão é tokenizado" color="#631286" icon="lock">
    O navegador chama a Velfy diretamente com sua Public Key, e recebe um token
  </Card>

  <Card title="📤 Seu backend cria a cobrança" color="#631286" icon="paper-plane">
    Envie o token recebido no campo `card.hash`
  </Card>

  <Card title="⚡ Resposta imediata" color="#631286" icon="bolt">
    A cobrança é processada de forma síncrona: a resposta já traz `paid` ou `refused`
  </Card>
</CardGroup>

## 🛠️ Implementação

### 1. Tokenizar o cartão

```text theme={null}
POST /api/v1/card-token?publicKey={sua_public_key}
```

```bash theme={null}
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"
  }'
```

A resposta é uma string — o **token do cartão**:

```text theme={null}
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzZWxsZXIiOjEyMywiY2FyZCI6ey...
```

<Note>
  O token retornado tem validade curta. Gere-o imediatamente antes de criar a transação.
</Note>

### 2. Criar a transação com o token

```bash theme={null}
curl -X POST 'https://api.velfy.com/api/v1/transactions' \
  -u "sk_xxx:pk_xxx" \
  -H 'Content-Type: application/json' \
  -d '{
    "paymentMethod": "credit_card",
    "amount": 15000,
    "installments": "3",
    "externalRef": "pedido-123",
    "ip": "200.100.50.1",
    "card": {
      "hash": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
    },
    "customer": {
      "name": "João da Silva",
      "email": "joao@example.com",
      "phone": "11999999999",
      "document": { "type": "cpf", "number": "12345678900" }
    },
    "items": [
      { "title": "Produto X", "unitPrice": 15000, "quantity": 1, "tangible": true }
    ]
  }'
```

### 3. Resposta

```json theme={null}
{
  "success": true,
  "message": "Transaction created",
  "status": 201,
  "data": {
    "id": 987654,
    "status": "paid",
    "amount": 15000,
    "installments": 3,
    "paymentMethod": "credit_card",
    "secureId": "c1b2...uuid",
    "secureUrl": "https://pay.velfy.com/checkout/c1b2...uuid",
    "externalId": "pedido-123",
    "card": {
      "holderName": "JOAO DA SILVA",
      "firstDigits": "41111",
      "lastDigits": "1111",
      "expirationMonth": "12",
      "expirationYear": "2030"
    },
    "fees": 750,
    "createdAt": "2026-07-28T12:00:00.000Z"
  }
}
```

## 📊 Parâmetros Detalhados

### Campos específicos do cartão

| Campo          | Tipo     | Descrição                                  |
| -------------- | -------- | ------------------------------------------ |
| `card.hash`    | `string` | Token retornado pela tokenização do cartão |
| `installments` | `string` | Número de parcelas                         |
| `ip`           | `string` | IP do comprador (obrigatório)              |

<Info>
  Consulte os [campos comuns a toda transação](/api-reference/payments/transactions) para os demais parâmetros (`amount`, `customer`, `items`, etc).
</Info>

## 📋 Status da Transação

| Status     | Descrição         | Próximo Passo                      |
| ---------- | ----------------- | ---------------------------------- |
| `paid`     | Cobrança aprovada | Libere o produto/serviço           |
| `refused`  | Cobrança recusada | Solicite outro método de pagamento |
| `refunded` | Estornada         | Valor devolvido ao cliente         |

## 🛡️ Boas Práticas

<AccordionGroup>
  <Accordion title="🔒 Segurança" icon="shield-check">
    * Sempre tokenize o cartão no navegador do cliente, usando apenas a Public Key
    * Nunca envie o número do cartão para o seu próprio backend
    * Use HTTPS em todas as chamadas
  </Accordion>

  <Accordion title="🔄 Idempotência" icon="arrows-rotate">
    * Use `externalRef` para relacionar a cobrança com seu pedido interno
    * Trate reenvios de webhook de forma idempotente
  </Accordion>
</AccordionGroup>

***

## 🎯 Próximos Passos

<CardGroup cols={2}>
  <Card title="🔗 Configurar Webhooks" color="#631286" icon="webhook" href="/api-reference/payments/webhooks">
    Receba a confirmação do pagamento automaticamente
  </Card>

  <Card title="🧾 Boleto" color="#631286" icon="barcode" href="/api-reference/payments/boleto">
    Aceite também pagamentos via boleto
  </Card>
</CardGroup>