Documentação para integradores

Integre sua operação
à rede Bumcash

Notifique pagamentos de faturas, credite cashback no PDV e reconcilie seus extratos via API. Comece pela trilha que corresponde ao seu modelo de negócio — em 10 minutos sua primeira transação está rodando.

Qual o seu modelo?

A Bumcash atende três modelos de lojista + um caminho para integradores. O fluxo é diferente para cada um — escolha abaixo a trilha que combina com você.

Recorrência

Telecom, academia, condomínio, convênio

Você fatura mensalmente. Cliente assina o serviço, paga as faturas, e a cada pagamento queremos creditar BMC na carteira dele. O fluxo recomendado é: pré-cadastrar o cliente na assinatura, ativar na primeira fatura, e a partir daí só notificar pagamentos.

Comece pela trilha de Recorrência

Varejo PDV

Lojas físicas e e-commerce

Você vende no balcão. Cliente compra em fiat e ganha cashback BMC proporcional. A ativação acontece na primeira compra numa única chamada à API.

Comece pela trilha de Varejo

Híbrido

Recorrência + varejo no mesmo CNPJ

Sua loja faz cobrança recorrente (academia mensal, plano de assinatura) e também vende avulso no PDV. Você usa as duas trilhas — recorrência para faturas, varejo para vendas avulsas — sobre a mesma carteira do cliente.

Veja como combinar as duas trilhas

Partner

Software houses, PDV, fintechs e integradores certificados

Você conecta a Bumcash em nome de múltiplos lojistas. Chaves Partner identificam o lojista alvo por CNPJ em cada chamada, e cada transação que passa por você credita automaticamente 10% da taxa à sua organização. Webhooks são partner-exclusive para você ter sinal em tempo real.

Comece pela trilha Partner

Guias por caso de uso

Casos de uso transversais que se combinam com qualquer trilha acima — sem mudar seu modelo de negócio, expandem o que dá pra fazer com a mesma chave de API.

Guia

Bot WhatsApp via API

Você já tem WhatsApp + bot próprios. A Bumcash entrega via API REST os dados que seu bot precisa: identificação não-destrutiva do cliente (com anti-enumeration), saldo + janela de expiração, rede de aceitação por geolocalização, e sua própria configuração.

Ver o guia

O que toda integração precisa saber

URL base: https://api-v2.bumcash.com.br/v1
Sandbox: Mesma URL, chaves com prefixo bmc_test_*. Não há domínio sandbox separado.
Autenticação: Header Authorization: Bearer bmc_…. Nunca exponha chaves no front-end.
Valores monetários: Sempre em centavos inteiros. R$ 1,00 = 100. Nunca use floats.
Idempotência: Toda escrita aceita idempotency_key. Mesma chave + mesmo payload = mesmo resultado por 90 dias.
Erros: Resposta padronizada com error.code específico. Veja a referência de códigos.