Documentação da API

URL base: https://api.venoxpay.sbs. Todas as respostas são JSON. Valores em centavos (R$ 49,90 = 4990).

Começar

1. Crie sua conta em app.venoxpay.sbs. 2. Envie documento (frente e verso) e a selfie segurando o documento. 3. Depois da aprovação, abra Integração no painel e gere sua chave de API.

Enquanto a verificação não for aprovada, a API responde 403 kyc_required.

Autenticação

Envie a chave no cabeçalho Authorization. A chave aparece uma única vez ao ser gerada; guarde-a em local seguro e nunca a coloque em código de navegador ou app.

Authorization: Bearer vx_live_xxxxxxxxxxxxxxxxxxxxxxxx

Criar cobrança POST

POST /v1/pix/charges

Campo	Tipo
`amount`	inteiro	Valor em centavos. Mínimo 100.
`external_id`	texto	Seu identificador do pedido. Deve ser único na sua conta.
`description`	texto	Opcional, até 140 caracteres.
`payer.name`	texto	Nome do pagador.
`payer.document`	texto	CPF ou CNPJ, só números.
`payer.email`	texto	E-mail do pagador.

@__raw_block_0__{{ $api }}/v1/pix/charges \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 4990,
    "external_id": "pedido-1042",
    "description": "Pedido 1042",
    "payer": { "name": "Maria Souza", "document": "12345678909", "email": "maria@exemplo.com" }
  }'

Resposta 201:

{
  "id": "01JC3Z8K5Q7R2W9X4N6M1PABCD",
  "external_id": "pedido-1042",
  "status": "pending",
  "amount": 4990,
  "fee": 0,
  "net": 4990,
  "pix": { "copy_paste": "00020126...", "qr_image": null },
  "paid_at": null,
  "created_at": "2026-11-14T15:04:05-03:00"
}

Mostre pix.copy_paste (Pix copia e cola) ou gere o QR Code a partir dele. Status possíveis: pending, paid, expired, failed.

Consultar cobrança GET

GET /v1/pix/charges/{id} devolve o mesmo objeto da criação, com o status atual.

Webhooks

Cadastre uma URL https:// em Integração. Enviamos um POST a cada mudança de status. Responda com qualquer status 2xx; se falhar, tentamos de novo até 6 vezes com intervalo crescente.

{
  "event": "charge.paid",
  "data": { "id": "01JC3Z8K5Q7R2W9X4N6M1PABCD", "external_id": "pedido-1042", "status": "paid", "amount": 4990, "net": 4990 }
}

Eventos: charge.paid, charge.expired, charge.failed. O mesmo evento pode chegar mais de uma vez: use id para ignorar repetidos.

Verifique a assinatura

O cabeçalho X-Venox-Signature é o HMAC SHA-256 do corpo bruto, usando o segredo exibido em Integração.

$body = file_get_contents('php://input');
$esperada = hash_hmac('sha256', $body, $seuSegredo);
if (!hash_equals($esperada, $_SERVER['HTTP_X_VENOX_SIGNATURE'] ?? '')) {
    http_response_code(401); exit;
}

Erros

HTTP	`error`
401	`unauthorized`	Chave ausente ou inválida.
403	`kyc_required`	Conta ainda não aprovada.
404	`not_found`	Cobrança não encontrada.
409	`duplicate_external_id`	Já existe cobrança com esse `external_id`.
422	`validation_error`	Campos inválidos; veja `details`.
429		Muitas requisições. Limite: 120 por minuto.
502	`provider_error`	Falha ao gerar o Pix. Tente de novo.

Saldo e saques

Cada Pix pago credita o valor líquido (net) no seu saldo. Peça saques pelo painel, em Saques; o mínimo é R$ 10,00. Nossa equipe envia o Pix para a chave informada.