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

💳 Cliente digita o cartão

No seu checkout, o comprador informa os dados do cartão

🔒 Cartão é tokenizado

O navegador chama a Velfy diretamente com sua Public Key, e recebe um token

📤 Seu backend cria a cobrança

Envie o token recebido no campo card.hash

⚡ Resposta imediata

A cobrança é processada de forma síncrona: a resposta já traz paid ou refused

🛠️ Implementação

1. Tokenizar o cartão

POST /api/v1/card-token?publicKey={sua_public_key}

curl -X POST 'https://api.velfy.com.br/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"
  }'

Todos os campos são strings, inclusive mês e ano de validade. A resposta é uma string — o token do cartão:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzZWxsZXIiOjEyMywiY2FyZCI6ey...

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

2. Criar a transação com o token

curl -X POST 'https://api.velfy.com.br/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" }
    },
    "shipping": {
      "address": {
        "street": "Rua Rita Clemente da Silva",
        "streetNumber": "54",
        "neighborhood": "Diamante",
        "city": "Belo Horizonte",
        "state": "MG",
        "zipCode": "30627202",
        "complement": "Apto 45"
      }
    },
    "items": [
      { "title": "Produto X", "unitPrice": 15000, "quantity": 1, "tangible": true }
    ]
  }'

A ordem das chaves no Basic Auth é Secret Key primeiro: sk_xxx:pk_xxx. Invertida, a API responde Unauthorized.

3. Resposta

{
  "success": true,
  "message": "Transaction created",
  "status": 201,
  "data": {
    "id": 987654,
    "status": "paid",
    "refusedReason": "Transação processada com sucesso",
    "amount": 15000,
    "installments": 3,
    "paidAmount": 15000,
    "refusedAmount": 0,
    "refundedAmount": 0,
    "paymentMethod": "credit_card",
    "acquirerType": "pagarme",
    "secureId": "c1b2...uuid",
    "externalId": "pedido-123",
    "card": {
      "holderName": "JOAO DA SILVA",
      "firstDigits": "41111",
      "lastDigits": "1111",
      "expirationMonth": "12",
      "expirationYear": "2030"
    },
    "shipping": {
      "fee": 0,
      "address": {
        "street": "Rua Rita Clemente da Silva",
        "streetNumber": "54",
        "neighborhood": "Diamante",
        "city": "Belo Horizonte",
        "state": "MG",
        "zipCode": "30627202",
        "complement": "Apto 45"
      }
    },
    "fees": 750,
    "createdAt": "2026-07-28T12:00:00.000Z"
  }
}

O campo refusedReason traz o motivo em português quando a cobrança é recusada — use-o para orientar o comprador. Em transações aprovadas ele vem como mensagem de sucesso.

📮 Endereço de cobrança (`shipping`)

O objeto shipping é opcional no contrato, mas recomendado em toda cobrança de cartão. O shipping.address é o que preenche o endereço de cobrança enviado à adquirente, e ele entra na análise de antifraude. Quando o endereço confere com o cadastro do portador do cartão, a chance de aprovação aumenta.

Se você não enviar shipping, a cobrança não falha — a Velfy completa o endereço para que a adquirente aceite o pedido. Mas o antifraude passa a analisar um endereço que não é o do comprador, e a taxa de aprovação cai. Envie o endereço real sempre que tiver.

Quando você envia shipping, o objeto address passa a ser obrigatório, e todos os campos dele também — exceto complement:

Campo	Tipo	Obrigatório	Descrição
`shipping.fee`	`number`	Não	Valor do frete em centavos. Se omitido ou `null`, assume `0`
`shipping.address.street`	`string`	Sim	Logradouro
`shipping.address.streetNumber`	`string`	Sim	Número
`shipping.address.neighborhood`	`string`	Sim	Bairro
`shipping.address.city`	`string`	Sim	Cidade
`shipping.address.state`	`string`	Sim	UF, duas letras. Ex.: `"MG"`
`shipping.address.zipCode`	`string`	Sim	CEP, 8 ou 9 caracteres. Aceita `"30627202"` ou `"30627-202"`
`shipping.address.complement`	`string`	Não	Complemento

O shipping.fee não é somado ao amount. O valor cobrado do comprador é sempre o amount — se o frete deve ser cobrado, inclua-o no amount.

Com frete grátis, basta omitir o fee:

{
  "shipping": {
    "address": {
      "street": "Rua Rita Clemente da Silva",
      "streetNumber": "54",
      "neighborhood": "Diamante",
      "city": "Belo Horizonte",
      "state": "MG",
      "zipCode": "30627202",
      "complement": "Apto 45"
    }
  }
}

📊 Parâmetros Detalhados

Campos específicos do cartão

Campo	Tipo	Obrigatório	Descrição
`card.hash`	`string`	Sim	Token retornado pela tokenização do cartão
`installments`	`string`	Não	Número de parcelas, como string. Ex.: `"3"`. Padrão: `"1"`
`ip`	`string`	Sim	IP do comprador. Sem ele a transação falha. Entra na análise de antifraude

installments é uma string. Enviar o número 3 sem as aspas é recusado na validação.

card.id (cobrança em cartão salvo) ainda não é suportado. Enviar esse campo faz a transação falhar.

Consulte os campos comuns a toda transação para os demais parâmetros (amount, customer, items, etc).

📋 Status da Transação

A cobrança em cartão é síncrona: a resposta da criação já traz o resultado final.

Status	Quando aparece	Próximo Passo
`paid`	Na resposta da criação	Libere o produto/serviço
`refused`	Na resposta da criação	Veja o `refusedReason` e solicite outro método
`refunded`	Somente via webhook, após estorno	Valor devolvido ao cliente

⚠️ Erros Comuns

Mensagem	Causa
`Unauthorized`	Ordem das chaves no Basic Auth. É `sk_xxx:pk_xxx` — a Secret Key primeiro
`IP not provided`	Falta o campo `ip`, obrigatório no cartão
`Validation Error` em `installments`	Parcelas enviadas como número. Use string: `"3"`
`Validation Error` em `shipping.address`	`shipping` enviado sem o objeto `address`, ou faltando um campo obrigatório dele
`Card ID not implemented yet`	`card.id` não é suportado; use `card.hash`

🛡️ Boas Práticas

🔒 Segurança

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

📈 Taxa de aprovação

Envie shipping.address com o endereço real do comprador
Envie o ip real do comprador, não o do seu servidor
Preencha customer.phone e customer.document corretamente

🔄 Idempotência

Use externalRef para relacionar a cobrança com seu pedido interno
Trate reenvios de webhook de forma idempotente

🎯 Próximos Passos

🔗 Configurar Webhooks

Receba a confirmação do pagamento automaticamente

🧾 Boleto

Aceite também pagamentos via boleto

Pagamentos

Cartão de crédito

Cartão de Crédito

🚀 Como Funciona

💳 Cliente digita o cartão

🔒 Cartão é tokenizado

📤 Seu backend cria a cobrança

⚡ Resposta imediata

🛠️ Implementação

1. Tokenizar o cartão

2. Criar a transação com o token

3. Resposta

📮 Endereço de cobrança (`shipping`)

📊 Parâmetros Detalhados

Campos específicos do cartão

📋 Status da Transação

⚠️ Erros Comuns

🛡️ Boas Práticas

🎯 Próximos Passos

🔗 Configurar Webhooks

🧾 Boleto

​Cartão de Crédito

​🚀 Como Funciona

💳 Cliente digita o cartão

🔒 Cartão é tokenizado

📤 Seu backend cria a cobrança

⚡ Resposta imediata

​🛠️ Implementação

​1. Tokenizar o cartão

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

​3. Resposta

​📮 Endereço de cobrança (shipping)

​📊 Parâmetros Detalhados

​Campos específicos do cartão

​📋 Status da Transação

​⚠️ Erros Comuns

​🛡️ Boas Práticas

​🎯 Próximos Passos

🔗 Configurar Webhooks

🧾 Boleto

Cartão de Crédito

🚀 Como Funciona

🛠️ Implementação

1. Tokenizar o cartão

2. Criar a transação com o token

3. Resposta

📮 Endereço de cobrança (`shipping`)

📊 Parâmetros Detalhados

Campos específicos do cartão

📋 Status da Transação

⚠️ Erros Comuns

🛡️ Boas Práticas

🎯 Próximos Passos