Documentação da API VenturePay

Começando

Visão geral da integração

A API VenturePay é organizada em torno de REST. Todas as requisições usam JSON, retornam códigos HTTP convencionais e são autenticadas por assinatura enviada no header. Você pode operar em sandbox antes de ir para produção.

Links de pagamento

Cartão, PIX, parcelamento e desconto em uma única chamada.

Webhooks em tempo real

Notificações assinadas em HMAC SHA256 a cada evento.

Sandbox completo

Cartões de teste e transações simuladas sem custo.

Segurança por assinatura

Nenhuma requisição é aceita sem assinatura válida.

Casos de uso comuns

E-commerce e checkout

Assinaturas recorrentes

Marketplaces

Aplicativos mobile

URL base

Todas as requisições devem apontar para a URL base abaixo. O caminho de cada endpoint é relativo a ela.

Produção ao vivo

https://api.venturepay.com.br/v1/

Use tokens com prefixo vp_prod_. Transações movimentam dinheiro real.

Sandbox testes

https://venturepay.com.br/api-sandbox/v1/

Use tokens com prefixo vp_test_. Nenhum valor real é movimentado.

Rate limits

A API aplica limites de requisições por token para garantir a estabilidade do serviço.

Tipo de token	Limite	Janela	Header de resposta
Sandbox	100 requisições	1 hora	`X-RateLimit-Remaining`
Produção	1.000 requisições	1 hora	`X-RateLimit-Reset`

Ao exceder o limite, a API responde 429 Too Many Requests. Implemente retentativa com backoff exponencial.

Autenticação

Chaves e assinatura

A autenticação usa um par de chaves: a pública identifica sua conta no corpo da requisição e a secreta assina cada chamada.

Public key

Identifica sua conta. Deve ser enviada no corpo da requisição, no campo public_key.

vp_prod_ce2d9ce1f7c213eaade842738a4e4

Secret key

Usada para gerar a assinatura. Mantenha apenas no backend e nunca exponha no frontend.

1de97abb11146a6c5aa3f84f811da866c211720cadb58ccca41398c6ddf4bcd8

Assinatura (venture-signature)

Toda requisição precisa do header venture-signature contendo o secret token correspondente à public key enviada.

assinatura.php

// Monte o corpo exatamente como será enviado
$request_body = json_encode([
    'public_key' => 'vp_prod_ce2d9ce1f7c213eaade842738a4e4',
    'custom_name' => 'Curso Premium',
    'amount' => 30
]);

$secret_key = '1de97abb11146a6c5aa3f84f811da866c211720cadb58ccca41398c6ddf4bcd8';

// Header enviado na requisição
// venture-signature: {$secret_key}

Boas práticas de segurança

Calcule a assinatura com o corpo exato da requisição (JSON serializado).
Use sempre a secret key correspondente à public key enviada.
Nunca exponha a secret key no frontend nem em repositórios públicos.
Requisições sem assinatura válida são rejeitadas com 401.

Ambientes

Característica	Sandbox	Produção
Prefixo do token	`vp_test_`	`vp_prod_`
Movimentação financeira	Simulada	Real
PIX	Simulado	Instantâneo
Rate limit	100 / hora	1.000 / hora

Referência

Endpoints

Todos os caminhos abaixo são relativos à URL base. As requisições usam application/json e exigem o header de assinatura.

Criar link de pagamento

POST /orders/charge/payment-link/

Cria um link de pagamento completo com suporte a cartão de crédito, PIX, parcelamento, desconto e personalização visual.

Se accept_credit e accept_pix não forem enviados, ambos são tratados como true. O pix_discount é opcional e assume 0.

Headers

Header	Valor	Obrigatório
`Content-Type`	application/json	Sim
`venture-signature`	1de97abb11146a6c5aa3f84f811da866c211720cadb58ccca41398c6ddf4bcd	Sim

Corpo da requisição

request.json

{
  "public_key": "vp_prod_ce2d9ce1f7c213eaade842738a4e4",
  "custom_name": "Premium Course",
  "description": "Access to premium online course",
  "amount": 30,
  "customer_email": "john@gmail.com",
  "customer_name": "John Doe",
  "webhook_url": "https://old-piano-01.webhook.cool",
  "max_installments": 6,
  "expiration_date": "2025-08-30T23:59:59Z",
  "accept_credit": true,
  "accept_pix": true,
  "pix_discount": 5.0,
  "fee_payer": "customer",
  "send_email": true,
  "logo_url": "https://venturepay.com.br/logo.png",
  "redirect_url": "https://meusite.com/obrigado"
}

Parâmetros

Campo	Tipo	Obrigatório	Descrição
`public_key`	string	Sim	Sua chave pública de API.
`custom_name`	string	Sim	Nome do produto ou serviço exibido no checkout.
`description`	string	Sim	Descrição detalhada do produto ou serviço.
`amount`	number	Sim	Valor em reais (ex.: 30 equivale a R$ 30,00).
`customer_email`	string	Sim	E-mail do cliente.
`customer_name`	string	Sim	Nome completo do cliente.
`webhook_url`	string	Não	URL que receberá as notificações de pagamento.
`max_installments`	number	Não	Máximo de parcelas permitidas (1 a 12).
`expiration_date`	string	Não	Data de expiração no formato ISO 8601.
`accept_credit`	boolean	Não	Aceitar cartão de crédito (padrão: true).
`accept_pix`	boolean	Não	Aceitar PIX (padrão: true).
`pix_discount`	number	Não	Desconto percentual para PIX (padrão: 0).
`fee_payer`	string	Não	Quem paga a taxa: `customer` ou `merchant`.
`send_email`	boolean	Não	Enviar e-mail com o link de pagamento ao cliente.
`logo_url`	string	Não	URL do logo exibido na página de pagamento.
`redirect_url`	string	Não	URL de redirecionamento após aprovação do pagamento.

200 OK · response.json

{
  "success": true,
  "data": {
    "link_id": "2794cfd3-d3e7-41bf-97e2-997c557d276e",
    "friendly_id": "RNJ149AZ",
    "payment_url": "https://venturepay.com.br/pay/?id=RNJ149AZ",
    "custom_name": "Premium Course",
    "description": "Access to premium online course",
    "amount": 30,
    "max_installments": 6,
    "expiration_date": "2025-08-30 20:59:59",
    "accept_credit": true,
    "accept_pix": false,
    "pix_discount": 5,
    "fee_payer": "customer",
    "no_interest_installments": false,
    "logo_url": "https://venturepay.com.br/uploads/products/...",
    "webhook_url": "https://old-piano-01.webhook.cool",
    "webhook_secret": "ce39c8a97c30aa9f889d2a483ad00653c4000aba7b45df2f55648608f5873ebc",
    "status": "active",
    "customer": {
      "name": "John Doe",
      "email": "john@gmail.com"
    },
    "email_sent": true,
    "created_at": "2025-07-30 01:11:02",
    "metadata": {
      "api_version": "1.0",
      "request_id": "req_68899b5692066",
      "processing_time_ms": 280.46
    }
  },
  "message": "Payment link created successfully"
}

Campo	Tipo	Descrição
`link_id`	string	Identificador único do link de pagamento.
`friendly_id`	string	Identificador curto usado em URLs e referências.
`payment_url`	string	URL completa da página de pagamento.
`webhook_secret`	string	Chave usada para validar a assinatura dos webhooks (SHA256).
`status`	string	Status do link: `active`, `expired` ou `paid`.
`email_sent`	boolean	Indica se o e-mail foi enviado ao cliente.

Código	Significado
`200`	Link criado com sucesso.
`400`	Dados inválidos ou campos obrigatórios ausentes.
`401`	Não autenticado — assinatura inválida.
`403`	Sem permissão para a operação.
`405`	Método HTTP incorreto.
`413`	Payload muito grande.
`429`	Rate limit excedido.
`500`	Erro interno do servidor.

Testando em sandbox

Use o endpoint de sandbox com as mesmas credenciais de produção. Nenhum valor real é movimentado.

POST https://venturepay.com.br/api-sandbox/v1/payment-link/

Cartões de teste

Resultado	Número	CVV	Validade
Aprovado	`4111 1111 1111 1111`	`123`	Qualquer data futura
Recusado	`4000 0000 0000 0002`	`123`	Qualquer data futura
Sem saldo	`4000 0000 0000 9995`	`123`	Qualquer data futura

Webhook de confirmação de pagamento

Quando o pagamento é confirmado, enviamos um POST para a webhook_url configurada, com a assinatura no header x-venturepay-signature.

Header	Exemplo	Descrição
`x-venturepay-signature`	fee1afa1bd6cae83f0f7837566d90c20b7131eee6c0d552d1e26c2c3c470e07d	Assinatura HMAC SHA256 gerada com o `webhook_secret`.
`Content-Type`	application/json	Tipo de conteúdo do payload.

payment_link.payment_completed

{
  "id": "wh_51GX5GJ3Z3DOODPTXNDLYGGV",
  "event": "payment_link.payment_completed",
  "api_version": "1.0",
  "created_at": "2025-07-30T01:10:02-03:00",
  "data": {
    "object": "payment_link_payment",
    "payment_link": {
      "id": 104,
      "friendly_id": "0Q3VPO1I",
      "custom_name": "Premium Course",
      "amount": 30,
      "status": "paid",
      "payment_url": "https://venturepay.com.br/pay/?id=0Q3VPO1I",
      "created_at": "2025-07-30T01:08:01-03:00",
      "expires_at": "2025-08-30T20:59:59-03:00",
      "paid_at": "2025-07-30T01:10:02-03:00"
    },
    "payment": {
      "id": "pay_51GX5GJ3Z3DOODPTXNDLYGGV",
      "transaction_id": "cb822d24-c5d5-4449-8bca-9963d3ac310f",
      "gateway_id": "or_gbEWZE9iLtr80Zax",
      "status": "paid",
      "amount": 31.91,
      "net_amount": 30,
      "fee_amount": 0,
      "currency": "BRL",
      "payment_method": "credit_card",
      "paid_at": "2025-07-30T01:10:02-03:00",
      "credit_card": {
        "brand": "Visa",
        "installments": 1,
        "masked_number": "477587****1106",
        "authorization_code": "0034EG",
        "acquirer_tid": "4040072294",
        "acquirer_nsu": "4040072294"
      }
    },
    "customer": {
      "name": "Vitor Hugo",
      "email": "john@gmail.com",
      "document": "11111111111"
    },
    "company": {
      "id": "comp_88b3fd10-4c95-11f0-8ec2-4e191bcb11b5",
      "name": "VENTUREPAY PAGAMENTOS",
      "document": "53768953000161"
    }
  }
}

Gerar cobrança PIX

POST /orders/charge/pix/

Cria uma cobrança PIX avulsa, sem link de pagamento, e devolve o código copia-e-cola e o QR Code na mesma resposta. O pagamento é confirmado depois, pelo webhook payment_paid.

O amount é sempre em centavos: 15000 equivale a R$ 150,00. O token precisa da permissão sales.

Headers

Header	Valor	Obrigatório
`Content-Type`	application/json	Sim
`venture-signature`	1de97abb11146a6c5aa3f84f811da866c211720cadb58ccca41398c6ddf4bcd8	Sim

Corpo da requisição

request.json

{
  "public_key": "vp_prod_ce2d9ce1f7c213eaade842738a4e4",
  "amount": 15000,
  "fee_payer": "company",
  "expires_in": 3600,
  "order_id": "PEDIDO-1042",
  "description": "Pedido 1042",
  "customer": {
    "name": "Maria de Souza",
    "document": "52998224725",
    "email": "maria@exemplo.com",
    "phone": "5511987654321",
    "birthdate": "01/09/1990"
  }
}

Parâmetros

Campo	Tipo	Obrigatório	Descrição
`public_key`	string	Sim	Sua chave pública de API.
`amount`	integer	Sim	Valor em centavos, de `100` (R$ 1,00) a `10000000` (R$ 100.000,00).
`customer.name`	string	Sim	Nome do pagador, de 3 a 120 caracteres.
`customer.document`	string	Sim	CPF ou CNPJ do pagador. Aceita com ou sem máscara; os dígitos verificadores são conferidos.
`customer.email`	string	Sim	E-mail do pagador.
`customer.phone`	string	Sim	Telefone com 10 a 13 dígitos. O DDI `55`, quando enviado, é removido antes de ir ao processador.
`customer.birthdate`	string	Não	Data de nascimento em `dd/mm/aaaa` ou `aaaa-mm-dd`.
`fee_payer`	string	Não	Quem paga a taxa: `company` (padrão) ou `customer`.
`expires_in`	integer	Não	Validade do código em segundos, de 300 a 86400 (padrão: 3600).
`order_id`	string	Não	Sua referência do pedido, até 100 caracteres entre letras, dígitos e `. _ / -`. É a chave de idempotência.
`description`	string	Não	Descrição da cobrança, até 100 caracteres. Sem valor, usamos o `order_id` ou a data.

200 OK · response.json

{
  "success": true,
  "data": {
    "transaction_id": "VEN9C6FA1E7",
    "order_id": "PEDIDO-1042",
    "status": "pending",
    "payment_method": "pix",
    "description": "Pedido 1042",
    "amount": 150.00,
    "amount_cents": 15000,
    "requested": 150.00,
    "fee": 5.24,
    "net_amount": 144.76,
    "fee_payer": "company",
    "pix": {
      "code": "00020101021226930014br.gov.bcb.pix...",
      "qr_code_url": "https://api.qrserver.com/v1/create-qr-code/?size=250x250&data=...",
      "expires_at": "2026-09-03 19:22:48"
    },
    "customer": {
      "name": "Maria de Souza",
      "document": "52998224725",
      "email": "maria@exemplo.com",
      "phone": "11987654321",
      "birthdate": "1990-09-01"
    },
    "created_at": "2026-09-03T18:22:48-03:00",
    "metadata": {
      "request_id": "req_68899b5692066",
      "processing_time_ms": 412.87
    }
  }
}

Campo	Tipo	Descrição
`transaction_id`	string	Identificador da transação na VenturePay. Use-o para conciliar o webhook.
`pix.code`	string	Código copia-e-cola que o pagador usa no app do banco.
`pix.qr_code_url`	string	Imagem do QR Code correspondente ao código.
`pix.expires_at`	string	Validade do código no fuso de Brasília (`aaaa-mm-dd hh:mm:ss`).
`requested`	number	Valor que você pediu, em reais.
`amount`	number	Valor que o pagador vê. Igual ao `requested` quando a taxa é sua.
`net_amount`	number	Valor que entra na sua conta depois da taxa.
`reused`	boolean	Presente apenas quando o `order_id` reaproveitou uma cobrança ainda válida.

Idempotência pelo order_id

Repetir a chamada com o mesmo order_id não gera uma segunda cobrança: enquanto a primeira estiver pendente e dentro da validade, devolvemos o mesmo código com reused: true. Depois que ela expira ou é paga, um novo order_id igual cria uma cobrança nova.

200 OK · cobrança reaproveitada

{
  "success": true,
  "data": {
    "transaction_id": "VEN9C6FA1E7",
    "order_id": "PEDIDO-1042",
    "status": "pending",
    "reused": true,
    "amount": 150.00,
    "amount_cents": 15000,
    "pix": {
      "code": "00020101021226930014br.gov.bcb.pix...",
      "qr_code_url": "https://api.qrserver.com/v1/create-qr-code/?size=250x250&data=...",
      "expires_at": "2026-09-03 19:22:48"
    }
  }
}

Código	Significado
`200`	Cobrança criada, ou reaproveitada pelo `order_id`.
`400`	JSON inválido, corpo vazio ou campo obrigatório ausente.
`401`	Assinatura ausente, credenciais inválidas ou token expirado.
`403`	Token sem a permissão `sales`, ou conta sem liberação para receber.
`405`	Método diferente de POST.
`413`	Corpo acima de 16 KB.
`422`	Campo fora do formato aceito ou valor fora dos limites.
`429`	Rate limit do token excedido.
`502`	O processador PIX não respondeu ou recusou a cobrança.
`503`	Nenhum processador PIX configurado para a conta.
`500`	Erro interno.

Códigos de erro deste endpoint

`MISSING_SECRET`	O header `venture-signature` não foi enviado.
`INVALID_CREDENTIALS`	A public key não existe ou o segredo não corresponde a ela.
`INSUFFICIENT_PERMISSION`	O token não tem a permissão `sales`.
`COMPANY_NOT_ACTIVE`	A conta não está habilitada a receber pagamentos.
`AMOUNT_BELOW_MINIMUM`	Valor menor que R$ 1,00. O mínimo vem em `error.details`.
`AMOUNT_ABOVE_MAXIMUM`	Valor maior que R$ 100.000,00.
`AMOUNT_TOO_LOW`	O valor não cobre a taxa PIX da conta.
`INVALID_DOCUMENT`	CPF ou CNPJ com dígito verificador inválido.
`INVALID_NAME`	Nome do pagador muito curto.
`INVALID_BIRTHDATE`	Data de nascimento fora do formato ou do intervalo aceito.
`INVALID_FIELD_FORMAT`	O campo tem caracteres fora da lista permitida.
`MALICIOUS_PAYLOAD`	O conteúdo do campo foi recusado pela análise de segurança.
`PIX_PROVIDER_UNREACHABLE`	Falha de comunicação com o processador. Tente novamente em instantes.
`PIX_CODE_NOT_RETURNED`	O processador não devolveu um código pagável.

Quem paga a taxa

O fee_payer decide se a taxa sai do seu líquido ou entra por cima do valor cobrado. Nos dois casos você continua pedindo o valor que quer receber em amount.

fee_payer	O pagador vê	Você recebe	Exemplo com amount 15000
`company`	O valor pedido	O valor pedido menos a taxa	Cobrado R$ 150,00 · líquido R$ 144,76
`customer`	O valor pedido mais a taxa	Exatamente o valor pedido	Cobrado R$ 155,42 · líquido R$ 150,00

Os exemplos usam a taxa de 3,49%. A taxa aplicada é a do seu plano, e os valores exatos voltam na resposta em fee e net_amount.

Exemplo completo

cobranca-pix.sh

curl -X POST 'https://api.venturepay.com.br/v1/orders/charge/pix/' \
  -H 'Content-Type: application/json' \
  -H 'venture-signature: SEU_SECRET_TOKEN' \
  -d '{
    "public_key": "vp_prod_ce2d9ce1f7c213eaade842738a4e4",
    "amount": 15000,
    "order_id": "PEDIDO-1042",
    "description": "Pedido 1042",
    "customer": {
      "name": "Maria de Souza",
      "document": "52998224725",
      "email": "maria@exemplo.com",
      "phone": "5511987654321"
    }
  }'

O que acontece depois

A cobrança nasce como pending e disparamos o evento payment_created.
Quando o pagador conclui o PIX, disparamos payment_paid e agendamos a liberação do saldo em D+1.
O comprovante é enviado por e-mail ao pagador automaticamente.
Para conferir o status sob demanda, use consultar cobrança com o transaction_id.

Consultar cobrança

GET /orders/?public_key={public_key}&transaction_id={transaction_id}

Retorna o status atual de uma cobrança específica a partir do seu identificador de transação.

consultar-cobranca.sh

curl -X GET \
  'https://api.venturepay.com.br/v1/orders/?public_key={public_key}&transaction_id=VEN97F8E4D3' \
  -H 'venture-signature: SEU_SECRET_TOKEN'

Consultar saldo

GET /balance/

Retorna os saldos disponível, pendente e total da sua conta VenturePay.

200 OK · response.json

{
  "success": true,
  "data": {
    "available_balance": 1234.56,
    "pending_balance": 567.89,
    "total_balance": 1802.45,
    "currency": "BRL"
  }
}

Cobranças

Faturas por API

Quatro endpoints controlam o ciclo completo de uma fatura: emitir, acompanhar o status, listar os pagamentos recebidos e reenviar a cobrança por e-mail. É a mesma fatura que aparece em Cobranças no painel, com o mesmo link público e os mesmos e-mails.

POST

Criar fatura

Cobrança única ou recorrente, com PIX e cartão, desconto, multa e juros.

POST

Consultar fatura

Status atual, valores, ciclos pagos e próximo vencimento.

POST

Últimos pagamentos

Histórico de uma fatura ou da conta toda, para conciliação.

POST

Reenviar cobrança

Dispara lembrete, aviso de atraso ou comprovante conforme o status.

Os quatro endpoints autenticam igual ao de cobrança PIX: public_key no corpo, header venture-signature e permissão sales no token. Todos usam POST e valores em centavos.

Situação da conta

Emitir e reenviar cobrança movimenta dinheiro e dispara e-mail em nome da sua empresa, então exige conta ativa. Consultar é leitura e continua funcionando enquanto a conta está em análise ou bloqueada — a mesma regra do painel.

Endpoint	Operação	Exige conta ativa
`/invoices/create/`	Escrita	Sim
`/invoices/resend/`	Escrita	Sim
`/invoices/status/`	Leitura	Não
`/invoices/payments/`	Leitura	Não

Com a conta fora de active, os endpoints de escrita respondem 403 com o código COMPANY_NOT_ACTIVE e o status atual da conta em error.details.company_status.

Como identificar uma fatura

Toda fatura tem dois identificadores, e o campo invoice_id dos endpoints de consulta e reenvio aceita os dois.

Identificador	Formato	Exemplo	Onde aparece
`invoice_id`	UUID v4	a038d20d-ef8b-4c93-a17f-3652ddebb84f	Chave técnica. Guarde esta no seu banco.
`friendly_id`	COB- + 6 dígitos	`COB-360729`	Exibido ao cliente e usado no link de pagamento.

Criar fatura

POST /orders/charge/invoices/create/

Emite a fatura e devolve o link público de pagamento. Por padrão o cliente recebe o e-mail da nova cobrança na hora; envie send_email: false para cuidar da comunicação por conta própria.

Este endpoint não é idempotente: repetir a chamada cria uma segunda fatura e envia um segundo e-mail ao cliente. Guarde o invoice_id da resposta e confira se ele já existe no seu banco antes de tentar de novo.

Headers

Header	Valor	Obrigatório
`Content-Type`	application/json	Sim
`venture-signature`	1de97abb11146a6c5aa3f84f811da866c211720cadb58ccca41398c6ddf4bcd8	Sim

Corpo da requisição

request.json

{
  "public_key": "vp_prod_ce2d9ce1f7c213eaade842738a4e4",
  "amount": 15000,
  "due_date": "2026-10-05",
  "description": "Mensalidade de outubro",
  "methods": ["pix", "card"],
  "max_installments": 6,
  "fee_payer": "company",
  "discounts": {
    "pix": 5,
    "card": 0
  },
  "fine_pct": 2,
  "interest_pct_month": 1,
  "send_email": true,
  "customer": {
    "name": "Maria de Souza",
    "email": "maria@exemplo.com",
    "document": "52998224725",
    "phone": "11987654321",
    "address": {
      "zipcode": "01310-100",
      "street": "Avenida Paulista",
      "number": "1000",
      "complement": "Conj. 12",
      "neighborhood": "Bela Vista",
      "city": "Sao Paulo",
      "state": "SP"
    }
  }
}

Parâmetros

Campo	Tipo	Obrigatório	Descrição
`public_key`	string	Sim	Sua chave pública de API.
`amount`	number	Sim	Valor de cada cobrança, em centavos. Máximo de `100000000` (R$ 1.000.000,00).
`due_date`	string	Sim	Primeiro vencimento, em `aaaa-mm-dd` ou `dd/mm/aaaa`. Datas passadas são aceitas e nascem como `atrasada`.
`description`	string	Não	Descrição exibida ao cliente. Até 255 caracteres.
`methods`	array	Não	Meios aceitos: `pix` e/ou `card`. Padrão `["pix"]`.
`max_installments`	number	Não	De 1 a 12. Sem `card` em `methods`, é forçado para 1.
`fee_payer`	string	Não	`company` (padrão) ou `customer`.
`discounts.pix`	number	Não	Desconto percentual no PIX (0 a 100). Ignorado se o PIX não está em `methods`.
`discounts.card`	number	Não	Desconto percentual no cartão (0 a 100). Ignorado se o cartão não está em `methods`.
`fine_pct`	number	Não	Multa percentual aplicada após o vencimento.
`interest_pct_month`	number	Não	Juros percentuais ao mês em caso de atraso.
`type`	string	Não	`unica` (padrão) ou `recorrente`.
`interval`	string	Não	Só em recorrente: `semanal`, `quinzenal`, `mensal` (padrão), `trimestral`, `semestral` ou `anual`.
`duration`	string	Não	Só em recorrente: `indeterminada` (padrão), `ciclos` ou `ate`.
`cycles`	number	Condicional	Obrigatório quando `duration` é `ciclos`. De 1 a 999.
`until`	string	Condicional	Obrigatório quando `duration` é `ate`. Precisa ser posterior a `due_date`.
`send_email`	boolean	Não	Enviar o e-mail da nova cobrança ao cliente. Padrão `true`.
`customer.name`	string	Sim	Nome do cliente. Não aceita dígitos.
`customer.email`	string	Sim	E-mail que recebe a cobrança e o comprovante.
`customer.document`	string	Sim	CPF ou CNPJ. O dígito verificador é conferido.
`customer.phone`	string	Sim	DDD + número. O DDI `55` é aceito e removido.
`customer.address`	object	Não	Endereço completo. Opcional, mas obrigatório em grupo — veja abaixo.

Endereço do cliente

O objeto customer.address pode ser omitido por inteiro. Se você enviar qualquer campo dele, todos os obrigatórios do grupo passam a ser exigidos — endereço pela metade é recusado com 422.

Campo	Formato	Obrigatório no grupo
`zipcode`	8 dígitos, com ou sem hífen	Sim
`street`	Até 255 caracteres	Sim
`number`	Até 20 caracteres	Sim
`neighborhood`	Até 120 caracteres	Sim
`city`	Até 120 caracteres	Sim
`state`	UF de 2 letras	Sim
`complement`	Até 100 caracteres	Não

200 OK · response.json

{
  "success": true,
  "data": {
    "invoice": {
      "invoice_id": "a038d20d-ef8b-4c93-a17f-3652ddebb84f",
      "friendly_id": "COB-360729",
      "status": "gerada",
      "description": "Mensalidade de outubro",
      "amount": 150,
      "amount_cents": 15000,
      "expected_total": 150,
      "paid_total": 0,
      "fee_payer": "company",
      "payment_methods": ["pix", "card"],
      "max_installments": 6,
      "discounts": {
        "pix_pct": 5,
        "card_pct": 0
      },
      "fine_pct": 2,
      "interest_pct_month": 1,
      "recurrence": {
        "type": "unica",
        "interval": null,
        "duration": null,
        "until_date": null,
        "cycles_total": 1,
        "cycles_paid": 0
      },
      "due_date": "2026-10-05",
      "next_charge_date": null,
      "payment_url": "https://venturepay.com.br/charge/?id=COB-360729",
      "customer": {
        "name": "Maria de Souza",
        "email": "maria@exemplo.com",
        "phone": "11987654321",
        "document": "52998224725",
        "address": {
          "zipcode": "01310-100",
          "street": "Avenida Paulista",
          "number": "1000",
          "complement": "Conj. 12",
          "neighborhood": "Bela Vista",
          "city": "Sao Paulo",
          "state": "SP"
        }
      },
      "payments": [],
      "created_at": "2026-09-14 17:59:27",
      "updated_at": "2026-09-14 17:59:27"
    },
    "email_sent": true,
    "metadata": {
      "request_id": "req_6aa835ff8c00d",
      "processing_time_ms": 108.49
    }
  }
}

Campos do objeto invoice

Campo	Tipo	Descrição
`invoice_id`	string	Identificador técnico da fatura (UUID). Guarde este valor.
`friendly_id`	string	Identificador curto no formato `COB-000000`.
`status`	string	`gerada`, `paga`, `atrasada` ou `cancelada`.
`amount`	number	Valor de cada cobrança em reais. O mesmo valor em centavos vem em `amount_cents`.
`expected_total`	number	Total previsto somando todos os ciclos. `null` em recorrência indeterminada.
`paid_total`	number	Soma do que já foi efetivamente pago.
`payment_methods`	array	Meios habilitados na fatura.
`recurrence.cycles_total`	number	Total de ciclos previstos. `null` em recorrência indeterminada.
`recurrence.cycles_paid`	number	Quantos ciclos já foram pagos.
`next_charge_date`	string	Próxima cobrança da recorrência. `null` em cobrança única.
`payment_url`	string	Link público onde o cliente paga. É o mesmo enviado no e-mail.
`payments`	array	Pagamentos vinculados, do mais recente para o mais antigo.
`email_sent`	boolean	Fora do objeto `invoice`. Indica se o e-mail saiu. A fatura é criada mesmo quando o envio falha.

Código	Significado
`200`	Fatura criada.
`400`	JSON inválido, corpo vazio ou campo obrigatório ausente.
`401`	Assinatura ausente, credenciais inválidas ou token expirado.
`403`	Token sem a permissão `sales`, ou conta fora de `active`.
`405`	Método diferente de POST.
`413`	Corpo acima de 16 KB.
`422`	Campo fora do formato aceito ou valor fora dos limites.
`429`	Rate limit do token excedido.
`500`	Erro interno.

Códigos de erro deste endpoint

`MISSING_SECRET`	O header `venture-signature` não foi enviado.
`INVALID_CREDENTIALS`	A public key não existe ou o segredo não corresponde a ela.
`TOKEN_EXPIRED`	O token passou da validade.
`INSUFFICIENT_PERMISSION`	O token não tem a permissão `sales`.
`COMPANY_NOT_ACTIVE`	A conta não está ativa. O status atual vem em `error.details.company_status`.
`MISSING_FIELD`	Campo obrigatório ausente. O campo vem em `error.field`.
`INVALID_AMOUNT`	`amount` não é um inteiro positivo em centavos.
`AMOUNT_ABOVE_MAXIMUM`	Valor acima de R$ 1.000.000,00.
`INVALID_DATE`	`due_date` ou `until` fora do formato ou do intervalo aceito.
`INVALID_DOCUMENT`	CPF ou CNPJ com dígito verificador inválido.
`INVALID_NAME`	Nome do cliente muito curto ou com dígitos.
`INVALID_EMAIL`	E-mail do cliente inválido.
`INVALID_FIELD_VALUE`	Valor fora da lista ou da faixa aceita — inclui `until` anterior ao vencimento.
`INVALID_FIELD_FORMAT`	O campo tem caracteres fora da lista permitida.
`FIELD_TOO_LONG`	O campo passou do tamanho máximo.
`MALICIOUS_PAYLOAD`	O conteúdo do campo foi recusado pela análise de segurança.

Cobrança recorrente

Com type: "recorrente", o amount passa a ser o valor de cada ciclo e o duration decide até quando a cobrança se repete.

duration	Até quando cobra	Campo exigido	expected_total
`indeterminada`	Até você cancelar a cobrança no painel	—	`null`
`ciclos`	Por um número fixo de ciclos	`cycles`	amount × cycles
`ate`	Até a data limite informada	`until`	amount × ciclos que couberem no período

recorrente.json · 12 mensalidades de R$ 99,90

{
  "public_key": "vp_prod_ce2d9ce1f7c213eaade842738a4e4",
  "amount": 9990,
  "due_date": "2026-10-05",
  "type": "recorrente",
  "interval": "mensal",
  "duration": "ciclos",
  "cycles": 12,
  "customer": {
    "name": "Joao da Silva",
    "email": "joao@exemplo.com",
    "document": "11144477735",
    "phone": "11912345678"
  }
}

A resposta traz expected_total: 1198.8 e recurrence.cycles_total: 12. Cada ciclo pago entra em payments e soma em recurrence.cycles_paid.

Exemplo completo

criar-fatura.sh

curl -X POST 'https://api.venturepay.com.br/v1/orders/charge/invoices/create/' \
  -H 'Content-Type: application/json' \
  -H 'venture-signature: SEU_SECRET_TOKEN' \
  -d '{
    "public_key": "vp_prod_ce2d9ce1f7c213eaade842738a4e4",
    "amount": 15000,
    "due_date": "2026-10-05",
    "description": "Mensalidade de outubro",
    "methods": ["pix", "card"],
    "max_installments": 6,
    "customer": {
      "name": "Maria de Souza",
      "email": "maria@exemplo.com",
      "document": "52998224725",
      "phone": "11987654321"
    }
  }'

Consultar fatura

POST /orders/charge/invoices/status/

Devolve a fatura inteira: status atual, valores, ciclos já pagos, próximo vencimento, link de pagamento e os pagamentos vinculados. É o mesmo objeto invoice retornado na criação.

Corpo da requisição

request.json

{
  "public_key": "vp_prod_ce2d9ce1f7c213eaade842738a4e4",
  "invoice_id": "COB-360729"
}

Parâmetros

Campo	Tipo	Obrigatório	Descrição
`public_key`	string	Sim	Sua chave pública de API.
`invoice_id`	string	Sim	O `invoice_id` (UUID) ou o `friendly_id` (`COB-000000`) da fatura.

200 OK · response.json

{
  "success": true,
  "data": {
    "invoice": {
      "invoice_id": "a038d20d-ef8b-4c93-a17f-3652ddebb84f",
      "friendly_id": "COB-360729",
      "status": "paga",
      "amount": 150,
      "amount_cents": 15000,
      "expected_total": 150,
      "paid_total": 150,
      "recurrence": {
        "type": "unica",
        "cycles_total": 1,
        "cycles_paid": 1
      },
      "due_date": "2026-10-05",
      "next_charge_date": null,
      "payment_url": "https://venturepay.com.br/charge/?id=COB-360729",
      "payments": [
        {
          "transaction_id": "VEN97F8E4D3",
          "invoice_id": "a038d20d-ef8b-4c93-a17f-3652ddebb84f",
          "status": "paga",
          "gateway_status": "approved",
          "payment_method": "pix",
          "amount": 150,
          "amount_cents": 15000,
          "created_at": "2026-10-02 18:00:04"
        }
      ],
      "created_at": "2026-09-14 17:59:27",
      "updated_at": "2026-10-02 18:00:04"
    },
    "metadata": {
      "request_id": "req_6aa835ffc6614",
      "processing_time_ms": 95.66
    }
  }
}

O exemplo está resumido: o objeto invoice traz todos os campos listados em criar fatura.

Código	Significado
`200`	Fatura encontrada.
`400`	JSON inválido, corpo vazio ou `public_key` ausente.
`401`	Assinatura ausente, credenciais inválidas ou token expirado.
`403`	Token sem a permissão `sales`.
`404`	Nenhuma fatura sua com esse identificador.
`405`	Método diferente de POST.
`422`	O `invoice_id` não parece um UUID nem um `COB-`.
`429`	Rate limit do token excedido.
`500`	Erro interno.

Códigos de erro deste endpoint

`INVOICE_NOT_FOUND`	A fatura não existe ou pertence a outra conta.
`INVALID_INVOICE_ID`	O identificador enviado está fora dos dois formatos aceitos.
`MISSING_FIELD`	`invoice_id` não foi enviado.

Os quatro status

O status atrasada é calculado no momento da consulta, não gravado: uma fatura em aberto que passou do vencimento já responde como atrasada. Por isso o valor aqui é sempre igual ao que aparece no painel.

status	Significado	E-mail no reenvio
`gerada`	Em aberto, dentro do prazo	Lembrete
`atrasada`	Em aberto e vencida	Aviso de atraso
`paga`	Quitada	Comprovante
`cancelada`	Cancelada no painel	Aviso de cancelamento

Exemplo completo

consultar-fatura.sh

curl -X POST 'https://api.venturepay.com.br/v1/orders/charge/invoices/status/' \
  -H 'Content-Type: application/json' \
  -H 'venture-signature: SEU_SECRET_TOKEN' \
  -d '{
    "public_key": "vp_prod_ce2d9ce1f7c213eaade842738a4e4",
    "invoice_id": "COB-360729"
  }'

Últimos pagamentos

POST /orders/charge/invoices/payments/

Lista os pagamentos de cobranças, do mais recente para o mais antigo. Com invoice_id, devolve o histórico daquela fatura — útil em recorrência, onde cada ciclo pago é um pagamento. Sem invoice_id, devolve os últimos pagamentos de todas as suas faturas, que é o formato para conciliação.

Corpo da requisição

request.json

{
  "public_key": "vp_prod_ce2d9ce1f7c213eaade842738a4e4",
  "status": "paga",
  "limit": 20,
  "offset": 0
}

Parâmetros

Campo	Tipo	Obrigatório	Descrição
`public_key`	string	Sim	Sua chave pública de API.
`invoice_id`	string	Não	Restringe a uma fatura. Aceita o UUID ou o `COB-`. Sem ele, a busca cobre a conta toda.
`status`	string	Não	Filtra por situação do pagamento. Valores na tabela abaixo.
`limit`	number	Não	Quantos pagamentos devolver, de 1 a 100. Padrão 20.
`offset`	number	Não	Quantos registros pular, para paginar. Padrão 0.

Valores aceitos em status

status	gateway_status	Significado
`paga`	`approved`	Pagamento confirmado.
`pendente`	`pending`	Aguardando confirmação.
`estornada`	`refunded`	Valor devolvido ao pagador.
`cancelada`	`canceled`	Cobrança cancelada antes da confirmação.
`falha`	`failed`	Tentativa recusada.
`fraude`	`fraud`	Bloqueado pela análise antifraude.

200 OK · response.json

{
  "success": true,
  "data": {
    "invoice": null,
    "payments": [
      {
        "transaction_id": "VEN97F8E4D3",
        "invoice_id": "a038d20d-ef8b-4c93-a17f-3652ddebb84f",
        "status": "paga",
        "gateway_status": "approved",
        "payment_method": "pix",
        "amount": 150,
        "amount_cents": 15000,
        "created_at": "2026-10-02 18:00:04",
        "invoice_friendly_id": "COB-360729",
        "customer": {
          "name": "Maria de Souza",
          "email": "maria@exemplo.com"
        }
      }
    ],
    "paging": {
      "limit": 20,
      "offset": 0,
      "returned": 1,
      "has_more": false
    },
    "filters": {
      "invoice_id": null,
      "status": "paga"
    },
    "metadata": {
      "request_id": "req_6aa83624723fc",
      "processing_time_ms": 97.75
    }
  }
}

Campos da resposta

Campo	Tipo	Descrição
`invoice`	object	Resumo da fatura consultada. `null` quando você não enviou `invoice_id`.
`payments[].transaction_id`	string	Identificador do pagamento. Serve para consultar a cobrança.
`payments[].status`	string	Situação em português, igual à do painel.
`payments[].gateway_status`	string	O mesmo status no vocabulário técnico, se você preferir tratar por ele.
`payments[].invoice_friendly_id`	string	De qual fatura veio o pagamento — importante na listagem da conta toda.
`paging.returned`	number	Quantos registros esta página trouxe.
`paging.has_more`	boolean	Indica que provavelmente há mais registros. Aumente o `offset` para continuar.
`filters`	object	Ecoa os filtros aplicados, para você confirmar o que foi consultado.

Código	Significado
`200`	Consulta realizada. Uma lista vazia também responde 200.
`400`	JSON inválido, corpo vazio ou `public_key` ausente.
`401`	Assinatura ausente, credenciais inválidas ou token expirado.
`403`	Token sem a permissão `sales`.
`404`	O `invoice_id` informado não é seu.
`405`	Método diferente de POST.
`422`	`status` fora da lista, ou `limit`/`offset` fora da faixa.
`429`	Rate limit do token excedido.
`500`	Erro interno.

Códigos de erro deste endpoint

`INVOICE_NOT_FOUND`	A fatura não existe ou pertence a outra conta.
`INVALID_INVOICE_ID`	O identificador enviado está fora dos dois formatos aceitos.
`INVALID_FIELD_VALUE`	`status`, `limit` ou `offset` com valor não aceito.

Exemplo completo

ultimos-pagamentos.sh

curl -X POST 'https://api.venturepay.com.br/v1/orders/charge/invoices/payments/' \
  -H 'Content-Type: application/json' \
  -H 'venture-signature: SEU_SECRET_TOKEN' \
  -d '{
    "public_key": "vp_prod_ce2d9ce1f7c213eaade842738a4e4",
    "status": "paga",
    "limit": 50
  }'

Reenviar cobrança

POST /orders/charge/invoices/resend/

Envia o e-mail da cobrança novamente ao cliente. Você não escolhe o conteúdo: ele acompanha o status da fatura, exatamente como o botão Reenviar do painel. A resposta informa em email.variant qual e-mail saiu.

O envio é sincrônico: só respondemos 200 depois que o servidor de e-mail aceitou a mensagem. Se ele recusar, a resposta é 502 e nada foi enviado — pode tentar de novo sem risco de e-mail duplicado.

Corpo da requisição

request.json

{
  "public_key": "vp_prod_ce2d9ce1f7c213eaade842738a4e4",
  "invoice_id": "COB-360729"
}

Parâmetros

Campo	Tipo	Obrigatório	Descrição
`public_key`	string	Sim	Sua chave pública de API.
`invoice_id`	string	Sim	O `invoice_id` (UUID) ou o `friendly_id` (`COB-000000`) da fatura.

Qual e-mail é enviado

Status da fatura	email.variant	Conteúdo
`gerada`	`reminder`	Lembrete com o valor, o vencimento e o link de pagamento.
`atrasada`	`overdue`	Aviso de cobrança em atraso.
`paga`	`receipt`	Comprovante de pagamento.
`cancelada`	`canceled`	Aviso de cancelamento da cobrança.

200 OK · response.json

{
  "success": true,
  "data": {
    "invoice": {
      "invoice_id": "a038d20d-ef8b-4c93-a17f-3652ddebb84f",
      "friendly_id": "COB-360729",
      "status": "atrasada",
      "amount": 150,
      "payment_url": "https://venturepay.com.br/charge/?id=COB-360729"
    },
    "email_sent": true,
    "email": {
      "variant": "overdue",
      "to": "maria@exemplo.com"
    },
    "metadata": {
      "request_id": "req_6aa83625ac8f6",
      "processing_time_ms": 232.85
    }
  }
}

O objeto invoice está resumido acima, mas vem completo na resposta real — os mesmos campos de criar fatura.

Código	Significado
`200`	E-mail aceito pelo servidor de envio.
`400`	JSON inválido, corpo vazio ou `public_key` ausente.
`401`	Assinatura ausente, credenciais inválidas ou token expirado.
`403`	Token sem a permissão `sales`, ou conta fora de `active`.
`404`	Nenhuma fatura sua com esse identificador.
`405`	Método diferente de POST.
`422`	O `invoice_id` está fora dos formatos aceitos.
`429`	Rate limit do token excedido.
`502`	O e-mail não pôde ser enviado. Tente novamente em instantes.
`500`	Erro interno.

Códigos de erro deste endpoint

`EMAIL_NOT_SENT`	O servidor de e-mail recusou a mensagem. O `invoice_id` vem em `error.details`.
`INVOICE_NOT_FOUND`	A fatura não existe ou pertence a outra conta.
`INVALID_INVOICE_ID`	O identificador enviado está fora dos dois formatos aceitos.
`COMPANY_NOT_ACTIVE`	A conta precisa estar ativa para enviar e-mail em seu nome.

Exemplo completo

reenviar-cobranca.sh

curl -X POST 'https://api.venturepay.com.br/v1/orders/charge/invoices/resend/' \
  -H 'Content-Type: application/json' \
  -H 'venture-signature: SEU_SECRET_TOKEN' \
  -d '{
    "public_key": "vp_prod_ce2d9ce1f7c213eaade842738a4e4",
    "invoice_id": "COB-360729"
  }'

Fluxo recomendado de integração

Crie a fatura e guarde o invoice_id junto do seu pedido. É o que evita duplicar a cobrança em uma retentativa.
Prefira reagir ao webhook payment_paid em vez de consultar em laço. Cada pagamento de fatura dispara o evento.
Use consultar fatura para conferência pontual e últimos pagamentos para fechar o dia.
Reenvie a cobrança quando o status virar atrasada: o e-mail de atraso é escolhido automaticamente.
Editar e cancelar fatura seguem exclusivos do painel, em Cobranças.

Eventos

Webhooks

Webhooks entregam notificações automáticas assim que um evento acontece nas suas transações, sem necessidade de polling.

Como funciona

Cadastre uma URL em Desenvolvedor → Webhooks e marque os eventos que quer receber.

Quando o evento acontece, enviamos um POST assinado para todas as URLs que o assinam.

Seu sistema valida a assinatura e responde 2xx.

Sem resposta 2xx, repetimos a entrega e registramos cada tentativa no painel.

Existem dois canais independentes. Os eventos desta seção são os webhooks da conta, cadastrados no painel e válidos para todas as cobranças da API. Um link de pagamento com webhook_url própria continua recebendo o evento payment_link.payment_completed naquela URL, com o formato descrito em criar link de pagamento.

Eventos disponíveis

Evento	Quando é disparado	Status em data
`payment_created`	Cobrança gerada e aguardando pagamento. Sai logo depois da resposta de gerar cobrança PIX.	`pending`
`payment_paid`	Pagamento liquidado. A liberação do saldo já está agendada e o comprovante foi enviado ao pagador.	`paid`

Os dois eventos usam o mesmo envelope: event, event_id, created_at, os dados da sua conta em company e a transação em data. O transaction_id é o mesmo devolvido na criação da cobrança, então dá para conciliar direto.

payment_created

{
  "event": "payment_created",
  "event_id": "8f2c1d94-5b7a-4e10-9c33-1af6e0d27b45",
  "created_at": "2026-09-03T18:22:44-03:00",
  "company": {
    "companie_id": "fb59bbdd8f73be1364b8c14c9d374844",
    "name": "MINHA LOJA LTDA",
    "document": "61423529000102"
  },
  "data": {
    "transaction_id": "VEN9C6FA1E7",
    "order_id": "PEDIDO-1042",
    "status": "pending",
    "payment_method": "pix",
    "description": "Pedido 1042",
    "amount": 150.00,
    "amount_cents": 15000,
    "requested": 150.00,
    "fee": 5.24,
    "net_amount": 144.76,
    "fee_payer": "company",
    "pix": {
      "code": "00020101021226930014br.gov.bcb.pix...",
      "qr_code_url": "https://api.qrserver.com/v1/create-qr-code/?size=250x250&data=...",
      "expires_at": "2026-09-03 19:22:48"
    },
    "customer": {
      "name": "Maria de Souza",
      "document": "52998224725",
      "email": "maria@exemplo.com",
      "phone": "11987654321",
      "birthdate": "1990-09-01"
    },
    "created_at": "2026-09-03T18:22:44-03:00"
  }
}

payment_paid

{
  "event": "payment_paid",
  "event_id": "10acfc1a-34b2-43c9-be1c-41a9b8e7f0da",
  "created_at": "2026-09-03T18:22:48-03:00",
  "company": {
    "companie_id": "fb59bbdd8f73be1364b8c14c9d374844",
    "name": "MINHA LOJA LTDA",
    "document": "61423529000102"
  },
  "data": {
    "transaction_id": "VEN9C6FA1E7",
    "order_id": "PEDIDO-1042",
    "status": "paid",
    "payment_method": "pix",
    "amount": 150.00,
    "amount_cents": 15000,
    "fee": 5.24,
    "net_amount": 144.76,
    "fee_payer": "company",
    "paid_at": "2026-09-03T18:22:48-03:00",
    "release_date": "2026-09-04T18:22:48-03:00",
    "customer": {
      "name": "Maria de Souza",
      "document": "52998224725",
      "email": "maria@exemplo.com",
      "phone": "11987654321"
    }
  }
}

Campo	Tipo	Descrição
`event_id`	string	Identificador único desta entrega. Use-o para descartar eventos repetidos.
`data.transaction_id`	string	Mesmo identificador devolvido quando a cobrança foi criada.
`data.order_id`	string	Sua referência enviada em `order_id`, ou `null` se não tiver enviado.
`data.paid_at`	string	Momento da liquidação, em ISO 8601 com o fuso de Brasília.
`data.release_date`	string	Quando o líquido entra no saldo disponível: D+1 no PIX, e o prazo do seu plano no cartão.
`data.net_amount`	number	Valor creditado depois da taxa. É o que será liberado na `release_date`.
`data.card`	object	Presente apenas quando `payment_method` é `card`.

No cartão, o envelope é o mesmo e ganha o bloco card. O release_date segue o prazo contratado da sua conta.

payment_paid · cartão

{
  "event": "payment_paid",
  "event_id": "c41e77b0-9d52-4a8f-8b16-5e2c0c9f31aa",
  "created_at": "2026-09-03T18:21:53-03:00",
  "company": { /* igual ao PIX */ },
  "data": {
    "transaction_id": "VENCRD6923",
    "order_id": "PEDIDO-2087",
    "status": "paid",
    "payment_method": "card",
    "amount": 200.00,
    "amount_cents": 20000,
    "fee": 10.00,
    "net_amount": 190.00,
    "fee_payer": "company",
    "paid_at": "2026-09-03T18:21:53-03:00",
    "release_date": "2026-09-04T18:21:53-03:00",
    "customer": {
      "name": "Ana Ribeiro",
      "document": "52998224725",
      "email": "ana@exemplo.com",
      "phone": "11911112222"
    },
    "card": {
      "brand": "VISA",
      "installments": 3,
      "masked_number": "411111******1111",
      "authorization_code": "AUTH123456"
    }
  }
}

Assinatura e validação

Cada entrega leva a assinatura do corpo em venture-signature: um HMAC SHA256 do JSON recebido, calculado com o secret do webhook que aparece no painel. Compare antes de processar qualquer dado.

Header	Descrição	Exemplo
`venture-signature`	HMAC SHA256 do corpo em hexadecimal, sem prefixo. Enviado sempre que o webhook tem secret.	ce39c8a97c30aa9f889d2a483ad00653c4000aba7b45df2f55648608f5873ebc
`X-Venture-Event`	Nome do evento entregue. É o mesmo valor de `event` no corpo.	`payment_paid`
`Content-Type`	Sempre JSON em UTF-8.	`application/json; charset=utf-8`
`User-Agent`	Identifica o nosso entregador.	`VenturePay-Webhooks/1.0`

Assine o corpo exatamente como chegou, byte a byte. Se o seu framework decodifica o JSON antes, guarde o corpo cru: reserializar muda espaços e escapes e invalida a comparação.

validar-webhook.php

$payload   = file_get_contents('php://input');
$signature = $_SERVER['HTTP_VENTURE_SIGNATURE'] ?? '';
$secret    = 'o-secret-do-webhook-no-painel';

$expected = hash_hmac('sha256', $payload, $secret);

if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    exit;
}

$event = json_decode($payload, true);

// Retentativas reentregam o mesmo event_id: registre e ignore repetidos.
if (jaProcessado($event['event_id'])) {
    http_response_code(200);
    exit;
}

if ($event['event'] === 'payment_paid') {
    liberarPedido(
        $event['data']['order_id'],
        $event['data']['transaction_id']
    );
}

// Responda antes de qualquer trabalho pesado.
http_response_code(200);

webhook.js

const crypto = require('crypto');
const express = require('express');

const app = express();
const SECRET = 'o-secret-do-webhook-no-painel';

// raw: o corpo precisa chegar sem passar pelo parser de JSON.
app.post('/webhooks/venturepay', express.raw({ type: 'application/json' }), (req, res) => {
  const expected = crypto
    .createHmac('sha256', SECRET)
    .update(req.body)
    .digest('hex');

  const received = req.get('venture-signature') || '';

  if (received.length !== expected.length ||
      !crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected))) {
    return res.sendStatus(401);
  }

  const event = JSON.parse(req.body);

  res.sendStatus(200);           // confirme primeiro
  processar(event).catch(console.error); // depois trabalhe
});

Entrega e retentativas

O disparo acontece depois que a transação já está gravada, então a resposta da API nunca espera pelo seu servidor. Cada tentativa fica registrada em Desenvolvedor → Webhooks, com status HTTP, tempo e corpo da resposta.

Comportamento	Como funciona
Sucesso	Qualquer status `2xx`. Encerra a entrega daquele destino.
Falha	Outro status, timeout ou erro de conexão. Contamos como tentativa e repetimos.
Tentativas	Conforme o campo Tentativas do webhook no painel — padrão 3, máximo 5.
Timeout	Conforme o painel, de 5 a 30 segundos por tentativa.
Esgotou	A entrega fica como `abandoned` no histórico e o contador de falhas do webhook sobe.
Vários destinos	Todas as URLs ativas que assinam o evento recebem, cada uma com o seu próprio ciclo de tentativas.

Requisitos da URL

https:// com certificado válido, na porta 443 ou 8443.
Endereço público. Recusamos localhost, redes internas e domínios que resolvem para IP privado.
Sem redirecionamento: um 301 ou 302 não é seguido e conta como falha.
Sem usuário e senha embutidos na URL.

Checklist de integração

Valide a assinatura antes de olhar o conteúdo.
Guarde o event_id e descarte o que já processou.
Libere o pedido só com payment_paid, nunca com payment_created.
Confira o valor em data.amount antes de dar baixa.
Responda 2xx primeiro e processe depois, para não estourar o timeout.

Confiabilidade

Tratamento de erros

A API usa códigos HTTP convencionais e retorna erros estruturados com código, mensagem e detalhes de correção.

error.json

{
  "success": false,
  "error": {
    "code": "INVALID_SIGNATURE",
    "message": "Assinatura HMAC inválida",
    "details": "Verifique se a secret key está correta e se o body está sendo assinado corretamente"
  }
}

Códigos HTTP

`200 OK`	Requisição processada com sucesso.
`400 Bad Request`	Dados inválidos ou campos obrigatórios ausentes.
`401 Unauthorized`	Assinatura inválida ou token inexistente.
`404 Not Found`	Recurso não encontrado.
`429 Too Many Requests`	Rate limit excedido.
`500 Server Error`	Erro interno do servidor.

Códigos de erro comuns

`INVALID_SIGNATURE`	Assinatura HMAC inválida.
`MISSING_FIELD`	Campo obrigatório não enviado.
`INVALID_CPF`	CPF inválido ou malformado.
`INVALID_EMAIL`	E-mail inválido.
`AMOUNT_TOO_LOW`	Valor mínimo é R$ 1,00.
`TRANSACTION_NOT_FOUND`	ID de transação não encontrado.

Dicas de depuração

Verifique error.code para identificar a natureza do erro.
Use error.details para orientações específicas de correção.
Implemente retentativa com backoff exponencial para erros 5xx.
Não repita requisições com erro 4xx sem antes corrigir o payload.

SDKs e snippets

Exemplos de código

Implementações completas para criar um link de pagamento, prontas para copiar e adaptar.

VenturePayAPI.php

<?php

class VenturePayAPI {
    private $publicKey;
    private $secretKey;
    private $baseUrl = 'https://api.venturepay.com.br/v1/';

    public function __construct($publicKey, $secretKey) {
        $this->publicKey = $publicKey;
        $this->secretKey = $secretKey;
    }

    public function createPaymentLink($data) {
        $data['public_key'] = $this->publicKey;
        $body = json_encode($data);

        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, $this->baseUrl . 'orders/charge/payment-link/');
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Content-Type: application/json',
            'venture-signature: ' . $this->secretKey
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        return json_decode($response, true);
    }
}

// Uso
$api = new VenturePayAPI(
    'vp_prod_ce2d9ce1f7c213eaade842738a4e4',
    '1de97abb11146a6c5aa3f84f811da866c211720cadb58ccca41398c6ddf4bcd8'
);

$link = $api->createPaymentLink([
    'custom_name'    => 'Curso Premium',
    'description'    => 'Acesso ao curso online',
    'amount'         => 30,
    'customer_name'  => 'Maria Silva Santos',
    'customer_email' => 'cliente@exemplo.com',
    'webhook_url'    => 'https://meusite.com/webhook',
    'send_email'     => true
]);

echo $link['data']['payment_url'];

venturepay.js

const axios = require('axios');

class VenturePayAPI {
  constructor(publicKey, secretKey) {
    this.publicKey = publicKey;
    this.secretKey = secretKey;
    this.baseUrl = 'https://api.venturepay.com.br/v1/';
  }

  async createPaymentLink(data) {
    data.public_key = this.publicKey;

    try {
      const response = await axios.post(
        this.baseUrl + 'orders/charge/payment-link/',
        JSON.stringify(data),
        {
          headers: {
            'Content-Type': 'application/json',
            'venture-signature': this.secretKey
          }
        }
      );
      return response.data;
    } catch (error) {
      throw new Error(error.response?.data?.error?.message || 'API Error');
    }
  }
}

// Uso
const api = new VenturePayAPI(
  'vp_prod_ce2d9ce1f7c213eaade842738a4e4',
  '1de97abb11146a6c5aa3f84f811da866c211720cadb58ccca41398c6ddf4bcd8'
);

api.createPaymentLink({
  custom_name: 'Curso Premium',
  description: 'Acesso ao curso online',
  amount: 30,
  customer_name: 'Maria Silva Santos',
  customer_email: 'cliente@exemplo.com',
  webhook_url: 'https://meusite.com/webhook',
  send_email: true
})
  .then(res => console.log(res.data.payment_url))
  .catch(err => console.error(err.message));

venturepay.py

import json
import requests


class VenturePayAPI:
    def __init__(self, public_key, secret_key):
        self.public_key = public_key
        self.secret_key = secret_key
        self.base_url = 'https://api.venturepay.com.br/v1/'

    def create_payment_link(self, data):
        data['public_key'] = self.public_key
        body = json.dumps(data, separators=(',', ':'))

        headers = {
            'Content-Type': 'application/json',
            'venture-signature': self.secret_key
        }

        response = requests.post(
            self.base_url + 'orders/charge/payment-link/',
            data=body,
            headers=headers
        )

        return response.json()


# Uso
api = VenturePayAPI(
    'vp_prod_ce2d9ce1f7c213eaade842738a4e4',
    '1de97abb11146a6c5aa3f84f811da866c211720cadb58ccca41398c6ddf4bcd8'
)

link = api.create_payment_link({
    'custom_name': 'Curso Premium',
    'description': 'Acesso ao curso online',
    'amount': 30,
    'customer_name': 'Maria Silva Santos',
    'customer_email': 'cliente@exemplo.com',
    'webhook_url': 'https://meusite.com/webhook',
    'send_email': True
})

print(link['data']['payment_url'])