VexusPayDocumentação oficial
API operacional
PT EN ES
VEXUS PUBLIC API · 2026-09-15

Uma API financeira pronta para a sua próxima grande integração.

Conecte Pix, boleto, checkout, cripto, cartões e Split Payment com contratos estáveis, segurança e visibilidade em cada etapa.

Contrato OpenAPI Webhooks assinados Sandbox público e isolado
Ilustração da infraestrutura de pagamentos VexusPay
Base URL Sandbox — sem movimentação realhttps://sandbox-api.example.invalid
Ecossistema de APIs VexusPay para pagamentos, cartões, boleto, cripto e Split
Ambiente de testes

Contrato Sandbox isolado

Sandbox disponívelhttps://sandbox-api.vexuspay.com.br está público com DNS, TLS e health checks validados. Selecione Sandbox acima para apontar os exemplos ao ambiente isolado, que nunca movimenta valores reais.

Crie uma credencial marcada como Sandbox em Configurações → Credenciais. Ela começa com vx_sbx_, funciona somente no hostname Sandbox e nunca acessa saldo, carteiras, provedores ou webhooks de produção.

Comparação entre os ambientes Sandbox e Produção da VexusPay
01

Saldo fictício

O workspace inicia com R$ 100.000,00 fictícios. Use GET /api/v1/sandbox/workspace, o faucet e o reset para organizar seus testes.

02

Estados reais de integração

Crie a operação pela rota normal e use os Sandbox Controls para aprovar, falhar, expirar ou reverter sem liquidação financeira.

03

Webhooks separados

Endpoints, entregas, tentativas e assinaturas Sandbox não são compartilhados com Produção. O corpo de OTP fica criptografado no pipeline e é redigido na auditoria.

IdempotênciaSeu servidor cria um UUID ou outra chave de 8–100 caracteres para a intenção de operação e a envia em Idempotency-Key. O Sandbox usa a mesma chave por credencial, método, path e corpo; repetir o corpo devolve o resultado lógico e trocar o corpo retorna conflito.
Cenários de erroSomente no Sandbox, envie X-Vexus-Sandbox-Scenario com success, insufficient_balance, provider_timeout, rate_limited, declined, expired ou webhook_retry. A Produção rejeita esse header.
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.

Fluxo de autenticação segura entre o backend e a API VexusPay
Headers obrigatórios
Apikey: SEU_CLIENT_ID
X-Client-Secret: SEU_CLIENT_SECRET
Content-Type: application/json
01

Crie a credencial

No painel, abra Configurações → Credenciais, escolha o ambiente e os menores escopos necessários. O Client Secret aparece somente na criação ou rotação: armazene-o imediatamente em um cofre.

02

Habilite o produto

Escopo e produto são verificações independentes. Cada rota abaixo informa ambos; uma credencial com o escopo correto ainda recebe 403 se o produto da conta estiver desabilitado.

03

Restrinja a origem

Quando usar a allowlist opcional, cadastre o IP público de saída do seu backend. Nunca tente autenticar diretamente do navegador ou do aplicativo móvel.

PIN é controle do painelO PIN de 6 dígitos apenas autoriza ações administrativas no painel, como criar a credencial. Nunca o envie à aplicação integradora, à IA, ao navegador ou em chamadas da API. O backend usa somente Apikey e X-Client-Secret.
Titularidade da integraçãoNome e domínio da credencial não mudam a conta à qual ela pertence. Em produção, use uma conta exclusiva do negócio ou formalize explicitamente o compartilhamento da conta titular; produtos, saldo, limites, taxas, operações e callbacks são isolados por conta e credencial.
Rotação e resposta de erroRotacionar invalida imediatamente o segredo anterior. Use 401 para revisar credencial/ambiente e 403 para revisar conta ativa, produto, escopo, IP permitido ou restrição de User-Agent. Não envie credenciais em ticket, chat, URL ou log.
Confiabilidade

Idempotência

Use de 8 a 100 caracteres e repita a mesma chave somente para o mesmo método, URL e conteúdo. Se não houver resposta conclusiva, consulte a intenção por operation + Idempotency-Key antes de qualquer nova tentativa financeira. No upload multipart, preserve os mesmos bytes e metadados do arquivo; conteúdo divergente retorna conflito. A Idempotency-Key é criada pelo seu próprio servidor antes de chamar uma rota que exige a chave; a VexusPay não a entrega nem a busca no painel.

1

Gere uma chave única

Use um UUID aleatório para uma intenção de operação, por exemplo uma emissão ou uma recarga.

2

Envie no header

Inclua Idempotency-Key junto das credenciais e do JSON da operação.

3

Consulte a intenção

Sem resposta conclusiva, use GET /api/v1/account/operations/by-idempotency/{idempotencyKey}?operation=... com a mesma credencial e repita o contexto de custódia cripto ou de usuário externo do cartão quando aplicável.

4

Nova intenção, nova chave

Só gere uma nova chave depois de confirmar que a intenção anterior terminou ou falhou definitivamente.

Gere no backend e mantenha para um retry
// Node.js
const idempotencyKey = crypto.randomUUID();

// PHP
$idempotencyKey = bin2hex(random_bytes(16));

# Python
idempotency_key = str(uuid.uuid4())

Idempotency-Key: <idempotencyKey>
Regra importanteUse a mesma chave apenas para a mesma intenção. Após timeout sem resposta, consulte pela chave original; se reconciliation_required=true, mantenha a operação em revisão e não repita a movimentação. Nunca reutilize uma chave antiga para uma nova cobrança, recarga, congelamento ou cancelamento.
Confiabilidade

Erros e retentativas

Erros JSON retornam statusCode, message e error com code, details, correlationId e retryable. Registre o correlationId, nunca as credenciais ou o corpo sensível.

4xx

Corrija ou consulte o estado

400/413/415/422 indicam request inválido. 401/403 indicam autenticação ou autorização. 404 também protege o isolamento entre contas. 409 exige consultar o recurso ou preservar a intenção original.

429

Respeite o Retry-After

Pause pelo tempo informado em Retry-After e aplique backoff exponencial com jitter. Não gere outra intenção nem outra Idempotency-Key.

5xx

Falha fechada

Em timeout, 500, 502, 503 ou 504, não presuma falha nem sucesso financeiro. Consulte pela Idempotency-Key original antes de qualquer nova POST; se o estado continuar inconclusivo, mantenha em revisão e acione o suporte com o correlationId. Um timeout gerado antes da aplicação pode não conter o envelope JSON.

Estados assíncronos201 e 202 confirmam criação ou admissão, não liquidação, PIX concluído ou confirmação blockchain. Persista os IDs retornados. Em cripto e no ciclo financeiro do cartão virtual, acompanhe pelas rotas GET: não existe webhook público de ciclo de vida para esses dois módulos. O único webhook público de cartão virtual é o de OTP.
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/networks e /api/v1/crypto/assets, depois envie network para /api/v1/crypto/wallets. A criação é idempotente por conta 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

Crie uma cotação, execute com uma nova Idempotency-Key da mesma intenção e acompanhe o ID retornado. Reserva, transmissão e confirmação continuam em segundo plano.

Valores, taxas e segurançaEnvie campos *_units e *_minor como strings inteiras na menor unidade, nunca como float. Em saques NET, taxas podem aumentar o débito; em GROSS, elas são descontadas do teto autorizado. Nunca presuma gás patrocinado: use os componentes e a validade retornados pela cotação. O Client Secret fica somente no backend.
Usuários de uma White LabelNa custódia individual, envie X-Vexus-Custody-Subject com o identificador interno, opaco, estável e imutável do seu usuário — nunca e-mail, telefone ou documento. O runtime aceita de 1 a 64 caracteres; para novas integrações, prefira pelo menos 8. Para a custódia central da própria White Label, envie somente X-Vexus-Custody-Access: CENTRAL. Os dois modos são mutuamente exclusivos.
Transferência interna White LabelEm POST /api/v1/crypto/internal-transfers, envie exatamente um destinatário. Prefira recipient_custody_subject: ele precisa apontar para um subject ACTIVE já existente na mesma White Label e nunca é criado automaticamente por essa rota. recipient_external_user_id permanece apenas como compatibilidade legada.
Swap e conversãoCote swaps em /api/v1/crypto/swaps/quote e execute em /api/v1/crypto/swaps, usando apenas pares retornados pelo catálogo. BRL → cripto exige endereço externo e capacidade liberada em /api/v1/crypto/conversions/capabilities. Cripto → BRL está em manutenção: não envie novas cotações ou confirmações nessa direção.
Acompanhe o resultado por pollingRespostas 201/202 não confirmam blockchain nem liquidação. Consulte o recurso pelo ID até estado terminal; não há webhook público de ciclo de vida cripto. Após timeout, use a recuperação unificada com a operação original (wallet.create, withdrawal.quote, withdrawal.execute, swap.quote, swap.execute, transfer.internal, conversion.address, conversion.quote ou conversion.confirm) e preserve corpo e Idempotency-Key.
CANAL OPERACIONAL

Central de suporte via API

Somente produção

A Central de Suporte conecta o backend de qualquer conta VexusPay habilitada à fila de atendimento. Ela pode ser incorporada ao painel ou sistema próprio do cliente usando as credenciais API da conta e, hoje, está disponível somente em https://api.vexuspay.com.br.

Quem pode integrarQualquer conta ativa pode integrar. O produto support e o escopo support.manage são habilitados por padrão; a API ainda valida ambos em cada chamada.

Fluxo API + webhook

  1. 1Conta envia e abreSe houver imagens, envie-as primeiro por multipart; depois POST /api/v1/support/tickets vincula os IDs e cria o protocolo.
  2. 2VexusPay atendeA equipe assume, responde e altera o estado para aguardar o cliente.
  3. 3Webhook atualizaO backend valida o evento e propaga a mudança ao navegador por WebSocket/SSE, com polling apenas como fallback.
  4. 4Conta respondePOST /api/v1/support/tickets/{ticketId}/messages devolve o ticket para a fila, com estado OPEN.
Atualização sem recarregarO painel administrativo da VexusPay reconcilia a fila automaticamente em aproximadamente 3 segundos. No sistema integrador, consuma o webhook no backend e notifique o browser por WebSocket ou SSE; use polling periódico somente como fallback e reconciliação.
ACESSO

Autenticação servidor a servidor

Envie Apikey e X-Client-Secret a partir do backend. Nunca exponha o segredo no painel web, aplicativo móvel ou código entregue ao navegador.

  • support.manage na credencial
  • Produto support habilitado
  • Conta titular ativa
ISOLAMENTO

Cada titular vê apenas os próprios tickets

O titular é determinado pela credencial autenticada, nunca por um ID enviado no corpo. Consulta ou resposta a um ticket de outra conta não revela sua existência.

  • Sem parâmetro de titular no corpo ou na URL
  • Mensagens preservadas em ordem cronológica
  • Até quatro imagens privadas por mensagem
CONFIABILIDADE

Idempotência em toda escrita

Toda operação POST, inclusive upload e controle de webhook, usa uma chave de 8 a 100 caracteres. Em um retry, repita a mesma chave, o mesmo corpo e, no multipart, exatamente os mesmos bytes.

  • Corpo diferente com a mesma chave gera conflito
  • Nova intenção exige uma chave nova
  • Rotas GET não usam a chave
CONTRATO V1

Rotas publicadas

https://api.vexuspay.com.br
POST/api/v1/support/attachments

Recebe no campo multipart file uma imagem JPEG, PNG ou WebP de até 5 MiB.

GET/api/v1/support/attachments/{attachmentId}

Baixa o binário privado com autenticação; o navegador deve acessá-lo pelo backend do integrador.

POST/api/v1/support/tickets

Abre um ticket com category, subject e texto, até quatro attachment_ids, ou ambos.

GET/api/v1/support/tickets

Lista somente os tickets pertencentes à conta autenticada.

GET/api/v1/support/tickets/{ticketId}

Retorna o ticket e sua conversa cronológica.

POST/api/v1/support/tickets/{ticketId}/messages

Envia texto de até 5.000 caracteres, até quatro attachment_ids, ou ambos.

POST/api/v1/support/tickets/{ticketId}/close

Confirma o fechamento do ticket.

GET/api/v1/support/webhooks

Lista os endpoints de suporte da própria conta, sem reexibir o segredo.

POST/api/v1/support/webhooks

Cadastra uma URL HTTPS e entrega o segredo de assinatura uma única vez.

POST/api/v1/support/webhooks/{webhookId}/rotate-secret

Revoga o segredo anterior e retorna o novo uma única vez.

POST/api/v1/support/webhooks/{webhookId}/activate

Reativa a entrega para o endpoint.

POST/api/v1/support/webhooks/{webhookId}/deactivate

Pausa novas entregas para o endpoint.

Enviar uma imagem privada
curl --request POST 'https://api.vexuspay.com.br/api/v1/support/attachments' \
  --header 'Apikey: SEU_CLIENT_ID' \
  --header 'X-Client-Secret: SEU_CLIENT_SECRET' \
  --header 'Idempotency-Key: 14f759ee-a6f4-420a-924a-8ce85de34717' \
  --form 'file=@/caminho/evidencia.png;type=image/png'
Limites e download protegidoCada imagem pode ter até 5 MiB, 8.192 px por lado e 20 megapixels. O upload retorna um ID PENDING válido por 24 horas; cada conta pode manter 20 pendentes e enviar, numa janela móvel de 24 horas, até 100 arquivos ou 100 MiB. Vincule até quatro IDs no JSON do ticket ou da mensagem. O download_url exige credenciais API: o backend deve baixar ou fazer proxy autorizado, nunca repassar Apikey ou X-Client-Secret ao navegador. Mensagens e webhooks carregam somente metadados e URL, jamais bytes/base64.
Abrir um ticket em produção
curl --request POST 'https://api.vexuspay.com.br/api/v1/support/tickets' \
  --header 'Apikey: SEU_CLIENT_ID' \
  --header 'X-Client-Secret: SEU_CLIENT_SECRET' \
  --header 'Idempotency-Key: 9cb6dffc-a856-4c52-a417-4be6012dde8a' \
  --header 'Content-Type: application/json' \
  --data '{
    "category": "IMPLEMENTATION",
    "subject": "Dúvida na integração",
    "message": "Precisamos validar o retorno do endpoint de cobrança.",
    "attachment_ids": ["d6c53708-95f6-46f2-8bf7-2c4cdd4ccade"]
  }'
Cadastrar o receptor de webhook
curl --request POST 'https://api.vexuspay.com.br/api/v1/support/webhooks' \
  --header 'Apikey: SEU_CLIENT_ID' \
  --header 'X-Client-Secret: SEU_CLIENT_SECRET' \
  --header 'Idempotency-Key: 672980ad-209c-4557-9ff8-d6a22430bf09' \
  --header 'Content-Type: application/json' \
  --data '{
    "label": "Suporte produção",
    "url": "https://seu-dominio.com.br/webhooks/vexus/support"
  }'
CATEGORIAS

Direcione o assunto para a fila correta

FINANCIAL Financeiro TECHNICAL Técnico / TI IMPLEMENTATION Implementação / API COMMERCIAL Comercial / Conta OTHER Outros

O assunto deve ter de 3 a 180 caracteres. O texto aceita até 5.000 caracteres e pode ficar vazio quando houver ao menos uma imagem válida.

ESTADOS

Acompanhe quem precisa agir

OPEN
Novo ou devolvido à fila após resposta da conta.
IN_PROGRESS
Em atendimento pela equipe VexusPay.
WAITING_CUSTOMER
A VexusPay respondeu e aguarda retorno da conta.
RESOLVED
Solução registrada, aguardando conclusão.
CLOSED
Encerrado; novas mensagens retornam conflito.
RESPOSTAS E ERROS

Integre com rastreabilidade

Sucessos seguem {"statusCode": ..., "data": ...}. Erros informam código estável, correlationId e se a falha é retentável.

  • ✓
    Registre o correlation ID sem salvar credenciais.
  • ✓
    Trate 401 como credencial ausente ou inválida.
  • ✓
    Trate 403 como produto, escopo ou elegibilidade ausente.
  • ✓
    Trate 413/415 como tamanho ou tipo de imagem inválido; não tente converter no navegador.
  • ✓
    Respeite 429 e X-RateLimit-Reset; o limite padrão é 120 requisições por minuto por credencial.
WEBHOOK ASSINADOPUBLICADO

Valide antes de processar

Preserve o corpo bruto e use o segredo retornado na criação ou rotação do endpoint:

  • 1
    Receba apenas HTTPS e preserve o corpo bruto antes do json_decode.
  • 2
    Calcule HMAC-SHA256(timestamp + "." + rawBody, signing_secret) e compare em tempo constante com X-Vexus-Signature.
  • 3
    Valide X-Vexus-Timestamp e deduplique por event_id e X-Vexus-Delivery.
  • 4
    Persista o evento, responda 2xx rapidamente e processe o trabalho em fila interna.
Eventos, imagens e retryAssine support.ticket.created, support.ticket.assigned, support.message.created, support.ticket.status_changed e support.ticket.closed. Em mensagens com imagens, o evento contém somente metadados e download_url protegida, nunca bytes/base64. Falhas transitórias são reenviadas com backoff exponencial e jitter; após o limite configurado, a entrega fica em DEAD. Veja também a seção Webhooks.
Eventos

Webhooks

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

Fluxo de webhooks assinados da VexusPay com retentativa automática
Headers de entrega
X-Vexus-Event: checkout.order.status_changed | virtual_card.otp.received | support.message.created
X-Vexus-Delivery: <uuid>
X-Vexus-Timestamp: <unix_timestamp>
X-Vexus-Signature: v1=<hmac_sha256>
Como verificarUse exatamente o corpo bruto recebido: HMAC-SHA256(timestamp + "." + rawBody, signing_secret). Compare em tempo constante, aceite somente timestamps recentes e use event_id/X-Vexus-Delivery para ignorar repetição. A entrega retenta falhas de transporte, 408, 409, 425, 429 e 5xx; webhooks de suporte estão disponíveis somente em Produção.
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.

Exemplos de integração
const response = await fetch("https://sandbox-api.example.invalid/health/live", {
  method: 'GET',
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
GET /health/ready Público

Readiness

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

Exemplos de integração
const response = await fetch("https://sandbox-api.example.invalid/health/ready", {
  method: 'GET',
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
Módulo

PIX

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

Fluxo da API PIX VexusPay, da cobrança ao webhook de confirmação
POST /api/v1/cashin Credenciais Escopo: cashin Produto: pix.cash_in

Criar cobrança PIX

Cria uma cobrança PIX dinâmica. Use uma nova Idempotency-Key para cada nova cobrança; reutilize a chave somente ao repetir exatamente a mesma intenção.

Exige Idempotency-Key.
Exemplos de integração
import crypto from 'node:crypto';

const idempotencyKey = crypto.randomUUID();

const response = await fetch("https://sandbox-api.example.invalid/api/v1/cashin", {
  method: 'POST',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
    'Idempotency-Key': idempotencyKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "amount": 25.9
}),
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
Ver corpo de exemplo
{
    "amount": 25.9
}
POST /api/v1/cashout Credenciais Escopo: cashout Produto: pix.cash_out

Enviar PIX

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

Exige Idempotency-Key.
Exemplos de integração
import crypto from 'node:crypto';

const idempotencyKey = crypto.randomUUID();

const response = await fetch("https://sandbox-api.example.invalid/api/v1/cashout", {
  method: 'POST',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
    'Idempotency-Key': idempotencyKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "amount": 20,
    "pix_key": "<chave-pix-destino>",
    "pix_key_type": "random",
    "description": "Repasse"
}),
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
Ver corpo de exemplo
{
    "amount": 20,
    "pix_key": "<chave-pix-destino>",
    "pix_key_type": "random",
    "description": "Repasse"
}
POST /api/v1/pix/qr/decode Credenciais Escopo: cashout Produto: pix.cash_out

Ler QR Code PIX

Valida o CRC e decodifica um payload EMV PIX sem movimentar saldo. A resposta informa se o valor está fixado no próprio QR.

Exemplos de integração
const response = await fetch("https://sandbox-api.example.invalid/api/v1/pix/qr/decode", {
  method: 'POST',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "payload": "00020101021226810014br.gov.bcb.pix2559https://example.invalid/pix/cobranca-exemplo520400005303986540539.905802BR5905VEXUS6009SAO PAULO62070503***6304B9CE"
}),
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
Ver corpo de exemplo
{
    "payload": "00020101021226810014br.gov.bcb.pix2559https://example.invalid/pix/cobranca-exemplo520400005303986540539.905802BR5905VEXUS6009SAO PAULO62070503***6304B9CE"
}
POST /api/v1/pix/qr/pay Credenciais Escopo: cashout Produto: pix.cash_out

Pagar QR Code PIX

Paga um QR Code PIX após validar CRC, valor declarado, saldo e limites. Um valor presente no QR sempre prevalece sobre o valor enviado pelo integrador.

Exige Idempotency-Key.
Exemplos de integração
import crypto from 'node:crypto';

const idempotencyKey = crypto.randomUUID();

const response = await fetch("https://sandbox-api.example.invalid/api/v1/pix/qr/pay", {
  method: 'POST',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
    'Idempotency-Key': idempotencyKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "payload": "00020101021226810014br.gov.bcb.pix2559https://example.invalid/pix/cobranca-exemplo520400005303986540539.905802BR5905VEXUS6009SAO PAULO62070503***6304B9CE",
    "description": "Fornecedor"
}),
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
Ver corpo de exemplo
{
    "payload": "00020101021226810014br.gov.bcb.pix2559https://example.invalid/pix/cobranca-exemplo520400005303986540539.905802BR5905VEXUS6009SAO PAULO62070503***6304B9CE",
    "description": "Fornecedor"
}
Módulo

Boleto

Emissão, consulta e pagamento de boleto.

Fluxo da API de boleto VexusPay, da emissão ao pagamento
POST /api/v1/boleto/issue Credenciais Escopo: boleto Produto: boleto

Emitir boleto

Emite uma cobrança direta sem exigir um item no catálogo do Checkout. O produto de API boleto precisa estar habilitado. Nome, CPF/CNPJ e e-mail são obtidos do cadastro; o endereço não é obrigatório.

Exige Idempotency-Key.
Exemplos de integração
import crypto from 'node:crypto';

const idempotencyKey = crypto.randomUUID();

const response = await fetch("https://sandbox-api.example.invalid/api/v1/boleto/issue", {
  method: 'POST',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
    'Idempotency-Key': idempotencyKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "amount": 99.9,
    "due_date": "2026-09-30",
    "description": "Cobrança por boleto"
}),
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
Ver corpo de exemplo
{
    "amount": 99.9,
    "due_date": "2026-09-30",
    "description": "Cobrança por boleto"
}
POST /api/v1/boleto/info Credenciais Escopo: boleto Produto: boleto

Consultar boleto

Consulta no provedor, sem movimentar saldo, o valor atualizado e os dados do beneficiário.

Exemplos de integração
const response = await fetch("https://sandbox-api.example.invalid/api/v1/boleto/info", {
  method: 'POST',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "billetCode": "00190000000000014990000000000000000000000000"
}),
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
Ver corpo de exemplo
{
    "billetCode": "00190000000000014990000000000000000000000000"
}
POST /api/v1/boleto/pay Credenciais Escopo: boleto Produto: boleto

Pagar boleto

Reconsulta no provedor o valor atualizado e o beneficiário, então valida saldo e limites antes do pagamento. O integrador envia somente o código.

Exige Idempotency-Key.
Exemplos de integração
import crypto from 'node:crypto';

const idempotencyKey = crypto.randomUUID();

const response = await fetch("https://sandbox-api.example.invalid/api/v1/boleto/pay", {
  method: 'POST',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
    'Idempotency-Key': idempotencyKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "billetCode": "00190000000000014990000000000000000000000000"
}),
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
Ver corpo de exemplo
{
    "billetCode": "00190000000000014990000000000000000000000000"
}
Módulo

Checkout

Catálogo, links, meios habilitados e relatório de checkout.

Fluxo da API de cartão VexusPay, do checkout à confirmação
POST /api/v1/card/config Somente produção Credenciais Escopo: cards.write Produto: card PUBLISHED_PRODUCTION_ONLY

Obter configuração de tokenização

Retorna a chave pública e a URL do SDK autorizados para tokenizar o cartão no navegador. Nunca envie PAN ou CVV ao backend da VexusPay.

Exemplos de integração
const response = await fetch("https://api.nodexhub.com.br/api/v1/card/config", {
  method: 'POST',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
Ver corpo de exemplo
{}
POST /api/v1/card/pay Somente produção Credenciais Escopo: cards.write Produto: card PUBLISHED_PRODUCTION_ONLY

Processar pagamento com cartão

Processa uma cobrança avulsa sem exigir um item no catálogo do Checkout. O produto de API card precisa estar habilitado. Use um cartão já tokenizado pelo SDK indicado na configuração; esta rota exige token de uso único e não aceita PAN ou CVV.

Exige Idempotency-Key.
Exemplos de integração
import crypto from 'node:crypto';

const idempotencyKey = crypto.randomUUID();

const response = await fetch("https://api.nodexhub.com.br/api/v1/card/pay", {
  method: 'POST',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
    'Idempotency-Key': idempotencyKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "amount": 99.9,
    "external_id": "pedido-zoe-123",
    "buyer_name": "Cliente de Exemplo",
    "buyer_email": "cliente@example.com",
    "buyer_cpf": "52998224725",
    "card_token": "SUBSTITUA_PELO_TOKEN_DE_USO_UNICO",
    "payment_method_id": "visa",
    "installments": 1,
    "description": "Pedido ZoePay 123"
}),
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
Ver corpo de exemplo
{
    "amount": 99.9,
    "external_id": "pedido-zoe-123",
    "buyer_name": "Cliente de Exemplo",
    "buyer_email": "cliente@example.com",
    "buyer_cpf": "52998224725",
    "card_token": "SUBSTITUA_PELO_TOKEN_DE_USO_UNICO",
    "payment_method_id": "visa",
    "installments": 1,
    "description": "Pedido ZoePay 123"
}
GET /api/v1/checkout/methods Credenciais Escopo: checkout Produto: checkout

Listar meios de checkout

Retorna somente meios de pagamento homologados e disponíveis para a conta autenticada.

Exemplos de integração
const response = await fetch("https://sandbox-api.example.invalid/api/v1/checkout/methods", {
  method: 'GET',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
  },
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
GET /api/v1/checkout/report Credenciais Escopo: checkout Produto: checkout

Consultar relatório de checkout

Retorna métricas agregadas dos links e pedidos pertencentes à conta autenticada.

Exemplos de integração
const response = await fetch("https://sandbox-api.example.invalid/api/v1/checkout/report", {
  method: 'GET',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
  },
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
GET /api/v1/checkout/products Credenciais Escopo: checkout Produto: checkout

Listar produtos de checkout

Lista produtos ativos e arquivados do catálogo da conta.

Exemplos de integração
const response = await fetch("https://sandbox-api.example.invalid/api/v1/checkout/products", {
  method: 'GET',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
  },
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
POST /api/v1/checkout/products Credenciais Escopo: checkout Produto: checkout

Criar produto de checkout

Cria um produto no catálogo. Meios que exigem identificação de produto externo só podem ser usados quando provider_product_id for informado.

Exige Idempotency-Key.
Exemplos de integração
import crypto from 'node:crypto';

const idempotencyKey = crypto.randomUUID();

const response = await fetch("https://sandbox-api.example.invalid/api/v1/checkout/products", {
  method: 'POST',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
    'Idempotency-Key': idempotencyKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "Plano mensal",
    "price": "49.90",
    "currency": "BRL",
    "payment_methods": [
        "PIX"
    ]
}),
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
Ver corpo de exemplo
{
    "name": "Plano mensal",
    "price": "49.90",
    "currency": "BRL",
    "payment_methods": [
        "PIX"
    ]
}
GET /api/v1/checkout/products/{productId} Credenciais Escopo: checkout Produto: checkout

Consultar produto de checkout

Retorna o produto do catálogo pertencente à conta autenticada.

Exemplos de integração
const response = await fetch("https://sandbox-api.example.invalid/api/v1/checkout/products/SUBSTITUA_PELO_PRODUCT_ID", {
  method: 'GET',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
  },
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
PUT /api/v1/checkout/products/{productId} Credenciais Escopo: checkout Produto: checkout

Atualizar produto de checkout

Atualiza uma versão do produto. Envie version retornado na leitura para impedir sobrescrita concorrente.

Exige Idempotency-Key.
Exemplos de integração
import crypto from 'node:crypto';

const idempotencyKey = crypto.randomUUID();

const response = await fetch("https://sandbox-api.example.invalid/api/v1/checkout/products/SUBSTITUA_PELO_PRODUCT_ID", {
  method: 'PUT',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
    'Idempotency-Key': idempotencyKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "Plano mensal atualizado",
    "price": "59.90",
    "currency": "BRL",
    "payment_methods": [
        "PIX"
    ],
    "version": 1
}),
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
Ver corpo de exemplo
{
    "name": "Plano mensal atualizado",
    "price": "59.90",
    "currency": "BRL",
    "payment_methods": [
        "PIX"
    ],
    "version": 1
}
DELETE /api/v1/checkout/products/{productId} Credenciais Escopo: checkout Produto: checkout

Arquivar produto de checkout

Arquiva o produto e os links ativos associados. A ação exige Idempotency-Key e não aceita corpo.

Exige Idempotency-Key.
Exemplos de integração
import crypto from 'node:crypto';

const idempotencyKey = crypto.randomUUID();

const response = await fetch("https://sandbox-api.example.invalid/api/v1/checkout/products/SUBSTITUA_PELO_PRODUCT_ID", {
  method: 'DELETE',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
    'Idempotency-Key': idempotencyKey,
  },
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
GET /api/v1/checkout/links Credenciais Escopo: checkout Produto: checkout

Listar links de checkout

Lista links de pagamento, estado e métricas da conta autenticada.

Exemplos de integração
const response = await fetch("https://sandbox-api.example.invalid/api/v1/checkout/links", {
  method: 'GET',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
  },
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
POST /api/v1/checkout/links Credenciais Escopo: checkout Produto: checkout

Criar link de checkout

Cria um link avulso ou associado a produto. O payment_path retornado deve ser combinado com seu domínio VexusPay.

Exige Idempotency-Key.
Exemplos de integração
import crypto from 'node:crypto';

const idempotencyKey = crypto.randomUUID();

const response = await fetch("https://sandbox-api.example.invalid/api/v1/checkout/links", {
  method: 'POST',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
    'Idempotency-Key': idempotencyKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "title": "Pagamento de serviço",
    "amount": "49.90",
    "currency": "BRL",
    "payment_methods": [
        "PIX"
    ]
}),
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
Ver corpo de exemplo
{
    "title": "Pagamento de serviço",
    "amount": "49.90",
    "currency": "BRL",
    "payment_methods": [
        "PIX"
    ]
}
GET /api/v1/checkout/links/{linkId} Credenciais Escopo: checkout Produto: checkout

Consultar link de checkout

Retorna a configuração e o payment_path do link pertencente à conta autenticada.

Exemplos de integração
const response = await fetch("https://sandbox-api.example.invalid/api/v1/checkout/links/SUBSTITUA_PELO_LINK_ID", {
  method: 'GET',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
  },
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
PUT /api/v1/checkout/links/{linkId} Credenciais Escopo: checkout Produto: checkout

Atualizar link de checkout

Atualiza uma versão do link. Envie version retornado na leitura para impedir sobrescrita concorrente.

Exige Idempotency-Key.
Exemplos de integração
import crypto from 'node:crypto';

const idempotencyKey = crypto.randomUUID();

const response = await fetch("https://sandbox-api.example.invalid/api/v1/checkout/links/SUBSTITUA_PELO_LINK_ID", {
  method: 'PUT',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
    'Idempotency-Key': idempotencyKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "title": "Pagamento de serviço atualizado",
    "amount": "59.90",
    "currency": "BRL",
    "payment_methods": [
        "PIX"
    ],
    "version": 1
}),
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
Ver corpo de exemplo
{
    "title": "Pagamento de serviço atualizado",
    "amount": "59.90",
    "currency": "BRL",
    "payment_methods": [
        "PIX"
    ],
    "version": 1
}
POST /api/v1/checkout/links/{linkId}/archive Credenciais Escopo: checkout Produto: checkout

Arquivar link de checkout

Arquiva o link e impede novos pagamentos. Exige Idempotency-Key e não aceita corpo.

Exige Idempotency-Key.
Exemplos de integração
import crypto from 'node:crypto';

const idempotencyKey = crypto.randomUUID();

const response = await fetch("https://sandbox-api.example.invalid/api/v1/checkout/links/SUBSTITUA_PELO_LINK_ID/archive", {
  method: 'POST',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
    'Idempotency-Key': idempotencyKey,
  },
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
POST /api/v1/checkout/links/{linkId}/cancel Credenciais Escopo: checkout Produto: checkout

Cancelar link de checkout

Cancela o link com motivo auditável e impede novos pagamentos. Exige Idempotency-Key.

Exige Idempotency-Key.
Exemplos de integração
import crypto from 'node:crypto';

const idempotencyKey = crypto.randomUUID();

const response = await fetch("https://sandbox-api.example.invalid/api/v1/checkout/links/SUBSTITUA_PELO_LINK_ID/cancel", {
  method: 'POST',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
    'Idempotency-Key': idempotencyKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "reason": "Solicitação de cancelamento do cliente"
}),
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
Ver corpo de exemplo
{
    "reason": "Solicitação de cancelamento do cliente"
}
Módulo

Cripto

Catálogo, carteiras, saldos, depósitos, saques, swaps, transferências internas e conversões conforme capacidade consultada.

Fluxo da API de cripto VexusPay, da carteira à conversão
GET /api/v1/crypto/networks Credenciais Escopo: cashin Produto: crypto

Listar redes cripto

Lista BSC e TRON com manutenção e capacidades de depósito, saque e swap.

Exemplos de integração
const response = await fetch("https://sandbox-api.example.invalid/api/v1/crypto/networks", {
  method: 'GET',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
  },
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
GET /api/v1/crypto/assets Credenciais Escopo: cashin Produto: crypto

Listar ativos cripto

Lista os ativos por rede, casas decimais e capacidades efetivamente habilitadas.

Exemplos de integração
const response = await fetch("https://sandbox-api.example.invalid/api/v1/crypto/assets", {
  method: 'GET',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
  },
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
GET /api/v1/crypto/swap-pairs Credenciais Escopo: cashin Produto: crypto

Listar pares de swap

Lista pares same-chain e o cross-chain USDT TRC-20 ↔ USDT BEP-20 disponíveis.

Exemplos de integração
const response = await fetch("https://sandbox-api.example.invalid/api/v1/crypto/swap-pairs", {
  method: 'GET',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
  },
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
GET /api/v1/crypto/wallets Credenciais Escopo: cashin Produto: crypto

Listar carteiras cripto

Lista somente as carteiras da conta ou do contexto de custódia autenticado.

Exemplos de integração
const response = await fetch("https://sandbox-api.example.invalid/api/v1/crypto/wallets", {
  method: 'GET',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
  },
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
POST /api/v1/crypto/wallets Credenciais Escopo: cashin Produto: crypto

Criar ou obter carteira

Cria ou reutiliza idempotentemente a carteira HD BSC ou TRON da conta. Tokens da mesma rede usam o mesmo endereço.

Exige Idempotency-Key.
Exemplos de integração
import crypto from 'node:crypto';

const idempotencyKey = crypto.randomUUID();

const response = await fetch("https://sandbox-api.example.invalid/api/v1/crypto/wallets", {
  method: 'POST',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
    'Idempotency-Key': idempotencyKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "network": "BSC"
}),
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
Ver corpo de exemplo
{
    "network": "BSC"
}
GET /api/v1/crypto/wallets/{walletId} Credenciais Escopo: cashin Produto: crypto

Consultar carteira

Retorna uma carteira Vexus pertencente à conta autenticada.

Exemplos de integração
const response = await fetch("https://sandbox-api.example.invalid/api/v1/crypto/wallets/SUBSTITUA_PELO_WALLET_ID", {
  method: 'GET',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
  },
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
GET /api/v1/crypto/wallets/{walletId}/balances Credenciais Escopo: cashin Produto: crypto

Consultar saldos da carteira

Retorna saldos ledger, disponível, reservado, pendente e on-chain em strings inteiras de unidade mínima.

Exemplos de integração
const response = await fetch("https://sandbox-api.example.invalid/api/v1/crypto/wallets/SUBSTITUA_PELO_WALLET_ID/balances", {
  method: 'GET',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
  },
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
GET /api/v1/crypto/wallets/{walletId}/transactions Credenciais Escopo: cashin Produto: crypto

Listar transações da carteira

Lista depósitos e saques recentes da carteira.

Exemplos de integração
const response = await fetch("https://sandbox-api.example.invalid/api/v1/crypto/wallets/SUBSTITUA_PELO_WALLET_ID/transactions", {
  method: 'GET',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
  },
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
GET /api/v1/crypto/deposits Credenciais Escopo: cashin Produto: crypto

Listar depósitos

Lista somente depósitos vinculados às carteiras da conta ou do contexto de custódia autenticado.

Exemplos de integração
const response = await fetch("https://sandbox-api.example.invalid/api/v1/crypto/deposits", {
  method: 'GET',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
  },
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
GET /api/v1/crypto/deposits/{depositId} Credenciais Escopo: cashin Produto: crypto

Consultar depósito

Retorna confirmações e estado do depósito; CREDITED ou 200 não substituem a verificação de estado terminal.

Exemplos de integração
const response = await fetch("https://sandbox-api.example.invalid/api/v1/crypto/deposits/SUBSTITUA_PELO_DEPOSIT_ID", {
  method: 'GET',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
  },
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
POST /api/v1/crypto/withdrawals/quote Credenciais Escopo: cashout Produto: crypto

Cotar saque cripto

Cria cotação autoritativa com taxas, valor líquido, total debitado e validade em *_units. Em GROSS, o valor informado é o teto e as taxas são descontadas dele. Não movimenta saldo.

Exige Idempotency-Key.
Exemplos de integração
import crypto from 'node:crypto';

const idempotencyKey = crypto.randomUUID();

const response = await fetch("https://sandbox-api.example.invalid/api/v1/crypto/withdrawals/quote", {
  method: 'POST',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
    'Idempotency-Key': idempotencyKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "network": "BSC",
    "asset": "USDT_BSC",
    "destination_address": "SUBSTITUA_PELO_ENDERECO_BSC",
    "amount_units": "1000000",
    "amount_mode": "GROSS"
}),
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
Ver corpo de exemplo
{
    "network": "BSC",
    "asset": "USDT_BSC",
    "destination_address": "SUBSTITUA_PELO_ENDERECO_BSC",
    "amount_units": "1000000",
    "amount_mode": "GROSS"
}
POST /api/v1/crypto/withdrawals Credenciais Escopo: cashout Produto: crypto

Executar saque cotado

Reserva e agenda o saque pelo quote_id. A resposta 202 não confirma blockchain; acompanhe até estado terminal.

Exige Idempotency-Key.
Exemplos de integração
import crypto from 'node:crypto';

const idempotencyKey = crypto.randomUUID();

const response = await fetch("https://sandbox-api.example.invalid/api/v1/crypto/withdrawals", {
  method: 'POST',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
    'Idempotency-Key': idempotencyKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "quote_id": "00000000-0000-4000-8000-000000000002"
}),
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
Ver corpo de exemplo
{
    "quote_id": "00000000-0000-4000-8000-000000000002"
}
GET /api/v1/crypto/withdrawals/{withdrawalId} Credenciais Escopo: cashout Produto: crypto

Consultar saque

Retorna estado, TXID e custo real de rede quando disponíveis.

Exemplos de integração
const response = await fetch("https://sandbox-api.example.invalid/api/v1/crypto/withdrawals/SUBSTITUA_PELO_WITHDRAWAL_ID", {
  method: 'GET',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
  },
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
POST /api/v1/crypto/swaps/quote Credenciais Escopo: cashout Produto: crypto

Cotar swap cripto

Cria cotação autoritativa same-chain ou USDT cross-chain usando somente pares publicados.

Exige Idempotency-Key.
Exemplos de integração
import crypto from 'node:crypto';

const idempotencyKey = crypto.randomUUID();

const response = await fetch("https://sandbox-api.example.invalid/api/v1/crypto/swaps/quote", {
  method: 'POST',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
    'Idempotency-Key': idempotencyKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "asset_in": "USDT_TRC20",
    "asset_out": "USDT_BSC",
    "amount_in_units": "1000000",
    "slippage_bps": 50
}),
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
Ver corpo de exemplo
{
    "asset_in": "USDT_TRC20",
    "asset_out": "USDT_BSC",
    "amount_in_units": "1000000",
    "slippage_bps": 50
}
POST /api/v1/crypto/swaps Credenciais Escopo: cashout Produto: crypto

Executar swap cotado

Reserva e agenda o swap pelo quote_id. A resposta 202 não confirma liquidação.

Exige Idempotency-Key.
Exemplos de integração
import crypto from 'node:crypto';

const idempotencyKey = crypto.randomUUID();

const response = await fetch("https://sandbox-api.example.invalid/api/v1/crypto/swaps", {
  method: 'POST',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
    'Idempotency-Key': idempotencyKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "quote_id": "00000000-0000-4000-8000-000000000003"
}),
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
Ver corpo de exemplo
{
    "quote_id": "00000000-0000-4000-8000-000000000003"
}
GET /api/v1/crypto/swaps/{swapId} Credenciais Escopo: cashout Produto: crypto

Consultar swap

Retorna valores realizados, hashes e estado conciliado do swap.

Exemplos de integração
const response = await fetch("https://sandbox-api.example.invalid/api/v1/crypto/swaps/SUBSTITUA_PELO_SWAP_ID", {
  method: 'GET',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
  },
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
POST /api/v1/crypto/internal-transfers Credenciais Escopo: cashout Produto: crypto

Transferir entre usuários

Liquida entre dois usuários VexusPay no ledger Vexus. Não cria transação blockchain nem TXID. Envie exatamente um destinatário: recipient_custody_subject é o modo recomendado para White Label e precisa identificar um subject ACTIVE já existente na mesma White Label; esta rota não cria usuário automaticamente. recipient_external_user_id permanece apenas para compatibilidade.

Exige Idempotency-Key.
Exemplos de integração
import crypto from 'node:crypto';

const idempotencyKey = crypto.randomUUID();

const response = await fetch("https://sandbox-api.example.invalid/api/v1/crypto/internal-transfers", {
  method: 'POST',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
    'Idempotency-Key': idempotencyKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "recipient_custody_subject": "usuario_00000002",
    "network": "TRON",
    "asset": "USDT_TRC20",
    "amount_units": "1000000"
}),
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
Ver corpo de exemplo
{
    "recipient_custody_subject": "usuario_00000002",
    "network": "TRON",
    "asset": "USDT_TRC20",
    "amount_units": "1000000"
}
GET /api/v1/crypto/conversions/capabilities Credenciais Escopo: cashin Produto: crypto

Consultar capacidade de conversão

Retorna as direções, ativos, redes e controles operacionais disponíveis sem criar operação.

Exemplos de integração
const response = await fetch("https://sandbox-api.example.invalid/api/v1/crypto/conversions/capabilities", {
  method: 'GET',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
  },
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
GET /api/v1/crypto/conversions/markets Credenciais Escopo: cashin Produto: crypto

Listar mercados de conversão

Preços indicativos do parceiro; não são cotações executáveis.

Exemplos de integração
const response = await fetch("https://sandbox-api.example.invalid/api/v1/crypto/conversions/markets", {
  method: 'GET',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
  },
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
GET /api/v1/crypto/conversions Credenciais Escopo: cashin Produto: crypto

Listar endereços de conversão

Lista endereços externos do parceiro pertencentes à conta.

Exemplos de integração
const response = await fetch("https://sandbox-api.example.invalid/api/v1/crypto/conversions", {
  method: 'GET',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
  },
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
POST /api/v1/crypto/conversions/deposit-address Credenciais Escopo: cashin Produto: crypto MAINTENANCE

Preparar endereço para venda cripto

Rota reservada para o fluxo cripto para BRL. Novas vendas estão em manutenção; não a utilize até capabilities informar disponibilidade.

Exige Idempotency-Key.
Exemplos de integração
import crypto from 'node:crypto';

const idempotencyKey = crypto.randomUUID();

const response = await fetch("https://sandbox-api.example.invalid/api/v1/crypto/conversions/deposit-address", {
  method: 'POST',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
    'Idempotency-Key': idempotencyKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "asset": "USDT",
    "network": "TRX"
}),
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
Ver corpo de exemplo
{
    "asset": "USDT",
    "network": "TRX"
}
GET /api/v1/crypto/conversion-operations Credenciais Escopo: cashout Produto: crypto

Listar conversões

Lista operações de conversão pertencentes ao contexto autenticado, inclusive estados históricos.

Exemplos de integração
const response = await fetch("https://sandbox-api.example.invalid/api/v1/crypto/conversion-operations", {
  method: 'GET',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
  },
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
POST /api/v1/crypto/conversions/quote Credenciais Escopo: cashout Produto: crypto

Cotar BRL para cripto

Cria uma cotação executável FIAT_TO_CRYPTO somente quando capabilities liberar o ativo e a rede. O destino externo é obrigatório. CRYPTO_TO_FIAT está em manutenção e não faz parte deste request nesta versão.

Exige Idempotency-Key.
Exemplos de integração
import crypto from 'node:crypto';

const idempotencyKey = crypto.randomUUID();

const response = await fetch("https://sandbox-api.example.invalid/api/v1/crypto/conversions/quote", {
  method: 'POST',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
    'Idempotency-Key': idempotencyKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "direction": "FIAT_TO_CRYPTO",
    "asset": "USDT",
    "network": "TRX",
    "brl_amount_minor": "10000",
    "destination_address": "SUBSTITUA_PELO_ENDERECO_TRC20"
}),
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
Ver corpo de exemplo
{
    "direction": "FIAT_TO_CRYPTO",
    "asset": "USDT",
    "network": "TRX",
    "brl_amount_minor": "10000",
    "destination_address": "SUBSTITUA_PELO_ENDERECO_TRC20"
}
POST /api/v1/crypto/conversions/{conversionId}/confirm Credenciais Escopo: cashout Produto: crypto

Confirmar conversão

Confirma uma cotação FIAT_TO_CRYPTO ainda válida. A resposta 202 indica apenas admissão e exige acompanhamento até estado terminal.

Exige Idempotency-Key.
Exemplos de integração
import crypto from 'node:crypto';

const idempotencyKey = crypto.randomUUID();

const response = await fetch("https://sandbox-api.example.invalid/api/v1/crypto/conversions/SUBSTITUA_PELO_CONVERSION_ID/confirm", {
  method: 'POST',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
    'Idempotency-Key': idempotencyKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
Ver corpo de exemplo
{}
GET /api/v1/crypto/conversions/{conversionId} Credenciais Escopo: cashout Produto: crypto

Consultar conversão

Consulta o estado auditável da conversão.

Exemplos de integração
const response = await fetch("https://sandbox-api.example.invalid/api/v1/crypto/conversions/SUBSTITUA_PELO_CONVERSION_ID", {
  method: 'GET',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
  },
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
Módulo

Cartões

Cobrança direta por cartão tokenizado, além de capacidades, emissão, consulta, recarga, transações, controle, visualização segura e webhook OTP de cartões virtuais para contas autorizadas.

Fluxo da API de cartões virtuais VexusPay
GET /api/v1/cards/products Credenciais Escopo: cards.read Produto: virtual.cards

Listar tipos de cartão

Retorna o catálogo técnico de tipos de cartão reconhecidos pela VexusPay; a presença de um produto não autoriza emissão. Consulte /api/v1/cards/capabilities imediatamente antes da ação e só emita quando actions.issue=true. O catálogo é dinâmico e códigos técnicos do emissor não são expostos.

Exemplos de integração
const response = await fetch("https://sandbox-api.example.invalid/api/v1/cards/products", {
  method: 'GET',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
  },
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
GET /api/v1/cards/rates Credenciais Escopo: cards.read Produto: virtual.cards

Consultar taxas de cartões

Retorna as taxas comerciais efetivas da conta para emissão, recarga e processamento, com origem GLOBAL, PLAN ou USER. As taxas são dinâmicas: consulte antes de iniciar uma operação. A taxa do emissor é informada somente quando a emissão ou recarga for confirmada.

Exemplos de integração
const response = await fetch("https://sandbox-api.example.invalid/api/v1/cards/rates", {
  method: 'GET',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
  },
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
GET /api/v1/cards/capabilities Somente produção Credenciais Escopo: cards.read Produto: virtual.cards PUBLISHED_PRODUCTION_ONLY

Consultar capacidades de cartão virtual

Retorna as ações efetivamente disponíveis para a conta neste momento e informa se X-Vexus-External-User-Id é obrigatório. Consulte imediatamente antes de exibir ou iniciar uma ação; não prometa emissão, recarga ou controle quando a ação correspondente estiver false. O pool de liquidação não possui consulta pública separada e sua indisponibilidade mantém a emissão bloqueada.

Exemplos de integração
const response = await fetch("https://api.nodexhub.com.br/api/v1/cards/capabilities", {
  method: 'GET',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
  },
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
GET /api/v1/cards Credenciais Escopo: cards.read Produto: virtual.cards

Listar cartões

Lista somente os cartões do usuário externo informado quando external_user_header_required=true, com saldo, status, bandeira e últimos quatro dígitos. Não retorna PAN, CVV nem OTP.

Exemplos de integração
const response = await fetch("https://sandbox-api.example.invalid/api/v1/cards", {
  method: 'GET',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
    'X-Vexus-External-User-Id': 'witevexus:user:1001',
  },
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
POST /api/v1/cards Credenciais Escopo: cards.write Produto: virtual.cards

Criar cartão virtual

Emite um cartão VexusPay somente quando products e capabilities liberarem a ação. A emissão é financeira e exige Idempotency-Key. O cartão pré-pago em USD é financiado pela tesouraria compartilhada do emissor, abastecida em USDT; não existe débito ou conversão automática da carteira Vexus Crypto do usuário final nem operação atômica cripto para cartão. A White Label deve reservar e debitar seu próprio ledger separadamente. O intervalo técnico atual é de USD 10.00 a USD 1000000.00, sem substituir os limites de risco próprios da White Label. Quando exigido, external_user_id no corpo deve coincidir com X-Vexus-External-User-Id. Não repita com uma nova chave após resposta ambígua.

Exige Idempotency-Key.
Exemplos de integração
import crypto from 'node:crypto';

const idempotencyKey = crypto.randomUUID();

const response = await fetch("https://sandbox-api.example.invalid/api/v1/cards", {
  method: 'POST',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
    'Idempotency-Key': idempotencyKey,
    'X-Vexus-External-User-Id': 'witevexus:user:1001',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "product_code": "vexus_international",
    "amount": "10.00",
    "name_on_card": "CLIENTE EXEMPLO",
    "external_user_id": "witevexus:user:1001"
}),
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
Ver corpo de exemplo
{
    "product_code": "vexus_international",
    "amount": "10.00",
    "name_on_card": "CLIENTE EXEMPLO",
    "external_user_id": "witevexus:user:1001"
}
GET /api/v1/cards/{cardId} Credenciais Escopo: cards.read Produto: virtual.cards

Consultar cartão

Sincroniza saldo e status atuais para o usuário externo autenticado. Não retorna PAN, CVV nem OTP.

Exemplos de integração
const response = await fetch("https://sandbox-api.example.invalid/api/v1/cards/SUBSTITUA_PELO_CARD_ID", {
  method: 'GET',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
    'X-Vexus-External-User-Id': 'witevexus:user:1001',
  },
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
DELETE /api/v1/cards/{cardId} Credenciais Escopo: cards.write Produto: virtual.cards

Cancelar cartão

Cancela permanentemente um cartão somente quando capabilities.actions.cancel=true. A ação pode devolver saldo conforme regras do cartão e exige Idempotency-Key.

Exige Idempotency-Key.
Exemplos de integração
import crypto from 'node:crypto';

const idempotencyKey = crypto.randomUUID();

const response = await fetch("https://sandbox-api.example.invalid/api/v1/cards/SUBSTITUA_PELO_CARD_ID", {
  method: 'DELETE',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
    'Idempotency-Key': idempotencyKey,
    'X-Vexus-External-User-Id': 'witevexus:user:1001',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
Ver corpo de exemplo
{}
POST /api/v1/cards/{cardId}/fund Credenciais Escopo: cards.write Produto: virtual.cards

Recarregar cartão

Adiciona saldo somente quando capabilities.actions.fund=true. A recarga pré-paga em USD usa a tesouraria compartilhada do emissor, abastecida em USDT, e não debita nem converte automaticamente a carteira Vexus Crypto do usuário final. A White Label deve reservar e debitar seu próprio ledger separadamente. Exige Idempotency-Key, aceita atualmente de USD 10.00 a USD 1000000.00 e retorna as taxas confirmadas.

Exige Idempotency-Key.
Exemplos de integração
import crypto from 'node:crypto';

const idempotencyKey = crypto.randomUUID();

const response = await fetch("https://sandbox-api.example.invalid/api/v1/cards/SUBSTITUA_PELO_CARD_ID/fund", {
  method: 'POST',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
    'Idempotency-Key': idempotencyKey,
    'X-Vexus-External-User-Id': 'witevexus:user:1001',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "amount": "10.00"
}),
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
Ver corpo de exemplo
{
    "amount": "10.00"
}
POST /api/v1/cards/{cardId}/freeze Credenciais Escopo: cards.write Produto: virtual.cards

Congelar cartão

Suspende temporariamente um cartão ativo somente quando capabilities.actions.freeze=true. Exige Idempotency-Key.

Exige Idempotency-Key.
Exemplos de integração
import crypto from 'node:crypto';

const idempotencyKey = crypto.randomUUID();

const response = await fetch("https://sandbox-api.example.invalid/api/v1/cards/SUBSTITUA_PELO_CARD_ID/freeze", {
  method: 'POST',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
    'Idempotency-Key': idempotencyKey,
    'X-Vexus-External-User-Id': 'witevexus:user:1001',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
Ver corpo de exemplo
{}
POST /api/v1/cards/{cardId}/unfreeze Credenciais Escopo: cards.write Produto: virtual.cards

Descongelar cartão

Reativa um cartão congelado somente quando capabilities.actions.unfreeze=true. Exige Idempotency-Key.

Exige Idempotency-Key.
Exemplos de integração
import crypto from 'node:crypto';

const idempotencyKey = crypto.randomUUID();

const response = await fetch("https://sandbox-api.example.invalid/api/v1/cards/SUBSTITUA_PELO_CARD_ID/unfreeze", {
  method: 'POST',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
    'Idempotency-Key': idempotencyKey,
    'X-Vexus-External-User-Id': 'witevexus:user:1001',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
Ver corpo de exemplo
{}
GET /api/v1/cards/{cardId}/transactions Credenciais Escopo: cards.read Produto: virtual.cards

Listar transações do cartão

Retorna um snapshot de transações e saldo para exibição e conciliação auxiliar. O contrato do emissor não define identificador estável, paginação, webhook ou correlação completa do ciclo de autorização, captura, estorno, reembolso e chargeback; não use esta resposta como fonte contábil. Códigos OTP, PAN e CVV nunca são retornados.

Exemplos de integração
const response = await fetch("https://sandbox-api.example.invalid/api/v1/cards/SUBSTITUA_PELO_CARD_ID/transactions", {
  method: 'GET',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
    'X-Vexus-External-User-Id': 'witevexus:user:1001',
  },
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
POST /api/v1/cards/{cardId}/display-sessions Credenciais Escopo: cards.write Produto: virtual.cards

Criar visualização segura do cartão

Cria uma URL HTTPS de uso único, válida por 120 segundos, para exibir PAN e CVV diretamente no navegador do usuário. O backend da integração nunca recebe esses dados. Abra display_url diretamente em um iframe cuja origem coincida exatamente com allowed_origin; recarregar ou reutilizar a URL falha. Não faça proxy, fetch, captura, persistência ou log da URL. Quando exigido, X-Vexus-External-User-Id identifica o titular e external_user_id no corpo, se enviado, deve coincidir. Uma nova visualização exige nova Idempotency-Key; a recuperação não reexibe display_url e, após a expiração, crie outra sessão com outra chave.

Exige Idempotency-Key.
Exemplos de integração
import crypto from 'node:crypto';

const idempotencyKey = crypto.randomUUID();

const response = await fetch("https://sandbox-api.example.invalid/api/v1/cards/SUBSTITUA_PELO_CARD_ID/display-sessions", {
  method: 'POST',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
    'Idempotency-Key': idempotencyKey,
    'X-Vexus-External-User-Id': 'witevexus:user:1001',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "allowed_origin": "https://witevexus.fun",
    "external_user_id": "witevexus:user:1001"
}),
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
Ver corpo de exemplo
{
    "allowed_origin": "https://witevexus.fun",
    "external_user_id": "witevexus:user:1001"
}
GET /api/v1/cards/webhooks Credenciais Escopo: cards.read Produto: virtual.cards

Listar webhooks de OTP

Lista somente os endpoints exclusivos da conta inscritos apenas em virtual_card.otp.received. Endpoints mistos de outros produtos não são administráveis pelo escopo de cartões. O segredo nunca é retornado.

Exemplos de integração
const response = await fetch("https://sandbox-api.example.invalid/api/v1/cards/webhooks", {
  method: 'GET',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
  },
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
POST /api/v1/cards/webhooks Credenciais Escopo: cards.write Produto: virtual.cards

Configurar webhook de OTP

Cria um endpoint HTTPS para receber o único evento público de cartão, virtual_card.otp.received. O signing_secret aparece somente nesta resposta; armazene-o no cofre do backend. O evento usa createdAt em RFC 3339 UTC e assinatura HMAC sobre o corpo bruto. Exige Idempotency-Key.

Exige Idempotency-Key.
Exemplos de integração
import crypto from 'node:crypto';

const idempotencyKey = crypto.randomUUID();

const response = await fetch("https://sandbox-api.example.invalid/api/v1/cards/webhooks", {
  method: 'POST',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
    'Idempotency-Key': idempotencyKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "label": "OTP produção",
    "url": "https://api.exemplo.com/webhooks/vexus"
}),
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
Ver corpo de exemplo
{
    "label": "OTP produção",
    "url": "https://api.exemplo.com/webhooks/vexus"
}
POST /api/v1/cards/webhooks/{webhookId}/rotate-secret Somente produção Credenciais Escopo: cards.write Produto: virtual.cards PUBLISHED_PRODUCTION_ONLY

Rotacionar segredo do webhook OTP

Revoga imediatamente o segredo anterior, sem janela de sobreposição, e retorna o novo signing_secret uma única vez. Atualize o receptor de forma coordenada. Envie um objeto JSON vazio e Idempotency-Key. A recuperação posterior não reexibe o segredo.

Exige Idempotency-Key.
Exemplos de integração
import crypto from 'node:crypto';

const idempotencyKey = crypto.randomUUID();

const response = await fetch("https://api.nodexhub.com.br/api/v1/cards/webhooks/SUBSTITUA_PELO_WEBHOOK_ID/rotate-secret", {
  method: 'POST',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
    'Idempotency-Key': idempotencyKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
Ver corpo de exemplo
{}
POST /api/v1/cards/webhooks/{webhookId}/activate Somente produção Credenciais Escopo: cards.write Produto: virtual.cards PUBLISHED_PRODUCTION_ONLY

Ativar webhook OTP

Reativa novas entregas de virtual_card.otp.received para um endpoint da conta. Envie um objeto JSON vazio e Idempotency-Key.

Exige Idempotency-Key.
Exemplos de integração
import crypto from 'node:crypto';

const idempotencyKey = crypto.randomUUID();

const response = await fetch("https://api.nodexhub.com.br/api/v1/cards/webhooks/SUBSTITUA_PELO_WEBHOOK_ID/activate", {
  method: 'POST',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
    'Idempotency-Key': idempotencyKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
Ver corpo de exemplo
{}
POST /api/v1/cards/webhooks/{webhookId}/deactivate Somente produção Credenciais Escopo: cards.write Produto: virtual.cards PUBLISHED_PRODUCTION_ONLY

Desativar webhook OTP

Pausa novas entregas de virtual_card.otp.received sem apagar o histórico. Envie um objeto JSON vazio e Idempotency-Key.

Exige Idempotency-Key.
Exemplos de integração
import crypto from 'node:crypto';

const idempotencyKey = crypto.randomUUID();

const response = await fetch("https://api.nodexhub.com.br/api/v1/cards/webhooks/SUBSTITUA_PELO_WEBHOOK_ID/deactivate", {
  method: 'POST',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
    'Idempotency-Key': idempotencyKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
Ver corpo de exemplo
{}
Módulo

Conta

Consulta autorizada de saldo, limites financeiros efetivos, taxas e recuperação idempotente de operações.

GET /api/v1/account/limits Credenciais Escopo: account.read Produto: account

Limites da conta

Retorna os limites financeiros efetivos da conta em BRL: agregado, PIX de entrada e saída, boleto e transferência interna. O campo source informa se a regra vem da política GLOBAL ou de uma personalização USER.

Exemplos de integração
const response = await fetch("https://sandbox-api.example.invalid/api/v1/account/limits", {
  method: 'GET',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
  },
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
GET /api/v1/account/fees Credenciais Escopo: account.read Produto: account

Taxas da conta

Retorna taxas comerciais efetivas para PIX, boleto, cartão, cartão virtual, transferência interna e regras por ativo/rede cripto. Em cripto, a cotação da operação é autoritativa para custos de rede, taxa de serviço, valor líquido e débito total.

Exemplos de integração
const response = await fetch("https://sandbox-api.example.invalid/api/v1/account/fees", {
  method: 'GET',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
  },
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
GET /api/v1/account/operations/by-idempotency/{idempotencyKey} Somente produção Credenciais Escopo: account.read Produto: DYNAMIC_FROM_ORIGINAL_OPERATION PUBLISHED_PRODUCTION_ONLY

Consultar operação pela Idempotency-Key

Recupera de forma sanitizada o estado da intenção criada pela mesma credencial de produção. Exige account.read e valida dinamicamente, na conta proprietária da credencial, o produto e os entitlements da operação original; o custody subject delimita somente a propriedade do recurso e não possui contrato independente. Use após timeout, queda de conexão ou OPERATION_STATUS_AMBIGUOUS. Em cripto, PENDING recente ainda está em curso e, depois de 60 segundos, é promovido de forma conservadora para AMBIGUOUS com reconciliation_required=true. Ao receber ACCEPTED, pare o polling desta rota: wallet.create, withdrawal.quote, swap.quote, conversion.address e conversion.quote encerram a própria intenção com terminal=true; withdrawal.execute e swap.execute devem ser acompanhados pelo GET do resource_id até o lifecycle terminal. Persista o conversionId antes de POST /conversions/{conversionId}/confirm, pois a recuperação da confirmação pode retornar ACCEPTED sem resource_id; use o GET da conversão original. ACCEPTED nunca comprova liquidação nem autoriza uma nova intenção financeira. Codifique o segmento da chave conforme RFC 3986; por exemplo, `:` vira `%3A`. Para cripto, repita o contexto X-Vexus-Custody-Subject ou CENTRAL; para cartão da WiteVexus, repita X-Vexus-External-User-Id. A recuperação de display e webhook não reexibe display_url nem signing_secret. Se a criação de webhook for confirmada sem que o segredo tenha sido recebido, rotacione-o antes do uso; rotação ambígua permanece REVIEW e exige reconciliação. O replay do POST original com método, URL, corpo e chave idênticos conserva a resposta por 24 horas; depois que display_url expirar, crie outra sessão com outra chave.

Exemplos de integração
const response = await fetch("https://api.nodexhub.com.br/api/v1/account/operations/by-idempotency/SUBSTITUA_PELO_IDEMPOTENCY_KEY", {
  method: 'GET',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
    'X-Vexus-External-User-Id': 'witevexus:user:1001',
  },
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
GET /api/v1/account/ted Somente produção Credenciais Escopo: account.read Produto: account PUBLISHED_PRODUCTION_ONLY

Conta TED nominal

Consulta agência, conta, dígito, instituição e titular da conta TED vinculada ao usuário nominal. A consulta é somente leitura e nunca expõe credenciais do provedor.

Exemplos de integração
const response = await fetch("https://api.nodexhub.com.br/api/v1/account/ted", {
  method: 'GET',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
  },
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
GET /api/v1/account/balance Somente produção Credenciais Escopo: account.read Produto: account PUBLISHED_PRODUCTION_ONLY

Saldo da conta nominal

Consulta o saldo BRL da conta nominal no provedor bancário homologado. A resposta é somente leitura e é isolada pelo usuário autenticado.

Exemplos de integração
const response = await fetch("https://api.nodexhub.com.br/api/v1/account/balance", {
  method: 'GET',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
  },
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
GET /api/v1/account/transactions Somente produção Credenciais Escopo: account.read Produto: account PUBLISHED_PRODUCTION_ONLY

Extrato da conta nominal

Consulta o extrato da conta nominal em um período de até 31 dias, com paginação. Depósitos, saídas e demais tipos retornados permanecem separados por titular.

Exemplos de integração
const response = await fetch("https://api.nodexhub.com.br/api/v1/account/transactions", {
  method: 'GET',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
  },
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
GET /api/v1/nominal Somente produção Credenciais Escopo: account.read Produto: account PUBLISHED_PRODUCTION_ONLY

Conta nominal

Retorna a conta nominal ativa e a chave Pix vinculada ao usuário autenticado. Credenciais do provedor nunca são expostas.

Exemplos de integração
const response = await fetch("https://api.nodexhub.com.br/api/v1/nominal", {
  method: 'GET',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
  },
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
GET /api/v1/nominal/ted Somente produção Credenciais Escopo: account.read Produto: account PUBLISHED_PRODUCTION_ONLY

Agência e conta nominal

Consulta agência, conta, dígito e instituição da conta nominal.

Exemplos de integração
const response = await fetch("https://api.nodexhub.com.br/api/v1/nominal/ted", {
  method: 'GET',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
  },
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
GET /api/v1/nominal/balance Somente produção Credenciais Escopo: account.read Produto: account PUBLISHED_PRODUCTION_ONLY

Saldo nominal

Consulta o saldo BRL da conta nominal do usuário autenticado.

Exemplos de integração
const response = await fetch("https://api.nodexhub.com.br/api/v1/nominal/balance", {
  method: 'GET',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
  },
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
GET /api/v1/nominal/transactions Somente produção Credenciais Escopo: account.read Produto: account PUBLISHED_PRODUCTION_ONLY

Movimentações nominais

Consulta depósitos, saídas e demais movimentações da conta nominal em até 31 dias.

Exemplos de integração
const response = await fetch("https://api.nodexhub.com.br/api/v1/nominal/transactions", {
  method: 'GET',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
  },
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
GET /api/v1/nominal/pix-key Somente produção Credenciais Escopo: account.read Produto: account PUBLISHED_PRODUCTION_ONLY

Chave Pix nominal

Retorna a chave Pix nominal já provisionada.

Exemplos de integração
const response = await fetch("https://api.nodexhub.com.br/api/v1/nominal/pix-key", {
  method: 'GET',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
  },
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
GET /api/v1/nominal/operations/{operationId} Somente produção Credenciais Escopo: account.read Produto: account PUBLISHED_PRODUCTION_ONLY

Status de operação nominal

Consulta o resultado idempotente de uma operação QR ou saída Pix nominal.

Exemplos de integração
const response = await fetch("https://api.nodexhub.com.br/api/v1/nominal/operations/SUBSTITUA_PELO_OPERATION_ID", {
  method: 'GET',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
  },
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
POST /api/v1/balance Credenciais Escopo: cashin Produto: pix.cash_in

Consultar saldo

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

Exemplos de integração
const response = await fetch("https://sandbox-api.example.invalid/api/v1/balance", {
  method: 'POST',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
Ver corpo de exemplo
{}
Módulo

Conta nominal

POST /api/v1/nominal/pix-key Somente produção Credenciais Escopo: pix.cash_in Produto: pix.cash_in PUBLISHED_PRODUCTION_ONLY

Criar chave Pix nominal

Solicita uma conta virtual no provedor bancário homologado com chave aleatória, e-mail ou CNPJ. Exige Idempotency-Key e só funciona após a aprovação administrativa do pedido nominal.

Exige Idempotency-Key.
Exemplos de integração
import crypto from 'node:crypto';

const idempotencyKey = crypto.randomUUID();

const response = await fetch("https://api.nodexhub.com.br/api/v1/nominal/pix-key", {
  method: 'POST',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
    'Idempotency-Key': idempotencyKey,
  },
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
POST /api/v1/nominal/qr/dynamic Somente produção Credenciais Escopo: pix.cash_in Produto: pix.cash_in PUBLISHED_PRODUCTION_ONLY

Gerar QR dinâmico nominal

Cria uma cobrança QR dinâmica na conta nominal. Exige Idempotency-Key.

Exige Idempotency-Key.
Exemplos de integração
import crypto from 'node:crypto';

const idempotencyKey = crypto.randomUUID();

const response = await fetch("https://api.nodexhub.com.br/api/v1/nominal/qr/dynamic", {
  method: 'POST',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
    'Idempotency-Key': idempotencyKey,
  },
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
POST /api/v1/nominal/qr/static Somente produção Credenciais Escopo: pix.cash_in Produto: pix.cash_in PUBLISHED_PRODUCTION_ONLY

Gerar QR estático nominal

Cria um QR estático na conta nominal. Exige Idempotency-Key.

Exige Idempotency-Key.
Exemplos de integração
import crypto from 'node:crypto';

const idempotencyKey = crypto.randomUUID();

const response = await fetch("https://api.nodexhub.com.br/api/v1/nominal/qr/static", {
  method: 'POST',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
    'Idempotency-Key': idempotencyKey,
  },
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
POST /api/v1/nominal/qr/decode Somente produção Credenciais Escopo: pix.qr_pay Produto: pix.qr_pay PUBLISHED_PRODUCTION_ONLY

Ler QR nominal

Lê e valida um QR Pix no provedor bancário homologado sem executar pagamento.

Exige Idempotency-Key.
Exemplos de integração
import crypto from 'node:crypto';

const idempotencyKey = crypto.randomUUID();

const response = await fetch("https://api.nodexhub.com.br/api/v1/nominal/qr/decode", {
  method: 'POST',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
    'Idempotency-Key': idempotencyKey,
  },
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
POST /api/v1/nominal/qr/pay Somente produção Credenciais Escopo: pix.qr_pay Produto: pix.qr_pay PUBLISHED_PRODUCTION_ONLY

Pagar QR nominal

Paga um QR Pix pela conta nominal. A operação é assíncrona e exige Idempotency-Key.

Exige Idempotency-Key.
Exemplos de integração
import crypto from 'node:crypto';

const idempotencyKey = crypto.randomUUID();

const response = await fetch("https://api.nodexhub.com.br/api/v1/nominal/qr/pay", {
  method: 'POST',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
    'Idempotency-Key': idempotencyKey,
  },
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
POST /api/v1/nominal/pix-out Somente produção Credenciais Escopo: pix.cash_out Produto: pix.cash_out PUBLISHED_PRODUCTION_ONLY

Enviar Pix nominal

Envia Pix pela conta nominal. A confirmação é recebida por webhook e exige Idempotency-Key.

Exige Idempotency-Key.
Exemplos de integração
import crypto from 'node:crypto';

const idempotencyKey = crypto.randomUUID();

const response = await fetch("https://api.nodexhub.com.br/api/v1/nominal/pix-out", {
  method: 'POST',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
    'Idempotency-Key': idempotencyKey,
  },
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
Módulo

White Label

Contrato White Label da própria conta: plano, adicionais, taxas, cobrança e situação de acesso.

GET /api/v1/white-label Credenciais Escopo: account.read Produto: white_label

Consultar White Label

Retorna, em uma única resposta, a situação do contrato, plano, adicionais, cobrança, taxas e produtos efetivamente habilitados. Esta consulta permanece acessível mesmo quando a mensalidade estiver vencida.

Exemplos de integração
const response = await fetch("https://sandbox-api.example.invalid/api/v1/white-label", {
  method: 'GET',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
  },
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
GET /api/v1/white-label/plan Credenciais Escopo: account.read Produto: white_label

Consultar plano White Label

Retorna o plano e os adicionais contratados pela conta autenticada.

Exemplos de integração
const response = await fetch("https://sandbox-api.example.invalid/api/v1/white-label/plan", {
  method: 'GET',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
  },
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
GET /api/v1/white-label/fees Credenciais Escopo: account.read Produto: white_label

Consultar taxas White Label

Retorna as taxas comerciais do plano, incluindo PIX, boleto, cartão virtual e regras por ativo/rede cripto.

Exemplos de integração
const response = await fetch("https://sandbox-api.example.invalid/api/v1/white-label/fees", {
  method: 'GET',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
  },
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
GET /api/v1/white-label/billing Credenciais Escopo: account.read Produto: white_label

Consultar cobrança White Label

Retorna mensalidade, entrada, valor pendente, vencimento e situação de acesso. Não cria cobrança nem movimenta saldo.

Exemplos de integração
const response = await fetch("https://sandbox-api.example.invalid/api/v1/white-label/billing", {
  method: 'GET',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
  },
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
GET /api/v1/white-label/status Credenciais Escopo: account.read Produto: white_label

Consultar status White Label

Retorna somente a situação do contrato e se operações financeiras pela API estão liberadas.

Exemplos de integração
const response = await fetch("https://sandbox-api.example.invalid/api/v1/white-label/status", {
  method: 'GET',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
  },
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
GET /api/v1/white-label/nominal Somente produção Credenciais Escopo: account.read Produto: white_label

Listar solicitações de conta nominal

Lista somente os pedidos da White Label titular. Documento aparece mascarado e os dados de identidade vêm da VexusPay central.

Exemplos de integração
const response = await fetch("https://sandbox-api.example.invalid/api/v1/white-label/nominal", {
  method: 'GET',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
  },
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
POST /api/v1/white-label/nominal Somente produção Credenciais Escopo: account.read Produto: white_label

Solicitar conta nominal

Envia o pedido para análise administrativa. Nome, CPF ou CNPJ não são aceitos no corpo: a VexusPay usa exclusivamente o KYC já aprovado do titular.

Exemplos de integração
const response = await fetch("https://sandbox-api.example.invalid/api/v1/white-label/nominal", {
  method: 'POST',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "reason": "Conta operacional da minha marca para recebimentos PIX."
}),
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
Ver corpo de exemplo
{
    "reason": "Conta operacional da minha marca para recebimentos PIX."
}
POST /api/v1/white-label/nominal/bind Somente produção Credenciais Escopo: account.read Produto: white_label

Vincular cliente nominal

Vincula o identificador do cliente na White Label à conta nominal Vexus já ativa. O identificador é isolado por White Label.

Exemplos de integração
const response = await fetch("https://sandbox-api.example.invalid/api/v1/white-label/nominal/bind", {
  method: 'POST',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "nominal_user_id": 1001,
    "external_subject": "cliente:1001"
}),
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
Ver corpo de exemplo
{
    "nominal_user_id": 1001,
    "external_subject": "cliente:1001"
}
GET /api/v1/white-label/nominal/{requestId} Somente produção Credenciais Escopo: account.read Produto: white_label

Consultar solicitação nominal

Consulta um pedido pertencente à White Label titular, sem retornar documento completo nem credenciais da conta.

Exemplos de integração
const response = await fetch("https://sandbox-api.example.invalid/api/v1/white-label/nominal/SUBSTITUA_PELO_REQUEST_ID", {
  method: 'GET',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
  },
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
DELETE /api/v1/white-label/nominal/{requestId} Somente produção Credenciais Escopo: account.read Produto: white_label

Cancelar solicitação nominal

Cancela um pedido ainda pendente ou aprovado. Uma conta já provisionada não pode ser cancelada por esta rota.

Exemplos de integração
const response = await fetch("https://sandbox-api.example.invalid/api/v1/white-label/nominal/SUBSTITUA_PELO_REQUEST_ID", {
  method: 'DELETE',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
  },
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
Módulo

Suporte

Central de tickets e webhooks assinados para qualquer conta ativa autenticada. Disponível somente em produção.

GET /api/v1/support/tickets Somente produção Credenciais Escopo: support.manage Produto: support

Listar tickets de suporte

Somente produção. Lista até os 100 tickets mais recentes da conta titular da credencial, ordenados pela última atualização. Não retorna tickets de outras contas nem o conteúdo das mensagens.

Exemplos de integração
const response = await fetch("https://api.nodexhub.com.br/api/v1/support/tickets", {
  method: 'GET',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
  },
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
POST /api/v1/support/tickets Somente produção Credenciais Escopo: support.manage Produto: support

Abrir ticket de suporte

Somente produção. Abre um ticket na fila da VexusPay para a conta autenticada. Envie texto, até quatro attachment_ids previamente gerados, ou ambos; nunca envie HTML, bytes/base64 nem credenciais no JSON.

Exige Idempotency-Key.
Exemplos de integração
import crypto from 'node:crypto';

const idempotencyKey = crypto.randomUUID();

const response = await fetch("https://api.nodexhub.com.br/api/v1/support/tickets", {
  method: 'POST',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
    'Idempotency-Key': idempotencyKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "category": "IMPLEMENTATION",
    "subject": "Dúvida na integração PIX",
    "message": "Precisamos validar o tratamento do retorno assíncrono da nossa integração.",
    "attachment_ids": [
        "d6c53708-95f6-46f2-8bf7-2c4cdd4ccade"
    ]
}),
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
Ver corpo de exemplo
{
    "category": "IMPLEMENTATION",
    "subject": "Dúvida na integração PIX",
    "message": "Precisamos validar o tratamento do retorno assíncrono da nossa integração.",
    "attachment_ids": [
        "d6c53708-95f6-46f2-8bf7-2c4cdd4ccade"
    ]
}
GET /api/v1/support/tickets/{ticketId} Somente produção Credenciais Escopo: support.manage Produto: support

Consultar ticket de suporte

Somente produção. Retorna o ticket e a conversa cronológica quando o ticket pertence à conta titular da credencial.

Exemplos de integração
const response = await fetch("https://api.nodexhub.com.br/api/v1/support/tickets/SUBSTITUA_PELO_TICKET_ID", {
  method: 'GET',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
  },
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
POST /api/v1/support/tickets/{ticketId}/messages Somente produção Credenciais Escopo: support.manage Produto: support

Responder ticket de suporte

Somente produção. Adiciona texto, até quatro attachment_ids previamente gerados, ou ambos ao ticket da própria conta. Ao responder, o ticket volta para OPEN. Tickets CLOSED não aceitam novas mensagens.

Exige Idempotency-Key.
Exemplos de integração
import crypto from 'node:crypto';

const idempotencyKey = crypto.randomUUID();

const response = await fetch("https://api.nodexhub.com.br/api/v1/support/tickets/SUBSTITUA_PELO_TICKET_ID/messages", {
  method: 'POST',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
    'Idempotency-Key': idempotencyKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "message": "Aplicamos o ajuste e enviamos um novo correlation ID para análise.",
    "attachment_ids": [
        "d6c53708-95f6-46f2-8bf7-2c4cdd4ccade"
    ]
}),
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
Ver corpo de exemplo
{
    "message": "Aplicamos o ajuste e enviamos um novo correlation ID para análise.",
    "attachment_ids": [
        "d6c53708-95f6-46f2-8bf7-2c4cdd4ccade"
    ]
}
POST /api/v1/support/tickets/{ticketId}/close Somente produção Credenciais Escopo: support.manage Produto: support

Fechar ticket de suporte

Somente produção. Confirma o encerramento do ticket da própria conta. Envie um objeto JSON vazio e preserve a Idempotency-Key caso precise repetir a solicitação.

Exige Idempotency-Key.
Exemplos de integração
import crypto from 'node:crypto';

const idempotencyKey = crypto.randomUUID();

const response = await fetch("https://api.nodexhub.com.br/api/v1/support/tickets/SUBSTITUA_PELO_TICKET_ID/close", {
  method: 'POST',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
    'Idempotency-Key': idempotencyKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
Ver corpo de exemplo
{}
POST /api/v1/support/attachments Somente produção Credenciais Escopo: support.manage Produto: support

Enviar imagem de suporte

Somente produção. Recebe uma única imagem no campo multipart file, valida o MIME real, normaliza o bitmap e retorna um attachment_id pendente. Aceita JPEG, PNG ou WebP de até 5 MiB; o ID expira em 24 horas se não for vinculado a uma mensagem.

Exige Idempotency-Key.
Exemplos de integração
import crypto from 'node:crypto';
import { readFile } from 'node:fs/promises';

const idempotencyKey = crypto.randomUUID();

const image = await readFile('/caminho/para/evidencia.png');
const form = new FormData();
form.append('file', new Blob([image], { type: 'image/png' }), 'evidencia.png');

const response = await fetch("https://api.nodexhub.com.br/api/v1/support/attachments", {
  method: 'POST',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
    'Idempotency-Key': idempotencyKey,
  },
  body: form,
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
GET /api/v1/support/attachments/{attachmentId} Somente produção Credenciais Escopo: support.manage Produto: support

Baixar imagem de suporte

Somente produção. Retorna o binário privado de uma imagem pertencente à conta. O download exige credenciais em cada chamada, usa Cache-Control: no-store e deve ser intermediado pelo backend da integração; nunca exponha o Client Secret ao navegador.

Exemplos de integração
const response = await fetch("https://api.nodexhub.com.br/api/v1/support/attachments/SUBSTITUA_PELO_ATTACHMENT_ID", {
  method: 'GET',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
  },
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
const imageBytes = Buffer.from(await response.arrayBuffer());
console.log(response.headers.get('content-type'), imageBytes.length);
GET /api/v1/support/webhooks Somente produção Credenciais Escopo: support.manage Produto: support

Listar webhooks de suporte

Somente produção. Lista os endpoints da própria conta inscritos em eventos de suporte. A URL é mascarada para a origem HTTPS e o segredo de assinatura nunca é reexibido.

Exemplos de integração
const response = await fetch("https://api.nodexhub.com.br/api/v1/support/webhooks", {
  method: 'GET',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
  },
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
POST /api/v1/support/webhooks Somente produção Credenciais Escopo: support.manage Produto: support

Cadastrar webhook de suporte

Somente produção. Cria um endpoint HTTPS para receber eventos de suporte. O signing_secret aparece somente nesta resposta; armazene-o imediatamente em um cofre. Se events for omitido, os cinco eventos são assinados.

Exige Idempotency-Key.
Exemplos de integração
import crypto from 'node:crypto';

const idempotencyKey = crypto.randomUUID();

const response = await fetch("https://api.nodexhub.com.br/api/v1/support/webhooks", {
  method: 'POST',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
    'Idempotency-Key': idempotencyKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "label": "Suporte produção",
    "url": "https://api.exemplo.com/webhooks/vexus/support",
    "events": [
        "support.message.created",
        "support.ticket.status_changed",
        "support.ticket.closed"
    ]
}),
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
Ver corpo de exemplo
{
    "label": "Suporte produção",
    "url": "https://api.exemplo.com/webhooks/vexus/support",
    "events": [
        "support.message.created",
        "support.ticket.status_changed",
        "support.ticket.closed"
    ]
}
POST /api/v1/support/webhooks/{webhookId}/rotate-secret Somente produção Credenciais Escopo: support.manage Produto: support

Rotacionar segredo do webhook de suporte

Somente produção. Invalida o segredo anterior e retorna o novo signing_secret uma única vez. Envie um objeto JSON vazio e atualize o receptor antes de depender de novas entregas.

Exige Idempotency-Key.
Exemplos de integração
import crypto from 'node:crypto';

const idempotencyKey = crypto.randomUUID();

const response = await fetch("https://api.nodexhub.com.br/api/v1/support/webhooks/SUBSTITUA_PELO_WEBHOOK_ID/rotate-secret", {
  method: 'POST',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
    'Idempotency-Key': idempotencyKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
Ver corpo de exemplo
{}
POST /api/v1/support/webhooks/{webhookId}/activate Somente produção Credenciais Escopo: support.manage Produto: support

Ativar webhook de suporte

Somente produção. Reativa um endpoint da própria conta e limpa o circuito de falhas. Envie um objeto JSON vazio.

Exige Idempotency-Key.
Exemplos de integração
import crypto from 'node:crypto';

const idempotencyKey = crypto.randomUUID();

const response = await fetch("https://api.nodexhub.com.br/api/v1/support/webhooks/SUBSTITUA_PELO_WEBHOOK_ID/activate", {
  method: 'POST',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
    'Idempotency-Key': idempotencyKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
Ver corpo de exemplo
{}
POST /api/v1/support/webhooks/{webhookId}/deactivate Somente produção Credenciais Escopo: support.manage Produto: support

Desativar webhook de suporte

Somente produção. Suspende novas entregas ao endpoint sem excluir o histórico. Envie um objeto JSON vazio.

Exige Idempotency-Key.
Exemplos de integração
import crypto from 'node:crypto';

const idempotencyKey = crypto.randomUUID();

const response = await fetch("https://api.nodexhub.com.br/api/v1/support/webhooks/SUBSTITUA_PELO_WEBHOOK_ID/deactivate", {
  method: 'POST',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
    'Idempotency-Key': idempotencyKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
Ver corpo de exemplo
{}
Módulo

Split

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

Fluxo da API de Split Payment VexusPay entre os recebedores
GET /api/v1/splits/rules Credenciais Escopo: split Produto: split

Listar regras de split

Lista as regras pertencentes à conta autenticada.

Exemplos de integração
const response = await fetch("https://sandbox-api.example.invalid/api/v1/splits/rules", {
  method: 'GET',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
  },
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
POST /api/v1/splits/rules Credenciais Escopo: split Produto: split

Criar regra de split

Cria uma regra versionada por percentuais ou valores fixos.

Exige Idempotency-Key.
Exemplos de integração
import crypto from 'node:crypto';

const idempotencyKey = crypto.randomUUID();

const response = await fetch("https://sandbox-api.example.invalid/api/v1/splits/rules", {
  method: 'POST',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
    'Idempotency-Key': idempotencyKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "Parceiros",
    "mode": "PERCENTAGE",
    "currency": "BRL",
    "participants": [
        {
            "handle": "conta-parceira",
            "percentage": "20.00"
        }
    ]
}),
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
Ver corpo de exemplo
{
    "name": "Parceiros",
    "mode": "PERCENTAGE",
    "currency": "BRL",
    "participants": [
        {
            "handle": "conta-parceira",
            "percentage": "20.00"
        }
    ]
}
PUT /api/v1/splits/rules/{ruleId} Credenciais Escopo: split Produto: split

Revisar regra de split

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

Exige Idempotency-Key.
Exemplos de integração
import crypto from 'node:crypto';

const idempotencyKey = crypto.randomUUID();

const response = await fetch("https://sandbox-api.example.invalid/api/v1/splits/rules/SUBSTITUA_PELO_RULE_ID", {
  method: 'PUT',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
    'Idempotency-Key': idempotencyKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "Parceiros v2",
    "mode": "PERCENTAGE",
    "currency": "BRL",
    "participants": [
        {
            "handle": "conta-parceira",
            "percentage": "25.00"
        }
    ]
}),
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
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 Escopo: split Produto: split

Arquivar regra de split

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

Exemplos de integração
const response = await fetch("https://sandbox-api.example.invalid/api/v1/splits/rules/SUBSTITUA_PELO_RULE_ID", {
  method: 'DELETE',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
  },
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
POST /api/v1/splits Credenciais Escopo: split Produto: split

Criar split

Cria a operação financeira e suas alocações a partir de uma regra ativa. Requer uma rota de liquidação Split homologada para a conta; a gestão de regras continua disponível sem essa rota.

Exige Idempotency-Key.
Exemplos de integração
import crypto from 'node:crypto';

const idempotencyKey = crypto.randomUUID();

const response = await fetch("https://sandbox-api.example.invalid/api/v1/splits", {
  method: 'POST',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
    'Idempotency-Key': idempotencyKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "rule_id": "00000000-0000-4000-8000-000000000001",
    "amount": 100,
    "payer": {
        "name": "Cliente de Exemplo",
        "document": "52998224725",
        "email": "cliente@example.com"
    }
}),
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
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 Escopo: split Produto: split

Consultar split

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

Exemplos de integração
const response = await fetch("https://sandbox-api.example.invalid/api/v1/splits/SUBSTITUA_PELO_SPLIT_ID", {
  method: 'GET',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
  },
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
POST /api/v1/splits/{splitId}/cancel Credenciais Escopo: split Produto: split

Cancelar split

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

Exemplos de integração
const response = await fetch("https://sandbox-api.example.invalid/api/v1/splits/SUBSTITUA_PELO_SPLIT_ID/cancel", {
  method: 'POST',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
  },
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
POST /api/v1/splits/{splitId}/refund Credenciais Escopo: split Produto: split

Solicitar devolução do split

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

Exige Idempotency-Key.
Exemplos de integração
import crypto from 'node:crypto';

const idempotencyKey = crypto.randomUUID();

const response = await fetch("https://sandbox-api.example.invalid/api/v1/splits/SUBSTITUA_PELO_SPLIT_ID/refund", {
  method: 'POST',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
    'Idempotency-Key': idempotencyKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "amount": 25,
    "comment": "Devolução parcial solicitada pelo cliente"
}),
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
Ver corpo de exemplo
{
    "amount": 25,
    "comment": "Devolução parcial solicitada pelo cliente"
}
GET /api/v1/splits/report Credenciais Escopo: split Produto: split

Relatório de participante

Retorna itens da conta autenticada no intervalo UTC informado.

Exemplos de integração
const response = await fetch("https://sandbox-api.example.invalid/api/v1/splits/report", {
  method: 'GET',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
  },
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
Módulo

Sandbox Controls

Controles extras exclusivos do Sandbox para simular estados sem movimentar valores reais.

GET /api/v1/sandbox/workspace Credenciais Escopo: sandbox.manage

Consultar workspace Sandbox

Mostra apenas saldos e recursos fictícios da conta autenticada.

Exemplos de integração
const response = await fetch("https://sandbox-api.example.invalid/api/v1/sandbox/workspace", {
  method: 'GET',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
  },
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
POST /api/v1/sandbox/faucet Credenciais Escopo: sandbox.manage

Creditar faucet Sandbox

Credita um ativo fictício no ledger isolado do Sandbox.

Exige Idempotency-Key.
Exemplos de integração
import crypto from 'node:crypto';

const idempotencyKey = crypto.randomUUID();

const response = await fetch("https://sandbox-api.example.invalid/api/v1/sandbox/faucet", {
  method: 'POST',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
    'Idempotency-Key': idempotencyKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "asset": "USDT_BEP20",
    "amount": "25.00"
}),
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
Ver corpo de exemplo
{
    "asset": "USDT_BEP20",
    "amount": "25.00"
}
POST /api/v1/sandbox/reset Credenciais Escopo: sandbox.manage

Resetar workspace Sandbox

Apaga somente recursos Sandbox da conta e recria o saldo inicial fictício.

Exige Idempotency-Key.
Exemplos de integração
import crypto from 'node:crypto';

const idempotencyKey = crypto.randomUUID();

const response = await fetch("https://sandbox-api.example.invalid/api/v1/sandbox/reset", {
  method: 'POST',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
    'Idempotency-Key': idempotencyKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "confirmation": "RESET_SANDBOX"
}),
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
Ver corpo de exemplo
{
    "confirmation": "RESET_SANDBOX"
}
POST /api/v1/sandbox/resources/{resourceType}/{resourceId}/actions Credenciais Escopo: sandbox.manage

Transicionar recurso

Aprova, falha, expira ou reverte uma operação pendente fictícia.

Exige Idempotency-Key.
Exemplos de integração
import crypto from 'node:crypto';

const idempotencyKey = crypto.randomUUID();

const response = await fetch("https://sandbox-api.example.invalid/api/v1/sandbox/resources/SUBSTITUA_PELO_RESOURCE_TYPE/SUBSTITUA_PELO_RESOURCE_ID/actions", {
  method: 'POST',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
    'Idempotency-Key': idempotencyKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "action": "APPROVE"
}),
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
Ver corpo de exemplo
{
    "action": "APPROVE"
}
POST /api/v1/sandbox/crypto/deposits Credenciais Escopo: sandbox.manage

Simular depósito cripto

Cria um depósito fictício sem transmissão ou consulta blockchain. Use o wallet_id retornado pela criação/listagem de uma carteira Sandbox da própria conta.

Exige Idempotency-Key.
Exemplos de integração
import crypto from 'node:crypto';

const idempotencyKey = crypto.randomUUID();

const response = await fetch("https://sandbox-api.example.invalid/api/v1/sandbox/crypto/deposits", {
  method: 'POST',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
    'Idempotency-Key': idempotencyKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "wallet_id": "00000000-0000-4000-8000-000000000003",
    "amount": "10.00",
    "confirmations": 0
}),
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
Ver corpo de exemplo
{
    "wallet_id": "00000000-0000-4000-8000-000000000003",
    "amount": "10.00",
    "confirmations": 0
}
POST /api/v1/sandbox/cards/{cardId}/transactions Credenciais Escopo: sandbox.manage

Simular transação de cartão

Simula aprovação, recusa, estorno ou refund de um cartão fictício.

Exige Idempotency-Key.
Exemplos de integração
import crypto from 'node:crypto';

const idempotencyKey = crypto.randomUUID();

const response = await fetch("https://sandbox-api.example.invalid/api/v1/sandbox/cards/SUBSTITUA_PELO_CARD_ID/transactions", {
  method: 'POST',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
    'Idempotency-Key': idempotencyKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "amount": "12.50",
    "currency": "USD",
    "outcome": "APPROVED"
}),
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
Ver corpo de exemplo
{
    "amount": "12.50",
    "currency": "USD",
    "outcome": "APPROVED"
}
POST /api/v1/sandbox/cards/{cardId}/otp Credenciais Escopo: sandbox.manage

Gerar OTP de carteira digital

Gera OTP fictício e o entrega apenas pelo pipeline de webhook Sandbox.

Exige Idempotency-Key.
Exemplos de integração
import crypto from 'node:crypto';

const idempotencyKey = crypto.randomUUID();

const response = await fetch("https://sandbox-api.example.invalid/api/v1/sandbox/cards/SUBSTITUA_PELO_CARD_ID/otp", {
  method: 'POST',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
    'Idempotency-Key': idempotencyKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "wallet_type": "GOOGLE_PAY"
}),
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
Ver corpo de exemplo
{
    "wallet_type": "GOOGLE_PAY"
}
GET /api/v1/sandbox/webhook-deliveries Credenciais Escopo: sandbox.manage

Listar entregas de webhook

Lista entregas e tentativas do ambiente Sandbox.

Exemplos de integração
const response = await fetch("https://sandbox-api.example.invalid/api/v1/sandbox/webhook-deliveries", {
  method: 'GET',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
  },
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
POST /api/v1/sandbox/webhook-deliveries/{deliveryId}/retry Credenciais Escopo: sandbox.manage

Reenviar webhook Sandbox

Agenda novamente uma entrega Sandbox sem afetar webhooks de produção.

Exige Idempotency-Key.
Exemplos de integração
import crypto from 'node:crypto';

const idempotencyKey = crypto.randomUUID();

const response = await fetch("https://sandbox-api.example.invalid/api/v1/sandbox/webhook-deliveries/SUBSTITUA_PELO_DELIVERY_ID/retry", {
  method: 'POST',
  headers: {
    'Apikey': process.env.VEXUS_CLIENT_ID,
    'X-Client-Secret': process.env.VEXUS_CLIENT_SECRET,
    'Idempotency-Key': idempotencyKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
Ver corpo de exemplo
{}
Transparência

Disponibilidade

PIX cash-in/cash-out/QR PUBLISHED
Boleto issue/info/pay PUBLISHED
Crypto Vexus — catálogo, carteiras e depósitosNão existe webhook público de ciclo de vida cripto; consulte o recurso até estado terminal. PUBLISHED
Crypto Vexus — saquesCotação, execução idempotente e consulta do recurso até estado terminal. Não existe webhook público de ciclo de vida cripto. PUBLISHED
Crypto Vexus — swapsSame-chain BSC/TRON e USDT cross-chain somente nos pares publicados; consulte o recurso até estado terminal. PUBLISHED
Crypto Vexus — transferências internasLiquidação apenas no ledger; não gera TXID. PUBLISHED
Cripto — BRL para criptoExige destino externo, capacidade liberada e cotação válida. Ativos e redes vêm do catálogo/capabilities; consulte o recurso até estado terminal. PUBLISHED_WITH_EXPLICIT_AUTHORIZATION
Cripto — cripto para BRLNovas vendas estão bloqueadas até a publicação do contrato completo de recebimento e liquidação. Não envie quote/confirm nessa direção. MAINTENANCE
Sandbox públicoDNS, TLS e health checks públicos validados. Não usa saldo, credenciais, provedores ou webhooks de Produção. AVAILABLE
Split rules/create/get/cancel/refund/report PUBLISHED
Recuperação de operação por Idempotency-KeyA mesma credencial consulta o par operation + Idempotency-Key após timeout ou resposta ambígua, sem repetir a movimentação financeira. PUBLISHED_PRODUCTION_ONLY
VexusPay CardsExige produto virtual.cards, permissões cards.read/cards.write e entitlement virtual.card.api por conta. Produtos, capacidades e taxas são dinâmicos. PAN e CVV não são devolvidos pela API: o backend cria uma URL efêmera e de uso único para exibição direta no navegador. O único webhook público de cartão é virtual_card.otp.received; acompanhe os demais estados por consulta. PUBLISHED_WITH_EXPLICIT_AUTHORIZATION
Pagamento tradicional por cartão (card.pay)Cobrança avulsa sem item do catálogo de Checkout; exige produto card e aceita somente token de uso único criado pelo SDK indicado pela configuração, nunca PAN ou CVV. PUBLISHED_PRODUCTION_ONLY
Checkout management APIProdutos, links, meios habilitados e relatório exigem produto checkout e escopo checkout. PUBLISHED
White Label contract APIConsulta plano, adicionais, taxas, cobrança e status. Enquanto OVERDUE ou SUSPENDED, estas rotas de consulta continuam disponíveis, mas as APIs operacionais retornam WHITE_LABEL_OVERDUE ou WHITE_LABEL_SUSPENDED. PUBLISHED_WITH_EXPLICIT_AUTHORIZATION
Support tickets, image attachments and webhooksDisponível para qualquer conta ativa com produto support e escopo support.manage. Imagens privadas usam upload multipart separado, download autenticado e nunca transitam em bytes/base64 nos webhooks. PUBLISHED_PRODUCTION_ONLY
Client webhooksEventos publicados: checkout.order.status_changed, financial.operation.status_changed, virtual_card.otp.received e os cinco eventos support.* da central de suporte. Não existe webhook público de ciclo de vida cripto nem de autorização, captura, estorno, reembolso ou chargeback de cartão virtual. PUBLISHED
Public MED/dispute APIDisputas são acompanhadas pelo painel e suporte; nenhuma rota pública deve ser presumida. NOT_PUBLISHED