Pix Automático e contestações

Para o passo a passo, veja os guias Pix Automático e Contestações.

Pix Automático

Rota
POST /v1/subscriptions criar (devolve o QR Code de aprovação)
GET /v1/subscriptions listar (status, limit, starting_after)
GET /v1/subscriptions/{id} ver, com os ciclos cobrados em payments
POST /v1/subscriptions/{id}/charge cobrar um ciclo agora
POST /v1/subscriptions/{id}/cancel cancelar
POST /v1/subscriptions/{id}/simulate modo de teste: aprovar como se fosse o cliente

Criar

Campo
customer obrigatório name e document (CPF/CNPJ). Na Woovi, também address completo
frequency obrigatório weekly, monthly, quarterly, semiannually ou annually
amount centavos por ciclo. Sem ele, o valor é variável
first_amount centavos do primeiro ciclo, pago na aprovação. Padrão: amount
description o cliente vê no app do banco
start_date / end_date AAAA-MM-DD. Início padrão: hoje
retry true (padrão): o banco tenta de novo até 3 vezes em 7 dias
provider_account_id forçar uma conta
metadata copiado para cada ciclo

Objeto

{
  "id": "sub_8Hq...",
  "object": "subscription",
  "status": "pending",
  "amount": 4990,
  "first_amount": 4990,
  "frequency": "monthly",
  "start_date": "2026-10-18",
  "next_charge_date": "2026-11-18",
  "provider": "asaas",
  "approval": { "qr_code": "00020101...", "qr_code_base64": "iVBOR...", "url": null },
  "customer": { "id": "cus_...", "name": "Ana Lima", "document": "52998224725" }
}

status: pending (esperando o cliente), active, canceled, refused ou expired. approval só vem enquanto está pending.

Cobrar um ciclo

amount (obrigatório se o valor for variável) e due_date (AAAA-MM-DD, entre 2 e 10 dias úteis à frente). Devolve a cobrança criada. Na Woovi os ciclos são criados pela própria Woovi, então esta rota não se aplica.

Contestações

Rota
GET /v1/disputes listar (status=open traz as que esperam resposta; payment_id)
GET /v1/disputes/{id} ver
POST /v1/disputes/{id}/evidence responder: text e urls (links públicos das provas)
POST /v1/payments/{id}/simulate-dispute modo de teste: abrir uma contestação 
{
  "id": "dp_2Kd...",
  "object": "dispute",
  "kind": "med",
  "status": "open",
  "amount": 8990,
  "reason": "Golpe",
  "due_at": "2026-10-25T12:00:00.000Z",
  "payment_id": "pay_3kXy...",
  "provider": "woovi"
}

kind: med (Pix) ou chargeback (cartão). status: open, under_review, won, lost ou canceled.