A Velfy Payments é uma API só: cobranças por Pix, Boleto e Cartão, checkout hospedado e webhooks em tempo real. HTTP, JSON e Basic Auth — sem SDK obrigatório, sem contrato em XML.
1# Cobrança Pix com QR Code e copia e cola
2curl -X POST 'https://api.velfy.com/api/v1/transactions' \
3 -u "sk_xxx:pk_xxx" \
4 -H 'Content-Type: application/json' \
5 -d '{
6 "paymentMethod": "pix",
7 "amount": 14990,
8 "externalRef": "pedido-8123",
9 "postbackUrl": "https://sualoja.com/velfy",
10 "pix": { "expiresInDays": 2 },
11 "customer": {
12 "name": "João da Silva",
13 "email": "joao@example.com",
14 "document": { "type": "cpf", "number": "12345678900" }
15 }
16 }'
17
18# → data.pix.qrcode e data.secureUrl na resposta1# Boleto registrado, vencimento em 3 dias
2curl -X POST 'https://api.velfy.com/api/v1/transactions' \
3 -u "sk_xxx:pk_xxx" \
4 -H 'Content-Type: application/json' \
5 -d '{
6 "paymentMethod": "boleto",
7 "amount": 32000,
8 "externalRef": "pedido-8124",
9 "boleto": { "expiresInDays": 3 },
10 "customer": {
11 "name": "Maria Souza",
12 "email": "maria@example.com",
13 "document": { "type": "cpf", "number": "98765432100" }
14 }
15 }'
16
17# → boleto.url (PDF), barcode e digitableLine1// 1. o navegador tokeniza o cartão com a public key
2const hash = await tokenizeCard(publicKey, dadosDoCartao);
3
4// 2. o seu backend cria a cobrança com o token
5const res = await fetch(url, {
6 method: "POST",
7 headers: { Authorization: `Basic ${creds}` },
8 body: JSON.stringify({
9 paymentMethod: "credit_card",
10 amount: 49900,
11 installments: "3",
12 ip: req.ip,
13 card: { hash }
14 })
15}); // → status: "paid" ou "refused"Funciona com o seu stack
Pix, Boleto e Cartão saem todos de POST /api/v1/transactions. Você troca o paymentMethod, não a sua arquitetura.
A resposta já traz o QR Code e o payload copia e cola. Quando o Pix compensa, o webhook chega com o end2end.
pix.qrcodepix.expiresInDayspending → paid → refundedBoleto bancário registrado, pagável em qualquer banco, lotérica ou app. PDF, código de barras e linha digitável vêm na mesma resposta.
boleto.urlbarcode e digitableLine na respostaO cartão é tokenizado no navegador do comprador com a sua public key. O número nunca passa pelo seu servidor — você só manda o token.
/card-tokeninstallmentspaid ou refusedSem SDK obrigatório e sem dependência para instalar: se o seu stack faz um POST com Basic Auth, ele fala com a Velfy.
1# criar a cobrança
2curl -X POST 'https://api.velfy.com/api/v1/transactions' \
3 -u "$VELFY_SECRET_KEY:$VELFY_PUBLIC_KEY" \
4 -H 'Content-Type: application/json' \
5 -d @cobranca.json
6
7# consultar depois, para conciliar
8curl 'https://api.velfy.com/api/v1/transactions/918234' \
9 -u "$VELFY_SECRET_KEY:$VELFY_PUBLIC_KEY"
10
11# saldo disponível, em centavos
12curl 'https://api.velfy.com/api/v1/balance' \
13 -u "$VELFY_SECRET_KEY:$VELFY_PUBLIC_KEY"1const credentials = Buffer.from(
2 `${process.env.VELFY_SECRET_KEY}:${process.env.VELFY_PUBLIC_KEY}`
3).toString("base64");
4
5const res = await fetch(
6 "https://api.velfy.com/api/v1/transactions",
7 {
8 method: "POST",
9 headers: {
10 Authorization: `Basic ${credentials}`,
11 "Content-Type": "application/json",
12 },
13 body: JSON.stringify(payload),
14 }
15);
16
17const { data } = await res.json();1import base64
2import os
3import requests
4
5credentials = base64.b64encode(
6 f"{os.environ['VELFY_SECRET_KEY']}:{os.environ['VELFY_PUBLIC_KEY']}".encode()
7).decode()
8
9response = requests.post(
10 "https://api.velfy.com/api/v1/transactions",
11 headers={"Authorization": f"Basic {credentials}"},
12 json=payload,
13)
14
15data = response.json()["data"]1<?php
2$ch = curl_init("https://api.velfy.com/api/v1/transactions");
3
4curl_setopt_array($ch, [
5 CURLOPT_POST => true,
6 CURLOPT_USERPWD => $secretKey . ":" . $publicKey,
7 CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
8 CURLOPT_POSTFIELDS => json_encode($payload),
9 CURLOPT_RETURNTRANSFER => true,
10]);
11
12$body = json_decode(curl_exec($ch), true);
13$transaction = $body["data"];Toda resposta vem no mesmo envelope, todo método usa os mesmos campos comuns, e a referência completa — com OpenAPI — está publicada.
{ success, message, status, data } em toda resposta.pk_ vai para o navegador, sk_ fica no seu backend.Informe uma postbackUrl ao criar a cobrança e a Velfy dispara um POST a cada mudança de status — sem polling, sem esperar o cliente atualizar a página.
pending a chargedback e in_protest.data.id — reenvios não viram cobrança duplicada.GET /api/v1/transactions/{id}.Da primeira cobrança ao fechamento do mês, sem sair da API nem do painel.
Amarre cada cobrança ao seu pedido com externalRef e leia a taxa aplicada em fee.netAmount — o número do financeiro vem na própria transação.
GET /api/v1/balance devolve disponível, a compensar, retido, antecipado e total sacado — tudo em centavos.
Toda transação volta com um secureUrl pronto — e o painel gera link de cobrança avulso, sem escrever código.
O navegador troca os dados do cartão por um token usando só a public key. O número do cartão nunca chega ao seu servidor.
Um POST na sua postbackUrl a cada mudança de status, com o payload completo da transação.
Chargeback, MED e pré-chargeback acompanhados no painel, com um índice único para você ver se a operação está saudável.
Ao ativar a conta você recebe uma public key pk_ e uma secret key sk_. As duas juntas autenticam via Basic Auth.
Um POST em /api/v1/transactions com o paymentMethod, o valor em centavos e os dados do cliente.
Responda 200 na sua postbackUrl, processe de forma assíncrona e libere o pedido quando o status virar paid.
Vendas, ticket médio, aprovação por método, saúde da conta e saque — tudo em uma visão só. E os mesmos números saem pela API, se você preferir puxar para o seu BI.
Painel Velfy · números ilustrativos
available do GET /api/v1/balance, com botão.A Velfy é gateway parceiro das plataformas que a sua operação já roda. Onde existe parceria, conectar é colar as chaves — não escrever integração.
Selecione a Velfy como processadora dentro do painel da Zedy e comece a receber por Pix, boleto e cartão sem mexer na loja.
Cada venda processada volta para a campanha que a gerou, com o status real da transação — ROI calculado sobre o que foi pago, não sobre o clique.
Módulo oficial para a plataforma de faturamento de provedores de hospedagem. Cada fatura gerada passa a aceitar Pix, boleto e cartão, com baixa automática.
Checkout transparente com failover entre gateways. A Velfy participa do Flip de Pagamentos, que redireciona a venda quando a primeira tentativa é recusada.
E qualquer stack que faça HTTP — a API é REST com JSON e Basic Auth, sem SDK obrigatório.
O modelo de chaves da Velfy separa o que pode aparecer no navegador do que nunca sai do seu backend — e mantém o número do cartão fora do seu servidor.
A tokenização acontece no navegador do comprador, com a public key. Você recebe um token de vida curta e envia só ele em card.hash.
A pk_ pode ser exposta no client-side. A sk_ autentica o backend e nunca deve sair dele.
Toda rota /api/v1/* exige Basic Auth sobre HTTPS. Chamada sem header válido não passa — recebe 401.
Status, taxas, end2end do Pix e dados do pagador ficam consultáveis por ID — inclusive em disputa e chargeback.
Os detalhes técnicos completos — campos, tipos e exemplos de resposta — estão na documentação oficial.
É a API de pagamentos da Velfy. Ela processa cobranças por Pix, cartão de crédito e boleto, devolve o resultado por webhook e dá acesso a saldo, extrato e ao acompanhamento de cada transação — tudo pelo mesmo contrato.
Você recebe duas chaves ao ativar a conta: uma public key pk_ e uma secret key sk_. As rotas /api/v1/* usam HTTP Basic Auth combinando as duas em Base64. A public key também é a credencial usada na tokenização de cartão no navegador; a secret key nunca deve sair do seu backend.
Não. A integração é HTTP + JSON: qualquer cliente HTTP resolve — fetch no Node, requests no Python, cURL no PHP. A documentação traz exemplos prontos em cURL, Node e Python, e há uma spec OpenAPI publicada caso você queira gerar um cliente.
Informe uma postbackUrl ao criar a transação. A Velfy envia um POST para essa URL a cada mudança de status, com o payload completo em data. A recomendação é responder 200 rápido e processar a lógica de negócio de forma assíncrona, usando data.id para não processar o mesmo evento duas vezes.
pending, processing, paid, approved, refused, refunded, chargedback e in_protest. Pix e boleto confirmam como paid; cartão aprovado vem como approved. O mesmo valor aparece na resposta de criação, na consulta por ID e no webhook.
Não, e não deve. O navegador do comprador chama POST /api/v1/card-token diretamente com a sua public key e recebe um token. Seu backend usa só esse token, no campo card.hash, para criar a transação. O token tem validade curta — gere-o imediatamente antes da cobrança.
Pelo painel, em "Disponível para Saque". O valor liberado é o campo available de GET /api/v1/balance, que já desconta saques em andamento. A transferência sai apenas para conta de titularidade da própria empresa — a Velfy não envia valores para contas de terceiros.
Sempre em centavos, como número inteiro. "amount": 14990 equivale a R$ 149,90. Isso vale para o valor da cobrança, para os itens, para as taxas e para todos os campos de saldo.
Crie a conta, pegue suas chaves pk_ e sk_ e rode o primeiro curl. A referência completa da API já está publicada.
