Endpoints da API Bumcash

Notificação de pagamento de faturas. Trilha exclusiva para `companyType = recurrency` ou `hybrid`.

• POST/v1/recurring/bill-paymentperm: recurring:bill_payment (+ customers:activate se activate)

  Notifica o pagamento de uma fatura e credita BMC ao cliente. Aceita bloco `activate` para ativar o cliente na primeira fatura.

Cashback proporcional em vendas em fiat. Trilha para `companyType = retail` ou `hybrid`.

• POST/v1/payments/pos-cashbackperm: payments:create (+ customers:activate se activate)

  Credita cashback BMC numa venda no PDV. Aceita bloco `activate` para ativar o cliente na primeira compra.

• POST/v1/payments/coin-quoteperm: payments:create

  Autoriza o uso do saldo do cliente numa venda: confere CPF + data de nascimento e devolve a divisão `coin_amount`/`cash_amount`. Não debita — cobre o `cash_amount` e depois debite o `coin_amount` via `POST /v1/payments` (que devolve um `pay_…` estornável, ao contrário de `credits/burn`). É o passo que o PDV físico usa antes de passar o cartão. Limitado pelo `coin_acceptance_rate` do local e pelo saldo do cliente, o que for menor.

• POST/v1/paymentsperm: payments:create

  Pagamento com saldo BMC do cliente (consumo de moeda). Envie `coin_amount` de um `coin-quote` anterior para debitar exatamente o valor já descontado no balcão, e `allow_partial` para aceitar saldo abaixo do teto. Devolve um `pay_…` estornável. Reusar a `idempotency_key` com parâmetros diferentes retorna `409 idempotency_conflict` com o `payment_id` do pagamento original.

• POST/v1/payments/:id/reverseperm: refunds:create

  Estorna um pagamento com moeda: devolve o saldo ao cliente e marca o pagamento como `reversed`. Use quando a venda correspondente for cancelada. Idempotente — estornar duas vezes não credita duas vezes. O razão é append-only: o estorno entra como lançamento espelho, o original não é apagado.

• POST/v1/payments/pos-cashback/:id/reverseperm: refunds:create

  Estorna um cashback concedido: retira as moedas do cliente e cancela a cobrança daquela venda — sem isso o lojista é faturado por uma venda cancelada. O `id` é o lançamento `txn_…` devolvido por `pos-cashback`. Idempotente e append-only, como o estorno de pagamento. Recusa com `insufficient_balance_for_reversal` se o cliente já gastou as moedas, e `cashback_already_settled` se a venda já entrou num ciclo fechado.

• GET/v1/payments/:idperm: transactions:list

  Detalhe de um pagamento específico.

• GET/v1/paymentsperm: transactions:list

  Listagem paginada de pagamentos do seu escopo.

Pré-cadastro e consulta. Cross-cutting — usado por ambas as trilhas.

• POST/v1/customers/registerperm: customers:register

  Pré-cadastra cliente em status `pending` antes da primeira fatura/compra (não dispara validação oficial).

• GET/v1/customers/lookupperm: customers:query

  Resolve cliente por CPF ou phone (XOR). Sem efeito colateral. Lookup por phone tem três estados com anti-enumeration — phone de cliente de outro merchant e phone inexistente devolvem a mesma resposta bit-a-bit.

• GET/v1/customers/:phone/balanceperm: customers:query

  Saldo + tier + janela de expiração (7d/30d). Requer vínculo com caller + telefone verificado nos últimos 12 meses; senão 403 `phone_verification_stale`. Aceita `?cpf=` como variante para ignorar o guard de phone.

• POST/v1/customers/:cpf/confirm-phoneperm: customers:register

  Renova o atestado de telefone (`phoneVerifiedAt`). Caller sem vínculo recebe a mesma 404 que CPF inexistente. Phone já atrelado a outro cliente → 409 sem identificar o outro.

Descoberta da rede de aceitação e configuração do próprio merchant. Endpoints transversais — qualquer trilha pode consumir.

• GET/v1/network/locations

  Lojas que aceitam Bumcash, filtrável por geo (Haversine, `near=lat,lng` + `radius_km`), cidade/UF, categoria e `company_type`. Recurrency excluída por default (sem balcão). Geo ordena por distância; modo lista pagina por cursor. Cada item traz `logo_url` (com fallback para o logo do lojista); `compact=true` achata `address`/`operating_hours` em strings para templates de bot WhatsApp.

• GET/v1/locations/me

  Configuração do próprio merchant — `pos_cashback_rate` (cashback), `coin_acceptance_rate` (aceite de moeda, depreciado para cashback), `recurrency_conversion_rate`, `credit_expiration_days`, `billing_cycle` por location. Exclusivo `mch_`; chaves Partner recebem 403 `wrong_scope`.

• GET/v1/locations/lookup

  Par do `/me` para integradores: resolve UMA location por `?cnpj=` e retorna os mesmos campos de configuração. Busca restrita às locations vinculadas ao integrador — CNPJ fora do escopo retorna 404 `location_not_found` (não 403); CNPJ ambíguo no escopo retorna 409 `location_ambiguous`. Exclusivo `ptr_`; chaves Merchant recebem 403 `wrong_scope`.

Extratos, ganhos, transações. Cross-cutting — todos os tiers Merchant + Partner.

• GET/v1/statementsperm: statements:read

  Extratos de faturamento por período. Somente chaves Merchant — Partner lê a própria parte em /v1/earnings.

• GET/v1/statements/:idperm: statements:read

  Detalhe de um extrato com line items para conciliação.

• GET/v1/earningsperm: earnings:read

  Saldo acumulado como ativador da rede no período.

Registro e diagnóstico dos seus endpoints. Aberto a chaves Partner e Merchant — cada chave enxerga e gerencia apenas os endpoints da própria organização. A entrega já considerava os dois: um evento é enviado tanto ao integrador do local quanto ao lojista dono dele.

• POST/v1/webhooks

  Registra um endpoint para receber eventos em tempo real. `signing_secret` retornado apenas uma vez — para trocá-lo, remova o endpoint e crie outro.

• GET/v1/webhooks

  Lista os endpoints registrados pela sua organização.

• DELETE/v1/webhooks/:id

  Remove um endpoint. Eventos pendentes deixam de ser tentados.

• GET/v1/webhooks/:id/attempts

  Histórico de tentativas de entrega — útil para debugar falhas.

• POST/v1/webhooks/events/:eventId/replay

  Re-tenta a entrega de um evento que entrou em `failed`.

• GET/v1/webhooks/event-types

  Lista canônica dos eventos disponíveis para subscrição.

Reservado a chaves Partner (`ptr_`). Cobre dois capability-sets: (1) endpoints exclusivos como credits mint/burn; (2) endpoints transversais (customers, payments, recurring) que **exigem** `cnpj` ou `location_id` no payload — onde chaves Merchant inferem o local automaticamente. Veja a [Trilha Partner](/developers/partner/quickstart).

• POST/v1/credits/mintperm: credits:mint

  Emite BMC ao cliente em nome de um lojista. Identifique o lojista por `cnpj` ou `location_id`.

• POST/v1/credits/burnperm: credits:burn

  Resgata BMC do cliente em nome de um lojista.

• POST/v1/credits/batch-mintperm: credits:mint

  Emissão em lote — útil para sincronização de bases.