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

Cliente digita o cartão

No seu checkout, o comprador informa número, nome, validade e CVV do cartão.

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.

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.

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.

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.

Exemplo rápido

# 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"
  }'

# 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

Visão Geral

Autenticação

Métodos de Pagamento

Webhooks

Cartão de Crédito

Cartão de Crédito

Como funciona

Exemplo rápido

Resultado da cobrança

Boas práticas

Próximos passos

Referência técnica

Boleto

​Cartão de Crédito

​Como funciona

​Exemplo rápido

​Resultado da cobrança

​Boas práticas

​Próximos passos

Referência técnica

Boleto

Cartão de Crédito

Como funciona

Exemplo rápido

Resultado da cobrança

Boas práticas

Próximos passos