Documentação da API

Bem-vindo ao Developer Hub da VexPay. Nossa API foi construída para permitir integração rápida e segura de pagamentos Pix, Splits e Cashouts em qualquer plataforma.

vpn_keyAutenticação

A autenticação é feita via Bearer Token usando sua Secret Key (live_sk_...). Você pode gerar suas chaves na página de configurações.

Todas as requisições devem incluir o header de autorização. Requisições sem autenticação ou com token inválido retornarão erro 401 Unauthorized.

qr_code_2Criar Cobrança (Pix In)

Gera um QR Code dinâmico para recebimento de pagamentos via Pix. O QR Code gerado é válido por 24 horas e pode ser pago uma única vez.

Parâmetros (JSON)

curl -X POST https://app.vexpay.com.br/api/pix_in \
  -H "Authorization: Bearer live_sk_SUA_CHAVE_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50.00,
    "external_id": "PEDIDO_1001",
    "postbackUrl": "https://seu-site.com/webhook/vexpay",
    "payer": { "name": "João Silva", "document": "12345678900" }
  }'

Resposta de Sucesso

{
  "transactionId": "uuid-da-transacao",
  "external_id": "PEDIDO_1001",
  "amount": 50.00,
  "qrcode": "00020126580014br.gov.bcb.pix...",
  "qrcode_base64": "data:image/png;base64,...",
  "status": "PENDING",
  "expires_at": "2026-02-17T12:00:00Z"
}

sendRealizar Saque (Pix Out)

Realiza transferência Pix para uma chave de destino. O valor é debitado do seu saldo disponível na plataforma.

Parâmetros (JSON)

curl -X POST https://app.vexpay.com.br/api/pix_out \
  -H "Authorization: Bearer live_sk_SUA_CHAVE_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 150.00,
    "external_id": "SAQUE_REF_55",
    "pin": "1234",
    "creditParty": {
        "name": "Maria Recebedora",
        "key": "maria@email.com",
        "keyType": "EMAIL"
    }
  }'

Resposta de Sucesso

{
  "transactionId": "uuid-do-saque",
  "external_id": "SAQUE_REF_55",
  "amount": 150.00,
  "status": "PROCESSING",
  "message": "Saque enviado para processamento"
}

call_splitSplit de Pagamentos

O sistema de Split permite dividir automaticamente o valor de uma transação entre múltiplos recebedores quando o pagamento é confirmado. Ideal para marketplaces, afiliados, franquias e parcerias.

Parâmetros de Split (JSON)

* O email é obrigatório na criação. Após processamento, o sistema preenche automaticamentecalculated_amount e recipient_id.

Exemplo: Marketplace

Dividir 80% para o vendedor e 20% para a plataforma:

curl -X POST https://app.vexpay.com.br/api/pix_in \
  -H "Authorization: Bearer live_sk_SUA_CHAVE_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1000.00,
    "external_id": "PEDIDO_123",
    "postbackUrl": "https://seu-site.com/webhook/vexpay",
    "split_rules": [
      {
        "email": "parceiro@email.com",
        "percentage": 30
      },
      {
        "email": "outro@email.com",
        "percentage": 20
      }
    ],
    "payer": {
      "name": "João Cliente",
      "document": "12345678900"
    }
  }'

Como o Valor é Calculado

O valor do split é calculado sobre o valor líquido (após taxas):

Exemplo de Cálculo

Valor pago: R$ 1.000,00
Taxa cobrada: R$ 50,00
Valor líquido: R$ 950,00
Porcentagem: 30%
─────────────────────────
Valor do split: R$ 285,00 (30% de R$ 950,00)

Processamento Automático

O split é processado automaticamente quando o pagamento é confirmado via webhook. Você não precisa fazer nada adicional:

1. Pagamento é confirmado
2. VexPay processa o split automaticamente
3. Valores são debitados/creditados nas contas
4. Recebedores recebem notificações

Casos de Uso

Requisitos

• Os recebedores devem ter contas cadastradas no VexPay
• Os emails informados devem estar corretos e ativos
• A porcentagem deve ser um número entre 0 e 100
• O split é processado apenas quando o pagamento é confirmado

notificationsWebhooks

Enviamos uma requisição POST para suapostbackUrl sempre que um pagamento for confirmado ou houver atualização de status.

Payload de Notificação

{
  "transactionId": "uuid-da-transacao",
  "external_id": "PEDIDO_1001",
  "amount": 50.00,
  "status": "PAID",
  "paid_at": "2026-02-16T12:30:00Z",
  "payer": {
    "name": "João Silva",
    "document": "***456789**"
  }
}

Validando o Webhook

Recomendamos que você valide todas as notificações recebidas consultando o status da transação via API antes de liberar o produto/serviço.

errorErros & Status

A API utiliza códigos HTTP padrão para indicar sucesso ou falha das requisições.

Códigos de Status HTTP

Status de Transação