Trilha — Híbrido
Recorrência + Varejo
Para empresas com ambos os modelos no mesmo CNPJ — academias que vendem suplementos no balcão, condomínios com loja interna, operadoras com revenda de equipamentos. Você usa as duas trilhas, mas elas convergem na mesma carteira do cliente.
Modelo mental — uma carteira, duas vias
O modelo híbrido não é uma terceira API — é a combinação das duas trilhas, ambas creditando BMC para a mesma carteira do cliente. Você decide qual rota chamar com base no tipo da transação, não no perfil do cliente.
Configure seu local com companyType = hybrid no portal. A partir daí, sua chave Merchant ganha por padrão os verbos das duas trilhas (recurring:bill_payment, customers:register, customers:activate) — exceto payments:create, que segue como opt-in (peça habilitação se for usar a API para cashback PDV).
Quando usar cada rota
| Tipo da transação | Endpoint | Permissão |
|---|---|---|
| Mensalidade / fatura recorrente | POST /recurring/bill-payment | recurring:bill_payment |
| Plano de assinatura | POST /recurring/bill-payment | recurring:bill_payment |
| Venda à vista no PDV | POST /payments/pos-cashback | payments:create |
| E-commerce (cliente identificado por CPF) | POST /payments/pos-cashback | payments:create |
| Pré-cadastrar cliente antes da 1ª transação | POST /customers/register | customers:register |
Exemplo 1
Mensalidade da academia
O cliente paga R$ 89,90 da mensalidade. Você notifica via trilha recorrência — vide o quickstart de recorrência para o passo a passo completo.
curl -X POST https://api-v2.bumcash.com.br/v1/recurring/bill-payment \
-H "Authorization: Bearer bmc_test_mch_xxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"location_id": "loc_academia_centro",
"customer_cpf": "11122233344",
"bill_amount": 8990,
"reference_external_id": "fatura_2026_05",
"idempotency_key": "bill_marina_2026_05_v1"
}'Exemplo 2
Mesmo cliente compra suplemento no balcão
Marina (o mesmo CPF da mensalidade) compra um whey de R$ 80,00 na sua loja anexa. Você credita cashback BMC pela trilha varejo — vide o quickstart de varejo.
curl -X POST https://api-v2.bumcash.com.br/v1/payments/pos-cashback \
-H "Authorization: Bearer bmc_test_mch_xxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"location_id": "loc_academia_centro",
"customer_cpf": "11122233344",
"total_amount": 8000,
"operator_id": "op_balcao_01",
"idempotency_key": "venda_2026_05_15_balcao_99"
}'Não precisa enviar bloco activate aqui se Marina já foi ativada pela mensalidade — a primeira fatura paga já fez o trabalho. Se foi a primeira interação dela e você não tem certeza, envie o activate mesmo assim — é idempotente.
Atribuição: qual trilha 'ativou' o cliente?
Quando um cliente novo aparece na rede pela primeira vez, a trilha que o ativou ganha attribution — comissões da rede para vendas futuras desse cliente em outros lojistas, dentro de uma janela de 24 meses. Para um lojista híbrido, a trilha de ativação vai depender de qual evento aconteceu primeiro:
- Cliente assinou um plano antes de comprar no balcão? A primeira fatura paga ativa pela trilha de recorrência. Sua organização recebe attribution recurrency.
- Cliente comprou avulso antes de assinar? A primeira venda no PDV ativa pela trilha varejo. Attribution retail.
Os atributos são imutáveis uma vez setados. Não há "re-atribuição" se o cliente trocar de comportamento depois.
Conciliação
Use os mesmos endpoints das trilhas individuais — eles cobrem ambos os tipos de transação:
GET /statements— extratos de faturamento por período (cobre recurrency mints + retail cashback).GET /transactions— listagem unificada das suas transações, com discriminação por tipo (RECURRING_MINTvsPOS_CASHBACK).GET /earnings— saldo acumulado de attribution (recurrency-activator + retail-activator combinados).