API BravexPay
Voltar

Documentação oficial da API pública

Esta documentação reflete o comportamento atual do sistema. Os endpoints públicos ativos são de cash-in e webhook de adquirente. O roteamento de adquirente usa failover automático por usuário/método quando configurado no painel.

Base URL: https://brbet777.fun/api Webhook base: https://brbet777.fun/webhooks/acquirer/{acquirer_slug} Moeda padrão: BRL

Segurança obrigatória

Antes de ir para produção, valide estes pontos:

  • Use HTTPS em toda chamada e nunca exponha client_secret no frontend/browser.
  • Restrinja IPs permitidos da integração no painel (whitelist).
  • Guarde credenciais em variável de ambiente/cofre, nunca em código fonte.
  • Valide assinatura de webhook e recuse payload sem assinatura válida.
  • Monitore respostas 401, 429 e 503 para contingência.
O middleware bloqueia a credencial por 15 minutos após 5 tentativas de segredo inválido.

Autenticação

As rotas /api/cash-in aceitam credencial de integração via header ou Basic Auth. Se o usuário já estiver logado por sessão, o mesmo middleware também aplica validação de IP.

Opção A: headers X-Client
Headers 
Content-Type: application/json
Accept: application/json
X-Client-Id: seu_client_id
X-Client-Secret: seu_client_secret
Opção B: Basic Auth
Header Authorization 
Authorization: Basic base64(seu_client_id:seu_client_secret)
Accept: application/json
Não existe fluxo OAuth público em /oauth/token. A autenticação oficial da API é via chave de integração.

POST /api/cash-in

Cria uma transação de entrada e processa no adquirente elegível.

Endpoint 
POST https://brbet777.fun/api/cash-in
Campo Tipo Obrigatório Observação
amount number Sim Valor entre 0.01 e 100000.
payment_method string Sim pix, boleto, credit_card, debit_card, crypto.
payment_acquirer_id integer Não Preferência de adquirente. Se indisponível/inválido, o sistema usa failover.
description string Não Texto livre (máx. 255).
integration_key_id integer Não Opcional; quando omitido, o middleware usa a credencial autenticada.
customer_data object Sim Dados do pagador.
customer_data.name string Sim Nome completo.
customer_data.email string Sim Email válido.
customer_data.document string Sim CPF/CNPJ.
customer_data.phone string Não Telefone do cliente.
payment_data object Não Campos específicos por método/adquirente (detalhes abaixo).
split_rules array Não Opcional. Regras de split (em %) para dividir o recebimento entre múltiplos recebedores. O formato do item pode variar por adquirente.
split array Não Alias alternativo de split_rules. O backend normaliza os dois formatos.
metadata object Não Metadados livres para rastreio interno.
A resposta retorna transaction (registro interno) e acquirer_response (payload mapeado do adquirente).
Exemplo mínimo PIX 
{
  "amount": 150.90,
  "payment_method": "pix",
  "description": "Recarga via PIX",
  "customer_data": {
    "name": "Joao Silva",
    "email": "joao@empresa.com",
    "document": "12345678909",
    "phone": "11999999999"
  }
}

PIX, boleto, cartão e crypto

O método aceito depende do adquirente ativo para o usuário e da configuração em admin. Matriz atual por integração nativa:

Adquirente (slug) PIX Boleto Cartão Crypto
voltpay Sim Não Não Não
voltpay_black Sim Não Não Não
medusapayments Sim Não Não Não
pushinpay Sim Sim Não Não
efi Sim Sim Sim (credit_card/debit_card) Não
facilitapay Sim Sim Não Sim
mystick Sim Não Não Não
woopi Sim Não Não Não
suitpay Sim Sim Sim (credit_card/debit_card) Não
vulcapay Sim Não Não Não
bspay Sim Não Não Não
pixup Sim Não Não Não

Exemplos práticos de payment_data por método:

Boleto (exemplo completo para PushInPay) 
{
  "amount": 250.00,
  "payment_method": "boleto",
  "customer_data": {
    "name": "Maria Souza",
    "email": "maria@empresa.com",
    "document": "12345678909",
    "phone": "11988887777"
  },
  "payment_data": {
    "boleto": {
      "due_date": "2026-03-15",
      "payer_address_zipcode": "01310100",
      "payer_address_public_place": "Av Paulista",
      "payer_address_neighborhood": "Bela Vista",
      "payer_address_number": "1000",
      "payer_address_city": "Sao Paulo",
      "payer_address_state": "SP"
    }
  }
}
Cartão (EFI) 
{
  "amount": 89.90,
  "payment_method": "credit_card",
  "customer_data": {
    "name": "Cliente Cartao",
    "email": "cliente@empresa.com",
    "document": "12345678909",
    "phone": "11977776666"
  },
  "payment_data": {
    "payment_token": "tok_xxxxxxxxx",
    "installments": 1,
    "billing_address": {
      "street": "Rua A",
      "number": "123",
      "neighborhood": "Centro",
      "zipcode": "01001000",
      "city": "Sao Paulo",
      "state": "SP"
    }
  }
}
Crypto cash-in (FacilitaPay) 
{
  "amount": 500.00,
  "payment_method": "crypto",
  "customer_data": {
    "name": "Cliente Crypto",
    "email": "crypto@empresa.com",
    "document": "12345678909"
  },
  "payment_data": {
    "subject_id": "SEU_SUBJECT_ID",
    "from_bank_account_id": "UUID_ORIGEM",
    "to_bank_account_id": "UUID_DESTINO",
    "currency": "BRL",
    "exchange_currency": "USD"
  }
}
Campos exatos podem variar por adquirente. Em caso de 422, valide o corpo retornado em messages ou error.

Split

Para dividir o valor do pagamento entre múltiplos recebedores, envie split_rules (ou split). Cada item define o usuário/recebedor e o percentual (%).

  • A soma dos percentuais deve ser ≤ 100.
  • O restante (se houver) normalmente fica com o recebedor principal (depende do adquirente).
  • Campos do item podem variar por adquirente (ex.: recipient_id).
Exemplo de requisição com split_rules 
{
  "amount": 1000.00,
  "payment_method": "pix",
  "customer_data": {
    "name": "Pagador Split",
    "email": "split@empresa.com",
    "document": "12345678909"
  },
  "split_rules": [
    {
      "recipient_id": "SUBCONTA_A",
      "percentage": 70
    },
    {
      "recipient_id": "SUBCONTA_B",
      "percentage": 30
    }
  ]
}
Você pode usar split como alias de split_rules.

GET /api/cash-in

Lista as transações de cash-in da credencial autenticada, com paginação.

Endpoint 
GET https://brbet777.fun/api/cash-in
Query param Tipo Descrição
statusstringFiltra por status (PENDING, PAID, etc).
payment_methodstringFiltra por método.
date_fromYYYY-MM-DDData inicial (inclusive).
date_toYYYY-MM-DDData final (inclusive).
min_amountnumberValor mínimo.
max_amountnumberValor máximo.
per_pageintegerTamanho da página (máximo 100, padrão 20).
Exemplo de resposta 
{
  "success": true,
  "data": {
    "transactions": [
      {
        "id": 1532,
        "order_id": "CASHIN_67ac56f3ca69f_1739446313",
        "status": "PAID",
        "amount": "150.90",
        "payment_method": "PIX"
      }
    ],
    "pagination": {
      "current_page": 1,
      "per_page": 20,
      "total": 1,
      "last_page": 1,
      "has_more": false
    }
  }
}

GET /api/cash-in/{transactionId}

Consulta uma transação por order_id ou por id numérico.

Endpoint 
GET https://brbet777.fun/api/cash-in/{transactionId}
Se a transação estiver PENDING ou PROCESSING, o backend consulta o adquirente para atualizar status na hora.

Webhook de adquirente

Endpoint público usado pelos adquirentes para atualização de status. A validação de assinatura é obrigatória (exceto integrações configuradas para ignorar assinatura em ambiente de teste).

Endpoint 
POST https://brbet777.fun/webhooks/acquirer/{acquirer_slug}
Header/campo lido Uso
X-SignatureAssinatura primária.
X-Webhook-SignatureAlternativa comum em gateways.
X-Hub-Signature / X-Hub-Signature-256Compatibilidade.
X-Efi-SignatureHeader específico da EFI.
signature / md5 no payloadFallback para integrações legadas.
Nunca confie em webhook sem assinatura válida. O endpoint retorna 401 para assinatura ausente/inválida.

Status e erros comuns

HTTP Quando acontece Ação recomendada
201 Cash-in criado e enviado ao adquirente. Persistir order_id e acompanhar por webhook/status.
401 Credencial inválida/inativa/expirada ou webhook sem assinatura. Revalidar chaves e segredo; revisar assinatura.
403 IP não autorizado para a credencial/usuário. Ajustar whitelist de IP.
404 Transação não encontrada. Conferir identificador enviado.
422 Validação ou limite de valor/acquirer elegível. Corrigir payload e limites no admin.
429 Rate limit excedido ou credencial bloqueada por tentativas inválidas. Respeitar retry_after e implementar backoff.
503 Todos adquirentes elegíveis indisponíveis. Tentar novamente com retentativa exponencial.

Status de transação mais usados: PENDING, PROCESSING, PAID, FAILED, CANCELLED, REFUNDED.

Checklist de produção

  • Confirmar adquirentes ativos por usuário e método (PIX/boleto/cartão/crypto).
  • Testar fluxo ponta a ponta: criar, receber webhook, conciliar status final.
  • Configurar monitoramento de logs cashin, cashout e webhook.
  • Definir retentativa para 429/503 com backoff.
  • Versionar contrato de payload interno da sua aplicação para evitar quebra de integração.
cURL de referência (PIX) 
curl -X POST 'https://brbet777.fun/api/cash-in' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'X-Client-Id: seu_client_id' \
  -H 'X-Client-Secret: seu_client_secret' \
  -d '{
    "amount": 120.50,
    "payment_method": "pix",
    "description": "Pedido 0001",
    "customer_data": {
      "name": "Joao Silva",
      "email": "joao@empresa.com",
      "document": "12345678909"
    }
  }'

Documento mantido para o estado atual do sistema BravexPay. Atualize este arquivo quando houver mudança de endpoint, autenticação ou contrato.