Quickstart de integração

Uma chave Partner é multi-cliente por design. Diferente das chaves Merchant (acopladas a um único CNPJ), chaves Partner identificam o lojista alvo em cada requisição via cnpj ou location_id. Um único integrador atende dezenas de lojistas com uma única chave.

     ┌────────────────────────────────────────────────────────┐
     │              Sua organização (Partner)                 │
     │   org_xxx_partner • status=approved                    │
     └───────────────────────┬────────────────────────────────┘
                             │
        ┌────────────────────┼────────────────────┐
        ▼                    ▼                    ▼
   ┌─────────┐          ┌─────────┐          ┌─────────┐
   │ Loja A  │          │ Loja B  │          │ Loja C  │
   │ CNPJ Y  │          │ CNPJ Z  │          │ CNPJ W  │
   │ retail  │          │ recurr. │          │ hybrid  │
   └─────────┘          └─────────┘          └─────────┘
   cada location vinculada à sua org (e, se quiser, a outros integradores)

Por que este desenho: quando a Bumcash vincula uma location à sua org com a taxa de integração ativa, cada venda que o seu sistema faz ali te credita automaticamente 10% da taxa (sem reconciliação manual). Uma loja pode ter outras camadas — o caixa da Bumcash, o QR do cliente, outro integrador — e as vendas delas não são suas: você vê, recebe em webhook e é remunerado só pelo que passou pelas suas chaves. O lojista mantém a relação comercial direta com a Bumcash; você é um canal técnico.

• CNPJ da sua empresa aprovado pela Bumcash com organization_profile.type = partner e status = approved. Registro inicial via POST /v1/register/partner; aprovação manual pela equipe Bumcash.
• Termos de Uso aceitos no portal do integrador.
• Chave Partner de teste emitida (bmc_test_ptr_…) no portal, em Desenvolvedor → Chaves de API. Sua loja sandbox (CNPJ 33333333000191) já existe desde a aprovação e aparece em Desenvolvedor → Sandbox — não é preciso ter nenhum lojista cliente para testar.
• Só para produção: pelo menos um lojista cliente com location vinculada à sua org. Vínculo criado pela Bumcash quando o lojista assina sua integração; aparece em Clientes no portal do integrador.

Sua chave deve carregar as permissões: customers:register, customers:activate, payments:create, recurring:bill_payment, credits:mint, credits:burn, customers:query, transactions:list, earnings:read. Extratos de faturamento são do lojista; a sua parte está em /v1/earnings. Webhooks não exigem permissão — qualquer chave Partner válida pode gerenciar.

Toda escrita aceita um dos dois identificadores do lojista:

Mesmo endpoint usado pelos merchants diretos, com o lojista alvo identificado pelo CNPJ:

curl -X POST https://api-v2.bumcash.com.br/v1/customers/register \
  -H "Authorization: Bearer bmc_test_ptr_xxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "cnpj": "33333333000191",
    "customer_cpf": "11144477735",
    "customer_phone": "+5511987654321",
    "external_reference_id": "loja_a_subscription_42",
    "idempotency_key": "register_john_at_loja_a_2026-05-02"
  }'

{
  "id": "cust_a1b2c3d4e5f6",
  "cpf": "11144477735",
  "phone": "+5511987654321",
  "status": "pending",
  "registered_by_location_id": "loc_sandbox_org_3f9a2c1e",
  "external_reference_id": "loja_a_subscription_42",
  "registered_at": "2026-05-02T18:30:00.000Z"
}

2.A — Pagamento de fatura (lojistas recurrency ou hybrid)

curl -X POST https://api-v2.bumcash.com.br/v1/recurring/bill-payment \
  -H "Authorization: Bearer bmc_test_ptr_xxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "cnpj": "33333333000191",
    "customer_cpf": "11144477735",
    "bill_amount": 8990,
    "reference_external_id": "fatura_loja_a_2026_05",
    "activate": {
      "cpf": "11144477735",
      "phone": "+5511987654321"
    },
    "idempotency_key": "bill_loja_a_john_2026-05_v1"
  }'

2.B — Cashback em venda no PDV (lojistas retail ou hybrid)

curl -X POST https://api-v2.bumcash.com.br/v1/payments/pos-cashback \
  -H "Authorization: Bearer bmc_test_ptr_xxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "cnpj": "33333333000191",
    "customer_cpf": "11144477735",
    "sale_amount": 5000,
    "operator_external_id": "operador_caixa_3",
    "activate": {
      "cpf": "11144477735",
      "phone": "+5511987654321"
    },
    "idempotency_key": "sale_loja_a_2026-05-02_v1"
  }'

Em ambos os casos a resposta inclui customer_activation indicando se a transação efetivou a ativação ("activated") ou se o cliente já estava ativo ("already_active"). Sua taxa Partner (10%) é calculada automaticamente e contabilizada no feeSplit — consulta o acumulado no Passo 4.

Webhooks são partner-exclusive hoje. Você é o canal técnico, e a Bumcash quer que você saiba imediatamente quando uma transação confirma, um cliente ativa ou uma fatura é estornada.

curl -X POST https://api-v2.bumcash.com.br/v1/webhooks \
  -H "Authorization: Bearer bmc_test_ptr_xxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.suaempresa.com.br/bumcash/webhooks",
    "events": [
      "customer.activated",
      "recurring.bill_payment.succeeded",
      "recurring.bill_payment.refunded",
      "payments.pos_cashback.granted"
    ]
  }'

{
  "id": "wh_a1b2c3d4",
  "url": "https://api.suaempresa.com.br/bumcash/webhooks",
  "events": [
    "customer.activated",
    "recurring.bill_payment.succeeded",
    "..."
  ],
  "signing_secret": "whsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "created_at": "2026-05-02T18:30:00.000Z"
}

Cada evento entregue tem a forma:

{
  "id": "evt_a1b2c3",
  "type": "recurring.bill_payment.succeeded",
  "occurred_at": "2026-05-02T18:30:42.123Z",
  "location_id": "loc_sandbox_org_3f9a2c1e",
  "data": { /* … */ }
}

Retry policy: 5 tentativas com backoff exponencial (1m, 5m, 25m, 2h, 12h). Depois o evento entra em failed e fica disponível pra replay manual via POST /v1/webhooks/events/:id/replay. Histórico em GET /v1/webhooks/:id/attempts.

A cada transação em uma location integrationMode = "partner" vinculada a você, 10% da taxa do comerciante é destinada à sua org. Você consulta o acumulado por período:

curl 'https://api-v2.bumcash.com.br/v1/earnings?period_start=2026-05-01&period_end=2026-05-31' \
  -H "Authorization: Bearer bmc_test_ptr_xxxxxxxxxxxxxxxxxx"

{
  "period_start": "2026-05-01",
  "period_end": "2026-05-31",
  "integration_total": 12345,
  "recurrency_activator_total": 0,
  "retail_activator_total": 0,
  "grand_total": 12345,
  "line_items": [
    {
      "transaction_id": "rbp_xxxxxxxxxx",
      "location_id": "loc_sandbox_org_3f9a2c1e",
      "source": "integration",
      "amount": 899,
      "occurred_at": "2026-05-02T18:30:42.123Z"
    }
  ]
}

Valores em centavos. integration é a parcela da taxa Partner; recurrency_activator / retail_activator aparecem só se sua org também figurar como ativadora do customer (cenário raro).

Sua chave ptr_ também dá acesso à superfície de consulta usada por bots WhatsApp — GET /customers/lookup (por CPF ou telefone, com anti-enumeration), GET /customers/:phone/balance, POST /customers/:cpf/confirm-phone e o register do Passo 1. O vínculo segue a mesma regra desta página: sua chave enxerga os clientes registrados, ativados ou com transação (últimos 12 meses) nas locations que você integra. Para a configuração de cada lojista (taxas, expiração), use GET /v1/locations/lookup?cnpj=… — o /locations/me é exclusivo de chaves Merchant.

O passo a passo completo (estados do lookup, atestado de telefone, descoberta da rede) está no guia Bot WhatsApp via API, incluindo a seção Chaves Partner com as diferenças para integradores.

Ao aprovar sua organização, a Bumcash cria três lojas de teste vinculadas só à sua org — sua chave bmc_test_ptr_… as enxerga e nenhuma outra chave de integrador. Elas também aparecem no portal, em Desenvolvedor → Sandbox, com o location_id de cada uma.

• POST /v1/register/partner executado e organização aprovada pela Bumcash.
• Pelo menos um lojista com location vinculada à sua org em produção.
• Termos de Uso aceitos no portal do integrador.
• Chave de produção emitida e armazenada com segurança no vault (nunca em código-fonte).
• signing_secret do webhook em vault; receptor verifica HMAC-SHA256 + deduplica por event.id.
• idempotency_key derivada de algo estável da sua base (ex: bill_<lojista>_<contract>_<periodo>), não UUID aleatório por retentativa.
• Tratamento por error.code específico (não retentar 4xx exceto idempotency_conflict com nova chave).
• Conciliação contábil bate GET /v1/earnings contra sua base interna mensal.
• Validado em sandbox (sua loja 33333333000191 e as de recusa), depois trocada a chave para bmc_live_ptr_…