Criando Transações

Um único endpoint para cobrar via PIX, cartão de crédito ou boleto

Toda cobrança na Velfy Payments é criada através do mesmo endpoint. O método de pagamento é definido pelo campo paymentMethod no corpo da requisição.

🚀 Como Funciona

📤 Você cria a cobrança

Envie os dados da venda e o método de pagamento desejado (pix, credit_card ou boleto)

💳 Cliente paga

O cliente paga via PIX, cartão ou boleto, conforme o método escolhido

⚡ Confirmação instantânea

Você recebe a confirmação em tempo real via webhook

🔍 Consulte quando quiser

Use o endpoint de consulta para verificar o status a qualquer momento

🛠️ Endpoint

POST /api/v1/transactions

Autenticado via Basic Auth com sua secret key e public key.

📊 Campos Comuns

Independente do método de pagamento, toda requisição compartilha estes campos:

Campos Obrigatórios

Campo	Tipo	Descrição
`paymentMethod`	`string`	`pix`, `credit_card` ou `boleto`
`amount`	`number`	Valor total da cobrança, em centavos
`customer`	`object`	Dados do pagador
`customer.name`	`string`	Nome completo
`customer.email`	`string`	E-mail
`customer.document.type`	`string`	`cpf` ou `cnpj`
`customer.document.number`	`string`	Número do documento (somente dígitos)
`items`	`array`	Itens da venda (mínimo 1)
`items[].title`	`string`	Nome do item
`items[].unitPrice`	`number`	Preço unitário, em centavos
`items[].quantity`	`number`	Quantidade
`items[].tangible`	`boolean`	`true` para produto físico, `false` para digital/serviço

Campos Opcionais

Campo	Tipo	Descrição
`customer.phone`	`string`	Telefone do cliente
`shipping`	`object`	Endereço e valor de frete
`externalRef`	`string`	Identificador da cobrança no seu sistema
`postbackUrl`	`string`	URL para onde a Velfy enviará os webhooks desta transação
`metadata`	`string`	Campo livre para informações adicionais
`ip`	`string`	IP do comprador — obrigatório para cartão de crédito

💳 Métodos de Pagamento

Cada método adiciona campos específicos dentro de um objeto próprio (pix, card ou boleto):

PIX

QR Code e copia e cola

Cartão de crédito

Tokenização e cobrança

Boleto

Boleto bancário

📥 Resposta

Toda chamada bem-sucedida retorna o mesmo envelope:

{
  "success": true,
  "message": "Transaction created",
  "status": 201,
  "data": { }
}

O conteúdo de data varia conforme o método de pagamento — veja exemplos completos em cada página específica.

📋 Status Possíveis

Status	Descrição
`pending`	Cobrança criada, aguardando pagamento
`processing`	Pagamento em processamento
`paid` / `approved`	Pagamento confirmado
`refused`	Pagamento recusado
`refunded`	Pagamento estornado
`chargedback`	Chargeback recebido
`in_protest`	Chargeback em contestação

Para ver o corpo completo de resposta e como consultar uma transação já criada, veja Consultar transação.

Pagamentos

Criando transações

Criando Transações

🚀 Como Funciona

📤 Você cria a cobrança

💳 Cliente paga

⚡ Confirmação instantânea

🔍 Consulte quando quiser

🛠️ Endpoint

📊 Campos Comuns

Campos Obrigatórios

Campos Opcionais

💳 Métodos de Pagamento

PIX

Cartão de crédito

Boleto

📥 Resposta

📋 Status Possíveis

🎯 Próximos Passos

🔍 Consultar Transação

🔗 Webhooks

​Criando Transações

​🚀 Como Funciona

📤 Você cria a cobrança

💳 Cliente paga

⚡ Confirmação instantânea

🔍 Consulte quando quiser

​🛠️ Endpoint

​📊 Campos Comuns

​Campos Obrigatórios

​Campos Opcionais

​💳 Métodos de Pagamento

PIX

Cartão de crédito

Boleto

​📥 Resposta

​📋 Status Possíveis

​🎯 Próximos Passos

🔍 Consultar Transação

🔗 Webhooks

Criando Transações

🚀 Como Funciona

🛠️ Endpoint

📊 Campos Comuns

Campos Obrigatórios

Campos Opcionais

💳 Métodos de Pagamento

📥 Resposta

📋 Status Possíveis

🎯 Próximos Passos