Documentação API

Início Rápido

Integre pagamentos PIX em 3 passos simples.

1

Crie sua conta

Registre-se em vexopay.com.br/register

2

Gere suas API Keys

Vá em API Keys e gere suas credenciais

3

Integre

Use ci e cs nos headers das requisições

Autenticação

Todas as requisições exigem as credenciais nos headers:

// Headers obrigatórios
ci: vxp_ci_xxxxxxxxxxxxxxxx   // client_id
cs: vxp_cs_xxxxxxxxxxxxxxxx   // client_secret
Content-Type: application/json

Base URL

https://www.vexopay.com.br/api

Criar Cobrança PIX

POST /gateway/pix-create

Parâmetros (body JSON)

Campo	Tipo	Descrição
`amount` obrigatório	number	Valor em reais (mín: 2.00)
`payerName` obrigatório	string	Nome do pagador
`payerDocument` obrigatório	string	CPF (apenas números)
`description` opcional	string	Descrição da cobrança

curl -X POST https://www.vexopay.com.br/api/gateway/pix-create \ -H "Content-Type: application/json" \ -H "ci: vxp_ci_SEU_CLIENT_ID" \ -H "cs: vxp_cs_SEU_CLIENT_SECRET" \ -d '{ "amount": 50.00, "payerName": "João Silva", "payerDocument": "12345678909", "description": "Assinatura mensal" }'

const response = await fetch('https://www.vexopay.com.br/api/gateway/pix-create', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'ci': 'vxp_ci_SEU_CLIENT_ID',
    'cs': 'vxp_cs_SEU_CLIENT_SECRET',
  },
  body: JSON.stringify({
    amount: 50.00,
    payerName: 'João Silva',
    payerDocument: '12345678909',
    description: 'Assinatura mensal',
  }),
});

const data = await response.json();
console.log(data.data.qrCodeBase64);  // QR Code em Base64
console.log(data.data.copyPaste);      // Código copia e cola
console.log(data.data.paymentLink);    // Checkout hospedado (quando disponivel)

import requests response = requests.post( 'https://www.vexopay.com.br/api/gateway/pix-create', headers={ 'ci': 'vxp_ci_SEU_CLIENT_ID', 'cs': 'vxp_cs_SEU_CLIENT_SECRET', }, json={ 'amount': 50.00, 'payerName': 'João Silva', 'payerDocument': '12345678909', } ) data = response.json() print(data['data']['copyPaste']) # Código PIX

$ch = curl_init('https://www.vexopay.com.br/api/gateway/pix-create');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'ci: vxp_ci_SEU_CLIENT_ID',
        'cs: vxp_cs_SEU_CLIENT_SECRET',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'amount' => 50.00,
        'payerName' => 'João Silva',
        'payerDocument' => '12345678909',
    ]),
]);

$response = curl_exec($ch);
$data = json_decode($response, true);
echo $data['data']['copyPaste']; // Código PIX

Resposta (201)

{
  "success": true,
  "data": {
    "transactionId": "vxp_abc123def456...",
    "amount": 50.00,
    "fee": 1.50,
    "netAmount": 48.50,
    "status": "pending",
    "qrCodeBase64": "data:image/png;base64,...",
    "qrCodeUrl": "https://...",
    "copyPaste": "00020126...",
    "paymentLink": "https://...",
    "expiresAt": "2025-12-31T23:59:59Z"
  }
}

Consultar Status

GET /gateway/pix-status?transactionId=vxp_xxx

curl https://www.vexopay.com.br/api/gateway/pix-status?transactionId=vxp_abc123 \ -H "ci: vxp_ci_SEU_CLIENT_ID" \ -H "cs: vxp_cs_SEU_CLIENT_SECRET"

Resposta

{
  "success": true,
  "data": {
    "transactionId": "vxp_abc123...",
    "type": "pix_in",
    "amount": 50.00,
    "fee": 1.50,
    "netAmount": 48.50,
    "status": "paid",
    "payerName": "João Silva",
    "createdAt": "2025-01-15T14:30:00Z"
  }
}

Possíveis Status

Status	Descrição
`pending`	Aguardando pagamento
`paid`	Pagamento confirmado
`failed`	Pagamento falhou
`expired`	QR Code expirou
`refunded`	Pagamento estornado

Consultar Saldo

GET /gateway/balance

curl https://www.vexopay.com.br/api/gateway/balance \ -H "ci: vxp_ci_SEU_CLIENT_ID" \ -H "cs: vxp_cs_SEU_CLIENT_SECRET"

Resposta

{
  "success": true,
  "data": {
    "balance": 1250.00,
    "totalReceived": 5000.00,
    "totalWithdrawn": 3500.00,
    "totalFees": 250.00,
    "transactionsCount": 42,
    "currency": "BRL"
  }
}

Observação importante

Os campos payerName e payerDocument na criação do PIX não precisam ser verídicos. Eles servem apenas para preencher a cobrança. Os dados reais do pagador são capturados automaticamente após a confirmação do pagamento.

Solicitar Saque (Cash-out)

POST /merchant/cashout

Dois modos: sessão do painel (CSRF + PIN) ou server-to-server (ci/cs nos headers).

Parâmetros base

Campo	Tipo	Descrição
`withdrawalMethod` obrigatório	string	`PIX`, `INTERNAL` ou `CRYPTO`
`amount` obrigatório	number	Valor em reais
`description` opcional	string	Descrição da operação

PIX — parâmetros adicionais

Campo	Tipo	Descrição
`pixKeyType` obrigatório	string	`CPF`, `CNPJ`, `EMAIL`, `TELEFONE`, `CHAVE_ALEATORIA`
`pixKey` obrigatório	string	Chave PIX correspondente

INTERNAL — parâmetros adicionais

Campo	Tipo	Descrição
`targetAccount` obrigatório	string	Email, documento ou ID da conta destino

CRYPTO — parâmetros adicionais

Campo	Tipo	Descrição
`wallet` obrigatório	string	Carteira BEP20 (`0x` + 40 hex)

curl -X POST https://www.vexopay.com.br/api/merchant/cashout \ -H "Content-Type: application/json" \ -H "ci: vxp_ci_SEU_CLIENT_ID" \ -H "cs: vxp_cs_SEU_CLIENT_SECRET" \ -d '{ "withdrawalMethod": "PIX", "amount": 100.00, "pixKeyType": "CPF", "pixKey": "12345678909" }'

Regras

Tipo	Regras
`PIX`	Mínimo dinâmico: maior entre R$ 1,00 e (taxa fixa + R$ 0,01)
`INTERNAL`	Sem taxa. Liquidação imediata entre contas VexoPay
`CRYPTO`	Mínimo R$ 20 / Máximo R$ 3.000. Taxa plataforma + rede

Webhooks

Receba notificações em tempo real quando um pagamento for confirmado. Configure a URL no seu perfil.

Payload recebido

{
  "event": "payment.completed",
  "data": {
    "transactionId": "vxp_abc123...",
    "amount": 50.00,
    "fee": 1.50,
    "netAmount": 48.50,
    "status": "paid",
    "payerName": "João Silva",
    "paidAt": "2025-01-15T14:35:00Z"
  }
}

Eventos possíveis

Evento	Descrição
`payment.completed`	Pagamento confirmado
`payment.failed`	Pagamento falhou
`payment.expired`	QR Code expirou

Criar Cobrança Crypto

POST /gateway/crypto-create

Gera uma cobrança em USDT, USDC, BTC ou TRX com cotação Binance em tempo real.

Parâmetros (body JSON)

Campo	Tipo	Descrição
`amount` obrigatório	number	Valor em reais (mín R$ 5, máx R$ 50.000)
`network` obrigatório	string	`TRC20`, `USDC_TRC20`, `BTC` ou `TRX`
`description` opcional	string	Identificador interno (máx 120 chars)

Exemplo

curl -X POST https://www.vexopay.com.br/api/gateway/crypto-create \ -H "Content-Type: application/json" \ -H "ci: vxp_ci_xxxxx" \ -H "cs: vxp_cs_xxxxx" \ -d '{ "amount": 100.00, "network": "TRC20", "description": "Pedido #1234" }'

Resposta

{
  "success": true,
  "invoice": {
    "id": "5b3e...",
    "address": "TQPirdxgKdK2...",
    "amount": 18.180042,
    "amount_brl": 100.00,
    "fee_amount": 6.00,
    "net_amount": 94.00,
    "rate": 5.50,
    "asset": "USDT",
    "network": "TRC20",
    "expires_at": "2026-01-01T00:30:00Z",
    "status": "pending",
    "qr_payload": "tron:TQPir...?amount=18.180042&token=USDT"
  }
}

O cliente deve enviar exatamente o amount retornado (com os últimos decimais únicos). Esse "amount tagging" é como identificamos o pagamento no endereço compartilhado.

Status Cobrança Crypto

GET /gateway/crypto-status?id=<invoice_id>

Consulta o estado da cobrança. Recomendado fazer polling a cada 30s até receber paid.

Estados possíveis

Status	Significado
`pending`	Aguardando depósito na blockchain
`confirming`	Transação detectada, aguardando confirmações
`paid`	Confirmado e creditado no saldo do merchant
`expired`	30 min sem pagamento — invoice fechada

Exemplo

curl https://www.vexopay.com.br/api/gateway/crypto-status?id=5b3e... \ -H "ci: vxp_ci_xxxxx" \ -H "cs: vxp_cs_xxxxx"

Taxas Crypto

GET /merchant/crypto-fees

Retorna taxa de plataforma, taxa de rede e cotação de referência.

Resposta

{
  "success": true,
  "data": {
    "quote": {
      "brlPerUSD": 5.25,
      "networkFee": 3
    },
    "fees": {
      "platformFeePercentage": 3,
      "networkFee": 3
    }
  }
}

IP Whitelist

Restrinja o uso da API Key a IPs específicos. Configure na página API Keys.

Configuração	Comportamento
`Sem IPs`	Aceita de qualquer IP (padrão)
`Com IPs`	Aceita apenas dos IPs listados

IP bloqueado (403)

{ "error": "IP não autorizado (203.0.113.50)" }

Códigos de Erro

Referência de todos os códigos HTTP retornados pela API.

HTTP	Significado
`400`	Parâmetros inválidos ou ausentes
`401`	Credenciais (ci/cs) inválidas
`403`	Conta suspensa ou IP bloqueado
`404`	Recurso não encontrado
`409`	Conflito de estado
`428`	Reautenticação obrigatória (PIN)
`429`	Rate limit excedido
`500`	Erro interno do servidor
`502`	Erro com processador de pagamento