Quickstart

Pela API

Conta nova opera em modo teste até passar pela aprovação de produção. O caminho abaixo funciona inteiro no teste — integre primeiro, ative a produção depois.

Crie uma conta e faça login

Pelo painel, ou por POST /auth/register e POST /auth/login. A resposta traz um accessToken (JWT) que serve para o próximo passo.

Gere uma chave de API de teste

Com o JWT, chame POST /api-keys com environment: "test". A chave começa com v4pay_test_ e aparece uma única vez na resposta — guarde na hora. (A chave de produção, v4pay_live_, só existe depois da aprovação.)

curl -X POST https://v4pay-api.vercel.app/api-keys \
  -H "Authorization: Bearer SEU_JWT" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Integração da loja", "environment": "test" }'

{ "data": { "id": "…", "name": "Integração da loja", "prefix": "v4pay_test_3f9a2c1", "key": "v4pay_test_3f9a2c1e…" } }

Emita uma cobrança

Agora com a chave. Os seis campos abaixo são obrigatórios no modo manual — e três regras valem sempre: amount é em reais (100 = R

100,00) e o mínimo é **R

5,00**; customer_cpf aceita CPF ou CNPJ, com os dígitos verificadores conferidos; expires_at diz até quando a cobrança pode ser paga.

curl -X POST https://v4pay-api.vercel.app/pix \
  -H "Authorization: Bearer v4pay_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100,
    "description": "Pedido 1234",
    "customer_name": "Maria Silva",
    "customer_email": "maria@exemplo.com.br",
    "customer_cpf": "12345678909",
    "expires_at": "2026-09-06T23:59:00Z"
  }'

const resposta = await fetch('https://v4pay-api.vercel.app/pix', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer v4pay_SUA_CHAVE',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amount: 100,
    description: 'Pedido 1234',
    customer_name: 'Maria Silva',
    customer_email: 'maria@exemplo.com.br',
    customer_cpf: '12345678909',
    expires_at: '2026-09-06T23:59:00Z',
  }),
});

const { data, error } = await resposta.json();
if (error) throw new Error(error.message ?? error);
console.log(data.txid, data.pix_code); // copia e cola

import requests

resposta = requests.post(
    "https://v4pay-api.vercel.app/pix",
    headers={"Authorization": "Bearer v4pay_SUA_CHAVE"},
    json={
        "amount": 100,
        "description": "Pedido 1234",
        "customer_name": "Maria Silva",
        "customer_email": "maria@exemplo.com.br",
        "customer_cpf": "12345678909",
        "expires_at": "2026-09-06T23:59:00Z",
    },
)
corpo = resposta.json()
if "error" in corpo:
    raise RuntimeError(corpo["error"])
print(corpo["data"]["txid"], corpo["data"]["pix_code"])

A resposta (201) traz a cobrança inteira: txid, pix_code (copia e cola), qr_code_url (imagem em base64) e status: "pending".

Mostre o QR code e espere o pagamento

Exiba qr_code_url como imagem e pix_code para copiar — ou mande o cliente para a página pública https://pay.v4companyamaral.com/checkout/{txid}, que faz tudo isso. Quando o cliente pagar, o status vira paid, o comprovante público fica em /comprovante/{txid} no painel e o pagador recebe o link por e-mail (quando o envio está configurado). Você fica sabendo de dois jeitos:

Webhook (recomendado): cadastre uma URL em POST /webhook-endpoints e receba o evento charge.paid. Veja Webhooks.
Consulta: GET /pix/status?txid=… a qualquer momento.

Em modo teste, “pagar” é POST /pix/simulate-payment — veja Ambiente de testes.

As regras completas da emissão (modo produto, status, o que o pagador recebe) estão em Cobranças.

Pelo painel

Entre no painel

Com e-mail e senha, ou com a conta Google. A conta nova entra em modo teste — uma faixa no topo avisa.

Experimente sem dinheiro

Crie cobranças e links normalmente: o QR code de teste não é pagável de propósito, e o botão Simular pagamento faz a cobrança virar paga — o fluxo inteiro, sem mover um centavo.

Ative a produção

Em Ativar produção, complete os dados da empresa e envie os três documentos. A equipe do V4 Pay analisa e você recebe um e-mail com o resultado — o passo a passo está em Aprovação de produção.

Vá para produção e acompanhe

Aprovado, o botão Ir para produção ativa. Dali em diante a cobrança muda para Paga sozinha quando o Pix cai, e o histórico fica em Cobranças. Para onde o dinheiro vai está explicado em Modo de recebimento.

Início

Conta e acesso

Cobranças

Receber

Integração

Pela API

Pelo painel

​Pela API

​Pelo painel

Pela API

Pelo painel