VenturePay
Entrar Obter credenciais
v1 estável

Documentação da API VenturePay

Crie links de pagamento, consulte cobranças e saldo e receba webhooks em tempo real. Endpoints REST previsíveis, autenticação por assinatura e sandbox completo para testar sem custo.

Ver endpoints Como autenticar
URL base de produção
POST https://api.venturepay.com.br/v1/
Aprovação
98.2%
Antifraude
~80ms
Cartão
D+1
Sandbox
Grátis
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.

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"
  }
}
Eventos

Webhooks

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

Como funciona

1

Configure uma URL de webhook na sua conta ou no próprio link de pagamento.

2

Quando o evento ocorre, enviamos um POST assinado para a sua URL.

3

Seu sistema valida a assinatura e responde com status 200.

4

Sem confirmação, reenviamos a notificação automaticamente.

Eventos disponíveis

Evento Quando é disparado
payment_paid Pagamento aprovado e valor creditado na sua conta.
payment_created Nova cobrança criada e aguardando pagamento.
payment_cancelled Pagamento cancelado antes de ser processado.
payment_expired Cobrança expirada sem pagamento (após 24 horas).

Estrutura do payload

webhook.json 
{
  "success": true,
  "data": {
    "transaction_id": "VEN9C6FA1E7",
    "amount": "100.00",
    "net_amount": 94.00,
    "fee": 6.00,
    "expires_at": "2025-06-23T23:49:11Z",
    "customer": {
      "name": "Maria Silva Santos",
      "document": "12345678910",
      "email": "cliente@exemplo.com",
      "phone": "5511987654321"
    },
    "status": "paid"
  },
  "event_type": "payment_paid",
  "webhook_id": 123,
  "timestamp": 1640995200
}

Segurança dos webhooks

Cada notificação é assinada. Valide a assinatura antes de processar qualquer dado recebido.

Header Descrição Exemplo
X-VenturePay-Signature Assinatura HMAC SHA256 do payload. sha256=abc123...
X-VenturePay-Event Tipo do evento entregue. payment_paid
X-VenturePay-Webhook-Id Identificador do webhook. 123
X-VenturePay-Timestamp Timestamp Unix do envio. 1640995200
validar-webhook.php 
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_VENTUREPAY_SIGNATURE'];
$webhook_secret = 'seu-webhook-secret-aqui';

$expected = 'sha256=' . hash_hmac('sha256', $payload, $webhook_secret);

if (hash_equals($expected, $signature)) {
    // Webhook válido — processar dados
    $data = json_decode($payload, true);

    if ($data['event_type'] === 'payment_paid') {
        $transaction_id = $data['data']['transaction_id'];
        // Atualize o status no seu banco de dados
    }

    http_response_code(200);
} else {
    // Assinatura inválida — rejeitar
    http_response_code(401);
    exit('Unauthorized');
}

Checklist de integração

Valide a assinatura HMAC antes de processar.
Implemente lógica idempotente por evento.
Confirme status: paid antes de liberar o produto.
Receba webhooks somente por HTTPS.
Responda 200 para confirmar o recebimento.
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 OKRequisição processada com sucesso.
400 Bad RequestDados inválidos ou campos obrigatórios ausentes.
401 UnauthorizedAssinatura inválida ou token inexistente.
404 Not FoundRecurso não encontrado.
429 Too Many RequestsRate limit excedido.
500 Server ErrorErro interno do servidor.

Códigos de erro comuns

INVALID_SIGNATUREAssinatura HMAC inválida.
MISSING_FIELDCampo obrigatório não enviado.
INVALID_CPFCPF inválido ou malformado.
INVALID_EMAILE-mail inválido.
AMOUNT_TOO_LOWValor mínimo é R$ 1,00.
TRANSACTION_NOT_FOUNDID 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'])
Suporte técnico

Precisa de ajuda na integração?

Nosso time de desenvolvedores acompanha sua implementação de ponta a ponta, do sandbox ao primeiro pagamento em produção.

Falar com o suporte Central de ajuda
Copiado para a área de transferência