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 operação. O caminho de integração é 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

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.