Como cobrar a mensalidade dos seus afiliados via API (cardápio digital e parceiros)

Se você é um parceiro Woovi (por exemplo, uma plataforma de cardápio digital) e os restaurantes que usam a sua plataforma são afiliados à sua conta, você pode cobrar a mensalidade do seu sistema direto do saldo Woovi do afiliado, sem gerar boleto ou Pix para ele pagar.

Isso é feito com uma transferência interna pela API: o valor sai da conta do afiliado e entra na sua conta de parceiro, na hora.

Como funciona

1. O restaurante (afiliado) recebe os pagamentos dos clientes dele normalmente na conta Woovi.

2. No dia da cobrança, o seu sistema chama o endpoint POST /api/v1/transfer usando a sua chave de API (AppID de parceiro).

3. Você informa a chave Pix do afiliado como origem e a sua chave Pix como destino.

4. O valor da mensalidade é debitado do saldo do afiliado e creditado na sua conta.

Importante: como o valor é debitado da conta do afiliado, deixe essa cobrança prevista no contrato ou nos termos de uso da sua plataforma, informando valor e data da mensalidade.

Pré-requisitos

Antes de começar, confirme que:

• A sua empresa está cadastrada como parceira e o restaurante está afiliado a ela.

• A funcionalidade de transferência entre contas está habilitada na sua conta. Se não estiver, a API responde "Essa funcionalidade não está habilitada para sua empresa". Fale com o nosso suporte para ativar.

• A sua aplicação de API tem a permissão (escopo) de transferência e o IP do seu servidor está na lista de IPs permitidos da aplicação.

• Você sabe qual é a chave Pix da conta Woovi do afiliado (origem) e a chave Pix da sua conta (destino).

• As duas contas são contas Woovi.

Fazendo a cobrança

Endpoint: POST https://api.woovi.com/api/v1/transfer

Cabeçalho: Authorization: <seu AppID de parceiro>

Corpo da requisição:

{
  "value": 4990,
  "fromPixKey": "[email protected]",
  "toPixKey": "[email protected]",
  "correlationID": "mensalidade-restaurante-123-2026-10"
}

Resposta de sucesso (200):

{
  "transaction": {
    "value": 4990,
    "time": "2026-10-05T12:00:00.000Z",
    "correlationID": "mensalidade-restaurante-123-2026-10"
  }
}

Use um correlationID por mês para não cobrar duas vezes

Monte o correlationID com o afiliado e o mês de referência, por exemplo:

mensalidade-<id-do-restaurante>-<ano>-<mês> → mensalidade-restaurante-123-2026-10

A Woovi não aceita dois correlationID iguais. Se a sua rotina rodar de novo (por um timeout ou uma nova tentativa), a segunda chamada é recusada com "Uma transferência com o correlationID fornecido já existe" e o afiliado não é cobrado em dobro. Nesse caso, considere a mensalidade do mês como já paga.

Agendando a cobrança mensal

A Woovi não agenda essa transferência automaticamente: a recorrência fica no seu sistema. Uma forma simples:

1. Crie uma rotina (cron) que rode no dia da cobrança de cada afiliado.

2. Para cada afiliado com mensalidade a vencer, chame o POST /api/v1/transfer com o correlationID do mês.

3. Registre o resultado: sucesso, já cobrado (correlationID repetido) ou falha (veja abaixo).

4. Para as falhas por saldo insuficiente, agende novas tentativas nos dias seguintes, sempre com o mesmo correlationID do mês.

Erros mais comuns

Dúvidas frequentes

O afiliado vê essa cobrança?
Sim. Ela aparece no extrato do afiliado como uma transferência interna enviada, e no seu extrato como transferência interna recebida.

Existe tarifa?
Pode haver tarifa de transferência interna, conforme o plano da sua conta. A tarifa é cobrada da conta que faz a chamada (a sua). Fale com o suporte para mais detalhes.

Existe limite de valor?
Sim. A transferência respeita os limites de transferência da conta do afiliado e a reserva de segurança de saldo, se houver.

Posso estornar uma mensalidade cobrada por engano?
Sim. Faça uma transferência no sentido contrário, da sua conta para a conta do afiliado. Esse sentido precisa de uma liberação adicional: fale com o suporte para habilitar.

Para mais detalhes técnicos do endpoint, veja a documentação em developers.woovi.com.