Produção · API v1BRL · centavos inteiros

Integre PIX em produção com um contrato previsível e seguro.

Referência completa para autenticação, cobranças, transferências, saldo, idempotência, webhooks, erros e práticas de produção da VELTIS.

Gerar credenciais OpenAPI JSON Abrir console

Base URL

https://api.veltispay.com/v1

Auth

Key + Secret

Criações

Idempotentes

Eventos

HMAC-SHA256

Ambiente

Live

Quickstart

Do zero à primeira cobrança

Um fluxo de integração seguro começa pelas credenciais, passa pela cotação e termina confirmando o pagamento por webhook.

Gere credenciais

Crie Key + Secret e aplique somente os escopos necessários.

Consulte a tarifa

Faça a cotação em centavos antes de criar a operação.

Crie com idempotência

Envie uma chave única por operação financeira.

Confirme por webhook

Valide HMAC e deduplique pelo Event ID.

POST /charges

curl --request POST 'https://api.veltispay.com/v1/charges' \
  --header 'X-Veltis-Key: sk_live_xxxxxxxxx' \
  --header 'X-Veltis-Secret: sk_secret_live_xxxxxxxxx' \
  --header 'Idempotency-Key: order_8821' \
  --header 'Content-Type: application/json' \
  --data '{
    "amount": 15000,
    "description": "Pedido #8821",
    "external_reference": "order-8821",
    "customer": {
      "name": "Cliente Exemplo",
      "document": "12345678901",
      "email": "[email protected]"
    }
  }'

Segurança

Autenticação server-to-server

Novas integrações usam duas credenciais independentes. Nunca coloque Key ou Secret em JavaScript público, aplicativo distribuído ou repositório.

Cabeçalhos obrigatórios

X-Veltis-Key: sk_live_xxxxxxxxx
X-Veltis-Secret: sk_secret_live_xxxxxxxxx
Content-Type: application/json

Princípio do menor privilégio

Configure escopos, expiração e, quando possível, uma allowlist de IPs IPv4/CIDR para cada integração.

EscopoPermissão

charges:readConsultar cobranças e cotação PIX

charges:writeCriar e reconciliar cobranças

payouts:readConsultar transferências e cotação de saída

payouts:writeSolicitar transferências PIX

balance:readConsultar saldo disponível e reservado

ledger:readConsultar extrato financeiro

Credenciais legadas de uma única chave podem existir apenas para compatibilidade. Integrações novas devem usar X-Veltis-Key + X-Veltis-Secret.

Confiabilidade

Idempotência financeira

POST /charges e POST /payouts exigem Idempotency-Key. Isso permite repetir uma tentativa após timeout sem criar uma segunda movimentação.

Cabeçalho

Idempotency-Key: order_8821

# Também aceito
X-Idempotency-Key: order_8821

Use uma chave por intenção financeira

Exemplo: o ID interno do pedido, saque ou operação no seu sistema.

Repita a mesma chave após timeout

Se o payload for igual, a VELTIS reutiliza a operação já registrada.

Não mude o payload da mesma chave

Reutilizar uma chave com conteúdo diferente retorna 409 IDEMPOTENCY_CONFLICT.

Limite

A chave pode ter no máximo 191 caracteres.

Referência

Catálogo de endpoints

Pesquise por recurso, método, caminho ou escopo.

GET/fees/pix-quote?amount=10000

charges:read

Cotação de cobrança

Calcula tarifa e valor líquido antes de criar a cobrança.

GET/charges

charges:read

Listar cobranças

Retorna até 100 cobranças recentes da conta.

POST/charges

charges:writeIdempotency-Key

Criar cobrança PIX

Cria cobrança, QR Code, copia e cola e checkout hospedado.

GET/charges/:id

charges:read

Consultar cobrança

Consulta uma cobrança e pode reconciliar estado pendente.

POST/charges/:id/sync

charges:write

Sincronizar cobrança

Solicita reconciliação imediata com o serviço de liquidação.

GET/fees/payout-quote?amount=20000

payouts:read

Cotação de transferência

Retorna tarifa e débito total antes da transferência.

GET/payouts

payouts:read

Listar transferências

Retorna até 100 transferências recentes.

POST/payouts

payouts:writeIdempotency-Key

Criar transferência PIX

Solicita transferência com reserva financeira e rastreamento assíncrono.

GET/payouts/:id

payouts:read

Consultar transferência

Consulta estado, tarifa, débito total e motivo de falha.

GET/balance

balance:read

Consultar saldo

Retorna saldo disponível e saldo reservado em BRL.

GET/ledger?limit=100

ledger:read

Consultar extrato

Retorna lançamentos recentes; limit aceita de 1 a 200.

Recebimentos

Cobranças PIX

Valores são sempre enviados como inteiros em centavos. O mínimo aceito pela API é 100 centavos.

1. Cotar

GET https://api.veltispay.com/v1/fees/pix-quote?amount=15000
X-Veltis-Key: sk_live_xxxxxxxxx
X-Veltis-Secret: sk_secret_live_xxxxxxxxx

Resposta de cotação

{
  "success": true,
  "data": {
    "amount": 15000,
    "fee": 450,
    "net_amount": 14550,
    "currency": "BRL"
  }
}

2. Criar cobrança

POST https://api.veltispay.com/v1/charges
X-Veltis-Key: sk_live_xxxxxxxxx
X-Veltis-Secret: sk_secret_live_xxxxxxxxx
Idempotency-Key: order_8821
Content-Type: application/json

{
  "amount": 15000,
  "description": "Pedido #8821",
  "external_reference": "order-8821",
  "return_url": "https://suaempresa.com/pedidos/8821",
  "customer": {
    "name": "Cliente Exemplo",
    "document": "12345678901",
    "email": "[email protected]",
    "phone": "+5511999999999"
  },
  "metadata": {
    "pedido": "8821"
  }
}

Resposta

{
  "success": true,
  "data": {
    "id": "ch_...",
    "object": "charge",
    "amount": 15000,
    "fee": 450,
    "net_amount": 14550,
    "currency": "BRL",
    "status": "pending",
    "external_reference": "order-8821",
    "pix": {
      "copy_paste": "000201...",
      "qr_code_payload": "000201...",
      "qr_code_image": "...",
      "expires_at": "2026-09-26T00:30:00Z"
    },
    "checkout_url": "https://veltispay.com/c/ch_...",
    "paid_at": null,
    "created_at": "2026-09-26T00:15:00Z"
  }
}

return_url precisa ser HTTPS

Quando informado, return_url deve ser uma URL HTTPS válida. metadata aceita um objeto JSON de até aproximadamente 16 KB.

Saídas

Transferências PIX

Transferências via API são autorizadas pelas credenciais, escopos e controles da conta. O PIN transacional é exclusivo das operações humanas no painel.

Cotação

GET https://api.veltispay.com/v1/fees/payout-quote?amount=20000
X-Veltis-Key: sk_live_xxxxxxxxx
X-Veltis-Secret: sk_secret_live_xxxxxxxxx

{
  "success": true,
  "data": {
    "amount": 20000,
    "recipient_amount": 20000,
    "fee": 600,
    "total_debit": 20600,
    "currency": "BRL"
  }
}

Criar transferência

POST https://api.veltispay.com/v1/payouts
X-Veltis-Key: sk_live_xxxxxxxxx
X-Veltis-Secret: sk_secret_live_xxxxxxxxx
Idempotency-Key: withdraw_991
Content-Type: application/json

{
  "amount": 20000,
  "recipient_name": "Cliente Exemplo",
  "recipient_document": "12345678901",
  "pix_key_type": "cpf",
  "pix_key": "12345678901",
  "description": "Saque #991",
  "external_reference": "withdraw-991"
}

cpf

cnpj

email

phone

evp

Saldo é reservado antes do envio

A transferência precisa ter saldo disponível suficiente para valor + tarifa. Falta de saldo retorna 409 INSUFFICIENT_BALANCE.

Conciliação

Saldo e extrato

Use o saldo para disponibilidade operacional e o ledger para conciliar cada crédito e débito.

Saldo

GET https://api.veltispay.com/v1/balance
X-Veltis-Key: sk_live_xxxxxxxxx
X-Veltis-Secret: sk_secret_live_xxxxxxxxx

{
  "success": true,
  "data": {
    "available": 24842000,
    "reserved": 20600,
    "currency": "BRL"
  }
}

Extrato

GET https://api.veltispay.com/v1/ledger?limit=100
X-Veltis-Key: sk_live_xxxxxxxxx
X-Veltis-Secret: sk_secret_live_xxxxxxxxx

{
  "success": true,
  "data": [
    {
      "id": "led_...",
      "type": "charge_credit",
      "direction": "credit",
      "amount": 14550,
      "charge_id": "ch_...",
      "payout_id": null,
      "description": "Liquidação PIX",
      "created_at": "2026-09-26T00:20:00Z"
    }
  ]
}

Eventos

Webhooks assinados com HMAC-SHA256

Cada endpoint configurado recebe uma Signing Secret própria. O segredo é exibido na criação ou rotação e deve ficar somente no backend.

Cabeçalhos recebidos

X-Veltis-Event-Id: <event_id>
X-Veltis-Event-Type: charge.paid
X-Veltis-Timestamp: 1787160000
X-Veltis-Signature: sha256=<hex>
Content-Type: application/json

Verificação em Node.js

import crypto from "node:crypto";

const material = timestamp + "." + rawBody;
const expected = crypto
  .createHmac("sha256", process.env.VELTIS_WEBHOOK_SECRET)
  .update(material)
  .digest("hex");

const received = signature.replace(/^sha256=/, "");

if (received.length !== expected.length ||
    !crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected))) {
  throw new Error("Assinatura inválida");
}

Material assinado

timestamp + "." + RAW_BODY

Valide o corpo bruto exatamente como recebido. Persista o Event ID antes de executar efeitos e responda HTTP 2xx somente depois dessa persistência. Entregas com falha são reenviadas com backoff.

charge.createdcharge.pendingcharge.paidcharge.expiredcharge.failedcharge.cancelledcharge.refundedpayout.requestedpayout.approvedpayout.processingpayout.paidpayout.failedpayout.rejected

Contrato

Erros, HTTP e estados

Erros seguem um envelope estável. Use error.code para lógica e error.message para diagnóstico humano.

Formato

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Saldo disponível insuficiente"
  }
}

400Requisição inválida

JSON, idempotência ou cabeçalho obrigatório.

401Não autenticado

Key/Secret inválidos, expirados ou revogados.

403Sem permissão

Escopo, IP, conta ou capacidade operacional.

404Não encontrado

Recurso ou rota inexistente.

409Conflito

Idempotência, saldo ou estado da operação.

422Validação

Valor, PIX key ou campos inválidos.

429Limite de requisições

Reduza a taxa e faça retry com backoff.

5xxFalha temporária

Não gere nova intenção; repita com a mesma idempotência.

Estados de cobrança

creatingpendingpaidexpiredfailedcancelledrefunded

Estados de transferência

submittingrequestedapprovedprocessingpaidfailedrejected

Go live

Checklist antes de entrar em produção

Use esta lista como critério mínimo antes de liberar tráfego financeiro real.

Segredos fora do código

Armazene Key, Secret e Signing Secret em cofre de segredos ou variáveis protegidas.

Escopos mínimos

Conceda somente as permissões usadas por cada serviço.

Allowlist de IP

Restrinja as credenciais aos IPs do backend quando sua infraestrutura permitir.

Idempotência persistente

Salve a chave junto ao pedido/saque e reutilize a mesma após timeout.

Webhook em RAW_BODY

Calcule o HMAC antes de fazer parse ou reserializar o JSON.

Deduplicação

Persista Event ID e torne o processamento de eventos idempotente.

Timeouts e retries

Use timeout de rede e retry com backoff sem trocar a chave idempotente.

Conciliação

Use webhooks como caminho principal e consultas/sync como mecanismo de recuperação.

Gerenciar credenciais Configurar webhooks Abrir OpenAPI