Quickstart de integração

A integração de recorrência tem três momentos distintos no ciclo de vida do cliente:

Por que este desenho: o cliente assina o serviço na sua plataforma meses antes da primeira cobrança. Pré-cadastrá-lo na hora da assinatura cria o vínculo com sua loja imediatamente — sem disparar a validação oficial do CPF (que tem custo). A validação + ativação acontece quando a primeira fatura real chega: uma única chamada à API faz a ativação e o crédito de BMC na mesma transação.

• CNPJ aprovado pela equipe Bumcash (status approved no portal).
• Termos de Uso aceitos no portal.
• Pelo menos um local cadastrado com companyType = recurrency (ou hybrid) e integrationMode = self.
• Chave Merchant sandbox emitida no portal (bmc_test_mch_…). Para sandbox, use a base de fixtures pré-cadastrados — testes não disparam a validação real.

Sua chave deve carregar as permissões customers:register, customers:activate, recurring:bill_payment, customers:query,refunds:create, transactions:list, statements:read, earnings:read. São os defaults para um lojista recurrency/hybrid.

Chame este endpoint no momento em que o cliente assina o serviço na sua plataforma, não no momento da primeira cobrança. Cria o vínculo cliente↔loja com status = pending. Não dispara a validação oficial do CPF — esse passo fica para a primeira fatura.

curl -X POST https://api-v2.bumcash.com.br/v1/customers/register \
  -H "Authorization: Bearer bmc_test_mch_xxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "location_id": "loc_f1b2f0bf-7e8f-4a16-93da-1b6120e475e1",
    "customer_cpf": "71593209991",
    "customer_phone": "+5511987654321",
    "external_reference_id": "samuel_subscription_42",
    "idempotency_key": "register_samuel_2026-05-02"
  }'

Resposta — 201 Created

{
  "id": "cust_a1b2c3d4e5f6",
  "cpf": "71593209991",
  "phone": "+5511987654321",
  "status": "pending",
  "registered_by_location_id": "loc_f1b2f0bf-7e8f-4a16-93da-1b6120e475e1",
  "external_reference_id": "samuel_subscription_42",
  "registered_at": "2026-05-02T18:30:00.000Z"
}

Quando a primeira fatura real do cliente é paga, chame /recurring/bill-payment com o bloco activate. Numa única chamada o CPF é validado, o cliente passa para status = active, e o BMC é creditado.

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_f1b2f0bf-7e8f-4a16-93da-1b6120e475e1",
    "customer_cpf": "71593209991",
    "bill_amount": 8990,
    "reference_external_id": "fatura_2026_05",
    "activate": {
      "cpf": "71593209991",
      "phone": "+5511987654321"
    },
    "idempotency_key": "bill_samuel_2026-05_v1"
  }'

Resposta — 201 Created

{
  "id": "rbp_9f8e7d6c5b4a",
  "location_id": "loc_f1b2f0bf-7e8f-4a16-93da-1b6120e475e1",
  "customer_id": "cust_a1b2c3d4e5f6",
  "bill_amount": 8990,
  "coins_minted": 8990,
  "customer_activation": "activated",
  "created_at": "2026-05-02T18:35:00.000Z"
}

• Valores em centavos. R$ 89,90 = 8990. Para locais com recurrency_conversion_rate = 100 (default) é 1:1.
• customer_activation é uma enum: "activated" (esta chamada efetivou a ativação) ou "already_active" (cliente já estava ativo).
• O bloco activate é idempotente: cliente já ativo? Bloco vira no-op e o BMC é creditado normalmente.

Da segunda fatura em diante, omita o bloco activate. O cliente já está active.

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_f1b2f0bf-7e8f-4a16-93da-1b6120e475e1",
    "customer_cpf": "71593209991",
    "bill_amount": 8990,
    "reference_external_id": "fatura_2026_06",
    "idempotency_key": "bill_samuel_2026-06_v1"
  }'

{
  "id": "rbp_5b4a3f2e1d0c",
  "location_id": "loc_f1b2f0bf-7e8f-4a16-93da-1b6120e475e1",
  "customer_id": "cust_a1b2c3d4e5f6",
  "bill_amount": 8990,
  "coins_minted": 8990,
  "customer_activation": "already_active",
  "created_at": "2026-06-02T18:35:00.000Z"
}

Resumo dos códigos mais comuns desta trilha. Veja todos em referência de erros.

• GET /statements?location_id=… — extratos por período. Cada extrato traz total devido + contagem de transações.
• GET /statements/:id — line items para conciliar contra sua base.
• POST /refunds — estornar uma bill-payment específica. Requer refunds:create.
• GET /transactions — listagem das suas transações (mints, pagamentos, estornos).

Subscreva no portal em Webhooks → Endpoints:

customer.activated

Cliente passou de pending → active (na 1ª fatura com activate).

recurring.bill_payment.succeeded

BMC creditado com sucesso.

recurring.bill_payment.refunded

Estorno processado.

Para testar sem cadastrar nada, use estes identificadores que já existem no banco sandbox:

• Pré-cadastro chamado no signup do serviço (não no primeiro billing).
• idempotency_key derivada de algo estável da sua base (ex: bill_<contract_id>_<period>), não um UUID aleatório por retentativa.
• Webhook receptor com verificação HMAC + dedup por transaction_id.
• Tratamento de erros 4xx é específico por código (não retentar 4xx exceto idempotency_conflict com nova chave).
• Conciliação contábil bate GET /statements contra sua base de cobranças mensais.
• Validado em sandbox com fixtures, depois trocada a chave para bmc_live_mch_…