VexusPayDocumentação oficial
API operacional Entrar
VEXUS PUBLIC API · 2026-08-17

Integre pagamentos com uma API clara e previsível.

Integração HTTPS/JSON para os produtos publicados. Esta especificação descreve somente contratos disponíveis no domínio atual; recursos não publicados aparecem na matriz de disponibilidade e não devem ser inferidos.

Começar integração Baixar Postman
Base URL de produçãohttps://api.avalonpay.com.br
01

HTTPS + JSON

Contratos simples, respostas estruturadas e exemplos prontos para o backend.

02

Idempotência

Repetições seguras nas operações financeiras sem duplicar movimentações.

03

Webhooks assinados

Entrega autenticada e retentativas com identificador estável.

Fundamentos

Autenticação

As rotas privadas usam duas credenciais enviadas somente pelo seu servidor. Nunca exponha o Client Secret no navegador, aplicativo móvel ou repositório.

Headers obrigatórios
Apikey: SEU_CLIENT_ID
X-Client-Secret: SEU_CLIENT_SECRET
Content-Type: application/json
Confiabilidade

Idempotência

Use de 8 a 100 caracteres e repita a mesma chave somente ao repetir exatamente o mesmo corpo. Corpo divergente com a mesma chave retorna conflito.

Regra importanteUse a mesma chave apenas quando estiver repetindo exatamente o mesmo corpo da requisição.
Criptomoedas

Fluxo de carteira, depósito e envio

A API cripto usa as mesmas credenciais servidor-a-servidor. Consulte o catálogo antes de operar: ele é a fonte de verdade para moedas, redes, confirmações e disponibilidade de entrada ou saída.

01

Crie a carteira

Liste /api/v1/crypto/assets e envie o par asset/network para /api/v1/crypto/wallets. A criação é idempotente por conta, moeda e rede.

02

Receba automaticamente

Consulte o endereço da carteira. A VexusPay monitora a blockchain, aguarda as confirmações da rede e credita o ledger sem ação manual.

03

Envie automaticamente

Calcule o preview, confirme com a mesma cotação e uma Idempotency-Key. Reserva, assinatura KMS, transmissão e confirmação continuam em segundo plano.

Valores e segurançaEnvie valores cripto como string decimal na unidade do ativo. No painel o usuário confirma com PIN; na API, o Client Secret e o escopo cashout autenticam o servidor integrador. Nunca coloque essas credenciais no frontend.
Acompanhe o resultadoConsulte /api/v1/crypto/withdrawals/{withdrawalId} até o estado terminal e use /api/v1/crypto/transactions para conciliação. Repetições devem preservar corpo e chave de idempotência.
Eventos

Webhooks

Valide a assinatura usando o corpo bruto recebido antes de interpretar o JSON. Respostas 2xx confirmam a entrega.

Headers de entrega
X-Vexus-Event: checkout.order.status_changed
X-Vexus-Delivery: <uuid>
X-Vexus-Timestamp: <unix_timestamp>
X-Vexus-Signature: v1=<hmac_sha256>
Referência completa

Endpoints publicados

Os exemplos abaixo são derivados do mesmo contrato que gera o OpenAPI e a coleção Postman.

Módulo

Status

Disponibilidade técnica sem autenticação.

GET /health/live Público

Liveness

Verifica se o processo HTTP está ativo.

cURL
curl -X GET 'https://api.avalonpay.com.br/health/live'
GET /health/ready Público

Readiness

Valida banco, migrações e dependências internas necessárias para receber tráfego.

cURL
curl -X GET 'https://api.avalonpay.com.br/health/ready'
Módulo

PIX

Entrada, saída, leitura e pagamento de QR Code PIX.

POST /api/v1/cashin Credenciais

Criar cobrança PIX

Cria uma cobrança PIX dinâmica.

Exige Idempotency-Key.
cURL
curl -X POST 'https://api.avalonpay.com.br/api/v1/cashin' \
  -H 'Apikey: SEU_CLIENT_ID' \
  -H 'X-Client-Secret: SEU_CLIENT_SECRET' \
  -H 'Idempotency-Key: pedido-1024-tentativa-1' \
  -H 'Content-Type: application/json' \
  --data '{
    "amount": 25.9,
    "payer_name": "Cliente de Exemplo",
    "payer_document": "52998224725",
    "payer_email": "cliente@example.com",
    "description": "Pedido 1024",
    "external_id": "pedido-1024"
}'
Ver corpo de exemplo 
{
    "amount": 25.9,
    "payer_name": "Cliente de Exemplo",
    "payer_document": "52998224725",
    "payer_email": "cliente@example.com",
    "description": "Pedido 1024",
    "external_id": "pedido-1024"
}
POST /api/v1/cashout Credenciais

Enviar PIX

Envia um PIX para a chave informada, sujeito a saldo, produto e limites da conta.

Exige Idempotency-Key.
cURL
curl -X POST 'https://api.avalonpay.com.br/api/v1/cashout' \
  -H 'Apikey: SEU_CLIENT_ID' \
  -H 'X-Client-Secret: SEU_CLIENT_SECRET' \
  -H 'Idempotency-Key: pedido-1024-tentativa-1' \
  -H 'Content-Type: application/json' \
  --data '{
    "amount": 20,
    "pix_key": "<chave-pix-destino>",
    "pix_key_type": "random",
    "description": "Repasse"
}'
Ver corpo de exemplo 
{
    "amount": 20,
    "pix_key": "<chave-pix-destino>",
    "pix_key_type": "random",
    "description": "Repasse"
}
POST /api/v1/pix/qr/decode Credenciais

Ler QR Code PIX

Valida e decodifica um payload EMV PIX sem movimentar saldo.

cURL
curl -X POST 'https://api.avalonpay.com.br/api/v1/pix/qr/decode' \
  -H 'Apikey: SEU_CLIENT_ID' \
  -H 'X-Client-Secret: SEU_CLIENT_SECRET' \
  -H 'Content-Type: application/json' \
  --data '{
    "payload": "00020101021226810014br.gov.bcb.pix2559https://example.invalid/pix/cobranca-exemplo520400005303986540539.905802BR5905VEXUS6009SAO PAULO62070503***6304ABCD"
}'
Ver corpo de exemplo 
{
    "payload": "00020101021226810014br.gov.bcb.pix2559https://example.invalid/pix/cobranca-exemplo520400005303986540539.905802BR5905VEXUS6009SAO PAULO62070503***6304ABCD"
}
POST /api/v1/pix/qr/pay Credenciais

Pagar QR Code PIX

Paga um QR Code PIX após validação do payload e dos limites.

Exige Idempotency-Key.
cURL
curl -X POST 'https://api.avalonpay.com.br/api/v1/pix/qr/pay' \
  -H 'Apikey: SEU_CLIENT_ID' \
  -H 'X-Client-Secret: SEU_CLIENT_SECRET' \
  -H 'Idempotency-Key: pedido-1024-tentativa-1' \
  -H 'Content-Type: application/json' \
  --data '{
    "payload": "00020101021226810014br.gov.bcb.pix2559https://example.invalid/pix/cobranca-exemplo520400005303986540539.905802BR5905VEXUS6009SAO PAULO62070503***6304ABCD",
    "amount": 39.9,
    "description": "Fornecedor"
}'
Ver corpo de exemplo 
{
    "payload": "00020101021226810014br.gov.bcb.pix2559https://example.invalid/pix/cobranca-exemplo520400005303986540539.905802BR5905VEXUS6009SAO PAULO62070503***6304ABCD",
    "amount": 39.9,
    "description": "Fornecedor"
}
Módulo

Boleto

Emissão, consulta e pagamento de boleto.

POST /api/v1/boleto/issue Credenciais

Emitir boleto

Emite uma cobrança por boleto para um produto habilitado.

Exige Idempotency-Key.
cURL
curl -X POST 'https://api.avalonpay.com.br/api/v1/boleto/issue' \
  -H 'Apikey: SEU_CLIENT_ID' \
  -H 'X-Client-Secret: SEU_CLIENT_SECRET' \
  -H 'Idempotency-Key: pedido-1024-tentativa-1' \
  -H 'Content-Type: application/json' \
  --data '{
    "product_id": "00000000-0000-4000-8000-000000000001",
    "amount": 99.9,
    "buyer_name": "Cliente de Exemplo",
    "buyer_email": "cliente@example.com",
    "buyer_cpf": "52998224725",
    "buyer_address": {
        "zip_code": "01001000",
        "street_name": "Praça da Sé",
        "street_number": "100",
        "neighborhood": "Sé",
        "city": "São Paulo",
        "state": "SP"
    }
}'
Ver corpo de exemplo 
{
    "product_id": "00000000-0000-4000-8000-000000000001",
    "amount": 99.9,
    "buyer_name": "Cliente de Exemplo",
    "buyer_email": "cliente@example.com",
    "buyer_cpf": "52998224725",
    "buyer_address": {
        "zip_code": "01001000",
        "street_name": "Praça da Sé",
        "street_number": "100",
        "neighborhood": "Sé",
        "city": "São Paulo",
        "state": "SP"
    }
}
POST /api/v1/boleto/info Credenciais

Consultar boleto

Consulta os dados de um boleto sem movimentar saldo.

cURL
curl -X POST 'https://api.avalonpay.com.br/api/v1/boleto/info' \
  -H 'Apikey: SEU_CLIENT_ID' \
  -H 'X-Client-Secret: SEU_CLIENT_SECRET' \
  -H 'Content-Type: application/json' \
  --data '{
    "billetCode": "00000000000000000000000000000000000000000000"
}'
Ver corpo de exemplo 
{
    "billetCode": "00000000000000000000000000000000000000000000"
}
POST /api/v1/boleto/pay Credenciais

Pagar boleto

Paga um boleto após a aplicação validar código, beneficiário, saldo e limites.

Exige Idempotency-Key.
cURL
curl -X POST 'https://api.avalonpay.com.br/api/v1/boleto/pay' \
  -H 'Apikey: SEU_CLIENT_ID' \
  -H 'X-Client-Secret: SEU_CLIENT_SECRET' \
  -H 'Idempotency-Key: pedido-1024-tentativa-1' \
  -H 'Content-Type: application/json' \
  --data '{
    "billetCode": "00000000000000000000000000000000000000000000",
    "amount": 149.9,
    "beneficiary_name": "Empresa de Exemplo"
}'
Ver corpo de exemplo 
{
    "billetCode": "00000000000000000000000000000000000000000000",
    "amount": 149.9,
    "beneficiary_name": "Empresa de Exemplo"
}
Módulo

Cripto

Catálogo, carteiras, endereços, saldos, histórico e envios on-chain.

GET /api/v1/crypto/assets Credenciais

Listar ativos cripto

Retorna somente moedas e redes habilitadas em produção, incluindo capacidade de depósito, envio, casas decimais, confirmações e ícone.

cURL
curl -X GET 'https://api.avalonpay.com.br/api/v1/crypto/assets' \
  -H 'Apikey: SEU_CLIENT_ID' \
  -H 'X-Client-Secret: SEU_CLIENT_SECRET'
GET /api/v1/crypto/wallets Credenciais

Listar carteiras cripto

Retorna as carteiras da conta, saldo disponível/bloqueado, rede, ativo e disponibilidade de envio.

cURL
curl -X GET 'https://api.avalonpay.com.br/api/v1/crypto/wallets' \
  -H 'Apikey: SEU_CLIENT_ID' \
  -H 'X-Client-Secret: SEU_CLIENT_SECRET'
POST /api/v1/crypto/wallets Credenciais

Criar ou obter carteira

Cria de forma idempotente uma carteira para o par ativo/rede. Chamadas repetidas retornam a mesma carteira e o monitoramento automático já fica ativo.

cURL
curl -X POST 'https://api.avalonpay.com.br/api/v1/crypto/wallets' \
  -H 'Apikey: SEU_CLIENT_ID' \
  -H 'X-Client-Secret: SEU_CLIENT_SECRET' \
  -H 'Content-Type: application/json' \
  --data '{
    "asset": "USDT",
    "network": "BSC_BNB"
}'
Ver corpo de exemplo 
{
    "asset": "USDT",
    "network": "BSC_BNB"
}
GET /api/v1/crypto/wallets/{walletId}/address Credenciais

Consultar endereço de recebimento

Revela o endereço e, quando aplicável, memo/tag. Depósitos são detectados, confirmados e creditados automaticamente.

cURL
curl -X GET 'https://api.avalonpay.com.br/api/v1/crypto/wallets/{walletId}/address' \
  -H 'Apikey: SEU_CLIENT_ID' \
  -H 'X-Client-Secret: SEU_CLIENT_SECRET'
GET /api/v1/crypto/transactions Credenciais

Listar movimentações cripto

Lista depósitos e envios da conta, com status, confirmações, valores, taxas e hash blockchain quando disponível.

cURL
curl -X GET 'https://api.avalonpay.com.br/api/v1/crypto/transactions' \
  -H 'Apikey: SEU_CLIENT_ID' \
  -H 'X-Client-Secret: SEU_CLIENT_SECRET'
POST /api/v1/crypto/withdrawals/preview Credenciais

Calcular envio cripto

Valida destino e saldo e retorna uma cotação de 60 segundos com taxa de rede, taxa VexusPay e débito total. Não movimenta saldo.

cURL
curl -X POST 'https://api.avalonpay.com.br/api/v1/crypto/withdrawals/preview' \
  -H 'Apikey: SEU_CLIENT_ID' \
  -H 'X-Client-Secret: SEU_CLIENT_SECRET' \
  -H 'Content-Type: application/json' \
  --data '{
    "wallet_id": "00000000-0000-4000-8000-000000000001",
    "amount": "1.00",
    "destination": "0x1111111111111111111111111111111111111111"
}'
Ver corpo de exemplo 
{
    "wallet_id": "00000000-0000-4000-8000-000000000001",
    "amount": "1.00",
    "destination": "0x1111111111111111111111111111111111111111"
}
POST /api/v1/crypto/withdrawals Credenciais

Confirmar envio cripto

Confirma uma cotação válida. A reserva, assinatura local KMS, transmissão e confirmação blockchain seguem automaticamente. Nunca reenvie com outra chave enquanto o resultado estiver pendente.

Exige Idempotency-Key.
cURL
curl -X POST 'https://api.avalonpay.com.br/api/v1/crypto/withdrawals' \
  -H 'Apikey: SEU_CLIENT_ID' \
  -H 'X-Client-Secret: SEU_CLIENT_SECRET' \
  -H 'Idempotency-Key: pedido-1024-tentativa-1' \
  -H 'Content-Type: application/json' \
  --data '{
    "quote_id": "00000000-0000-4000-8000-000000000002",
    "destination": "0x1111111111111111111111111111111111111111"
}'
Ver corpo de exemplo 
{
    "quote_id": "00000000-0000-4000-8000-000000000002",
    "destination": "0x1111111111111111111111111111111111111111"
}
GET /api/v1/crypto/withdrawals/{withdrawalId} Credenciais

Consultar envio cripto

Retorna estado, hash blockchain, valores e taxas sem expor o endereço completo de destino.

cURL
curl -X GET 'https://api.avalonpay.com.br/api/v1/crypto/withdrawals/{withdrawalId}' \
  -H 'Apikey: SEU_CLIENT_ID' \
  -H 'X-Client-Secret: SEU_CLIENT_SECRET'
Módulo

Conta

Consulta de saldo conforme o produto habilitado.

POST /api/v1/balance Credenciais

Consultar saldo

Consulta o saldo exposto pelo contrato da conta. Envie um objeto JSON vazio.

cURL
curl -X POST 'https://api.avalonpay.com.br/api/v1/balance' \
  -H 'Apikey: SEU_CLIENT_ID' \
  -H 'X-Client-Secret: SEU_CLIENT_SECRET' \
  -H 'Content-Type: application/json' \
  --data '{}'
Ver corpo de exemplo 
{}
Módulo

Split

Regras, execução, consulta, cancelamento, devolução e relatório de Split Payment.

GET /api/v1/splits/rules Credenciais

Listar regras de split

Lista as regras pertencentes à conta autenticada.

cURL
curl -X GET 'https://api.avalonpay.com.br/api/v1/splits/rules' \
  -H 'Apikey: SEU_CLIENT_ID' \
  -H 'X-Client-Secret: SEU_CLIENT_SECRET'
POST /api/v1/splits/rules Credenciais

Criar regra de split

Cria uma regra versionada por percentuais ou valores fixos.

Exige Idempotency-Key.
cURL
curl -X POST 'https://api.avalonpay.com.br/api/v1/splits/rules' \
  -H 'Apikey: SEU_CLIENT_ID' \
  -H 'X-Client-Secret: SEU_CLIENT_SECRET' \
  -H 'Idempotency-Key: pedido-1024-tentativa-1' \
  -H 'Content-Type: application/json' \
  --data '{
    "name": "Parceiros",
    "mode": "PERCENTAGE",
    "currency": "BRL",
    "participants": [
        {
            "handle": "conta-parceira",
            "percentage": "20.00"
        }
    ]
}'
Ver corpo de exemplo 
{
    "name": "Parceiros",
    "mode": "PERCENTAGE",
    "currency": "BRL",
    "participants": [
        {
            "handle": "conta-parceira",
            "percentage": "20.00"
        }
    ]
}
PUT /api/v1/splits/rules/{ruleId} Credenciais

Revisar regra de split

Arquiva a versão anterior e cria uma nova versão da regra.

Exige Idempotency-Key.
cURL
curl -X PUT 'https://api.avalonpay.com.br/api/v1/splits/rules/{ruleId}' \
  -H 'Apikey: SEU_CLIENT_ID' \
  -H 'X-Client-Secret: SEU_CLIENT_SECRET' \
  -H 'Idempotency-Key: pedido-1024-tentativa-1' \
  -H 'Content-Type: application/json' \
  --data '{
    "name": "Parceiros v2",
    "mode": "PERCENTAGE",
    "currency": "BRL",
    "participants": [
        {
            "handle": "conta-parceira",
            "percentage": "25.00"
        }
    ]
}'
Ver corpo de exemplo 
{
    "name": "Parceiros v2",
    "mode": "PERCENTAGE",
    "currency": "BRL",
    "participants": [
        {
            "handle": "conta-parceira",
            "percentage": "25.00"
        }
    ]
}
DELETE /api/v1/splits/rules/{ruleId} Credenciais

Arquivar regra de split

Arquiva a regra da conta. Esta operação não aceita corpo.

cURL
curl -X DELETE 'https://api.avalonpay.com.br/api/v1/splits/rules/{ruleId}' \
  -H 'Apikey: SEU_CLIENT_ID' \
  -H 'X-Client-Secret: SEU_CLIENT_SECRET'
POST /api/v1/splits Credenciais

Criar split

Cria a operação financeira e suas alocações a partir de uma regra ativa.

Exige Idempotency-Key.
cURL
curl -X POST 'https://api.avalonpay.com.br/api/v1/splits' \
  -H 'Apikey: SEU_CLIENT_ID' \
  -H 'X-Client-Secret: SEU_CLIENT_SECRET' \
  -H 'Idempotency-Key: pedido-1024-tentativa-1' \
  -H 'Content-Type: application/json' \
  --data '{
    "rule_id": "00000000-0000-4000-8000-000000000001",
    "amount": 100,
    "payer": {
        "name": "Cliente de Exemplo",
        "document": "52998224725",
        "email": "cliente@example.com"
    }
}'
Ver corpo de exemplo 
{
    "rule_id": "00000000-0000-4000-8000-000000000001",
    "amount": 100,
    "payer": {
        "name": "Cliente de Exemplo",
        "document": "52998224725",
        "email": "cliente@example.com"
    }
}
GET /api/v1/splits/{splitId} Credenciais

Consultar split

Retorna a operação e as alocações visíveis à conta proprietária.

cURL
curl -X GET 'https://api.avalonpay.com.br/api/v1/splits/{splitId}' \
  -H 'Apikey: SEU_CLIENT_ID' \
  -H 'X-Client-Secret: SEU_CLIENT_SECRET'
POST /api/v1/splits/{splitId}/cancel Credenciais

Cancelar split

Cancela um split somente quando o estado financeiro permitir. Não aceita corpo.

cURL
curl -X POST 'https://api.avalonpay.com.br/api/v1/splits/{splitId}/cancel' \
  -H 'Apikey: SEU_CLIENT_ID' \
  -H 'X-Client-Secret: SEU_CLIENT_SECRET'
POST /api/v1/splits/{splitId}/refund Credenciais

Solicitar devolução do split

Solicita devolução parcial ou total; uma resposta 202 indica processamento assíncrono.

Exige Idempotency-Key.
cURL
curl -X POST 'https://api.avalonpay.com.br/api/v1/splits/{splitId}/refund' \
  -H 'Apikey: SEU_CLIENT_ID' \
  -H 'X-Client-Secret: SEU_CLIENT_SECRET' \
  -H 'Idempotency-Key: pedido-1024-tentativa-1' \
  -H 'Content-Type: application/json' \
  --data '{
    "amount": 25,
    "comment": "Devolução parcial solicitada pelo cliente"
}'
Ver corpo de exemplo 
{
    "amount": 25,
    "comment": "Devolução parcial solicitada pelo cliente"
}
GET /api/v1/splits/report Credenciais

Relatório de participante

Retorna itens da conta autenticada no intervalo UTC informado.

cURL
curl -X GET 'https://api.avalonpay.com.br/api/v1/splits/report' \
  -H 'Apikey: SEU_CLIENT_ID' \
  -H 'X-Client-Secret: SEU_CLIENT_SECRET'
Transparência

Disponibilidade

PIX cash-in/cash-out/QR PUBLISHED
Boleto issue/info/pay PUBLISHED
Crypto assets/wallets/deposits/withdrawals/history PUBLISHED
Split rules/create/get/cancel/refund/report PUBLISHED
Generic transaction query NOT_PUBLISHED
Direct card API NOT_PUBLISHED
Checkout management API NOT_PUBLISHED
Financial operation webhooks NOT_PUBLISHED
Public MED/dispute API NOT_PUBLISHED