Documentação da API

Bem-vindo à documentação oficial da Vexpay. Nossa API RESTful permite que você integre pagamentos instantâneos, gerencie carteiras e realize splits financeiros de forma simples e segura.

Base URL (Produção)
https://app.vexpay.com.br/v2

Todas as requisições devem ser feitas via HTTPS. Requisições HTTP inseguras serão rejeitadas.

Autenticação

A segurança da API utiliza o padrão OAuth 2.0 Client Credentials. Isso significa que você precisa trocar suas credenciais fixas (`Client ID` e `Client Secret`) por um `access_token` temporário.

Atenção: Nunca exponha seu Client Secret no Frontend (HTML/JS). Esta chamada deve ser feita sempre pelo seu Backend.

POST /oauth/token

Parâmetros (Header)

Campo	Valor	Descrição
Authorization	Basic ...	Base64 de `CLIENT_ID:CLIENT_SECRET`
Content-Type	application/json	Formato do corpo

curl -X POST https://app.vexpay.com.br/v2/oauth/token \
  -u "CLIENT_ID:CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"grant_type": "client_credentials"}'

$client = new GuzzleHttp\Client();
$response = $client->post('https://app.vexpay.com.br/v2/oauth/token', [
    'auth' => ['CLIENT_ID', 'CLIENT_SECRET'],
    'json' => ['grant_type' => 'client_credentials']
]);
$token = json_decode($response->getBody())->access_token;

const axios = require('axios');
const auth = Buffer.from('ID:SECRET').toString('base64');
const { data } = await axios.post('https://app.vexpay.com.br/v2/oauth/token', 
  { grant_type: 'client_credentials' },
  { headers: { Authorization: `Basic ${auth}` } }
);

import requests
from requests.auth import HTTPBasicAuth

res = requests.post('https://app.vexpay.com.br/v2/oauth/token',
    auth=HTTPBasicAuth('CLIENT_ID', 'CLIENT_SECRET'),
    json={'grant_type': 'client_credentials'})
token = res.json()['access_token']

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://app.vexpay.com.br/v2/oauth/token"))
    .header("Authorization", basicAuth("ID", "SECRET"))
    .POST(BodyPublishers.ofString("{\"grant_type\":\"client_credentials\"}"))
    .build();

Resposta de Sucesso

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJ...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "*"
}
                    

Criar Cobrança (Pix In)

Gera um QR Code dinâmico (Copia e Cola) para recebimento imediato. Ideal para checkouts de e-commerce e depósitos em carteira.

POST /pix/qrcode

Parâmetros do Corpo (JSON)

Campo	Tipo	Regra	Descrição
`amount`	Float	Obrigatório	Valor da transação. Ex: `150.50`
`payer`	Objeto	Obrigatório	Dados do pagador. Contém `name` e `document` (CPF/CNPJ).
`external_id`	String	Opcional	Seu ID de controle (ex: ID do pedido no seu banco). Usado para idempotência.
`postbackUrl`	String	Recomendado	URL onde você receberá o Webhook de confirmação. Se não enviado, usa a URL padrão do painel.

curl -X POST https://app.vexpay.com.br/v2/pix/qrcode \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 150.00,
    "external_id": "PEDIDO_123",
    "payer": { "name": "Carlos", "document": "12345678900" },
    "postbackUrl": "https://seu-site.com/webhook"
  }'

$response = $client->post('https://app.vexpay.com.br/v2/pix/qrcode', [
    'headers' => ['Authorization' => 'Bearer ' . $token],
    'json' => [
        'amount' => 150.00,
        'external_id' => 'PEDIDO_123',
        'payer' => ['name' => 'Carlos', 'document' => '12345678900'],
        'postbackUrl' => 'https://seu-site.com/webhook'
    ]
]);

const res = await axios.post('https://app.vexpay.com.br/v2/pix/qrcode', {
    amount: 150.00,
    external_id: 'PEDIDO_123',
    payer: { name: 'Carlos', document: '12345678900' },
    postbackUrl: 'https://seu-site.com/webhook'
}, { headers: { Authorization: `Bearer ${token}` } });

payload = {
    'amount': 150.00,
    'external_id': 'PEDIDO_123',
    'payer': {'name': 'Carlos', 'document': '12345678900'},
    'postbackUrl': 'https://seu-site.com/webhook'
}
res = requests.post('https://app.vexpay.com.br/v2/pix/qrcode', json=payload, headers=headers)

// Usando Jackson ou Gson para montar o JSON...

Resposta (201 Created)

{
  "success": true,
  "transactionId": "e0281273-...",
  "qrcode": "00020126580014br.gov.bcb.pix0136123e4567-e89b-12d3-a456-426614174000...",
  "imagemQrcode": "https://chart.googleapis.com/...",
  "status": "PENDING"
}
                    

Split de Pagamento (Marketplace)

O recurso de Split permite dividir o valor de uma venda entre múltiplos recebedores no momento exato do pagamento. Isso é fundamental para Marketplaces.

Basta adicionar o array split no payload de criação do Pix.

O Split é processado instantaneamente. O saldo cai direto na conta do recebedor (identificado pelo e-mail).

Estrutura do Objeto Split

Campo	Tipo	Descrição
`email`	String	E-mail do parceiro cadastrado na Vexpay.
`percentage`	Int	Porcentagem do valor total (ex: `10` para 10%).
`fixed_amount`	Float	Valor fixo em reais (ex: `5.00`).

curl -X POST https://app.vexpay.com.br/v2/pix/qrcode \
  -H "Authorization: Bearer {TOKEN}" \
  -d '{
    "amount": 100.00,
    "payer": { ... },
    "split": [
      { "email": "parceiro@loja.com", "percentage": 10 },
      { "email": "marketing@agencia.com", "fixed_amount": 5.00 }
    ]
  }'

// Adicione o array 'split' no payload
'split' => [
    ['email' => 'parceiro@loja.com', 'percentage' => 10], // 10%
    ['email' => 'dev@sistema.com', 'fixed_amount' => 5.00] // R$ 5,00 fixo
]

split: [
  { email: 'parceiro@loja.com', percentage: 10 },
  { email: 'dev@sistema.com', fixed_amount: 5.00 }
]

'split': [
    {'email': 'parceiro@loja.com', 'percentage': 10},
    {'email': 'dev@sistema.com', 'fixed_amount': 5.0}
]

// Configure o objeto Split no Builder

Webhooks (Notificações)

Não fique consultando o status a todo momento (Polling). Use Webhooks para ser notificado assim que o pagamento for confirmado.

Enviaremos uma requisição POST para a postbackUrl informada na criação da cobrança.

Payload Recebido

{
  "event": "pix.received",
  "data": {
    "transactionId": "e0281273-9812...",
    "external_id": "PEDIDO_123",
    "amount": 150.00,
    "status": "PAID",
    "paid_at": "2026-01-28 15:30:00"
  }
}
                    

Como processar (Exemplo Seguro)

// Exemplo do JSON que você vai receber no seu POST

$json = file_get_contents('php://input');
$data = json_decode($json, true);

if ($data['status'] === 'PAID') {
    // Liberar pedido ID: $data['external_id']
    http_response_code(200);
}

app.post('/webhook', (req, res) => {
    const { status, external_id } = req.body;
    
    if (status === 'PAID') {
        console.log(`Pedido ${external_id} pago!`);
    }
    res.sendStatus(200);
});

@app.route('/webhook', methods=['POST'])
def webhook():
    data = request.json
    if data['status'] == 'PAID':
        # Processar pagamento
    return 'OK', 200

// No seu Controller Spring Boot

Importante: Seu servidor deve responder com Status Code 200 ou 201. Caso contrário, tentaremos reenviar a notificação até 5 vezes.

Respostas e Erros

Utilizamos códigos HTTP convencionais para indicar sucesso ou falha.

Código	Status	Significado
200	OK	Sucesso padrão.
201	Created	Recurso criado (ex: QR Code gerado).
400	Bad Request	Erro nos dados enviados (ex: CPF inválido).
401	Unauthorized	Token inválido ou expirado.
403	Forbidden	Sua conta não tem permissão para esta ação.
422	Unprocessable	Erro de validação de negócio (ex: Saldo insuficiente).
500	Server Error	Erro interno. Tente novamente mais tarde.