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

> Parceiros (como cardápios digitais) podem cobrar a mensalidade direto do saldo do afiliado com uma transferência interna pela API.

Fonte: https://ajuda.woovi.com/hc/duvidas-frequentes/articles/como-cobrar-mensalidade-dos-afiliados-via-api
Categoria: Parcerias
Atualizado em: 2026-10-05

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": "chave-pix-do-restaurante@exemplo.com",
  "toPixKey": "chave-pix-da-sua-plataforma@exemplo.com",
  "correlationID": "mensalidade-restaurante-123-2026-10"
}
```

| Campo           | Descrição                                                                          |
| --------------- | ---------------------------------------------------------------------------------- |
| `value`         | Valor da mensalidade **em centavos**. No exemplo, `4990` = R$ 49,90.               |
| `fromPixKey`    | Chave Pix da conta do **afiliado** (de onde sai o valor).                          |
| `toPixKey`      | Chave Pix da **sua conta** de parceiro (para onde vai o valor).                    |
| `correlationID` | Identificador único da cobrança, definido por você. Opcional, mas **recomendado**. |

**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

| Mensagem                                                    | O que significa                                                                                     | O que fazer                                                                       |
| ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| *Saldo insuficiente*                                        | O saldo disponível do afiliado não cobre a mensalidade (mais a tarifa da transferência, se houver). | Tente de novo em outro dia ou combine outra forma de pagamento com o restaurante. |
| *Chave Pix de origem não encontrada*                        | A chave do afiliado não existe ou não pertence a um afiliado da sua conta.                          | Confira a chave Pix e se o restaurante está afiliado a você.                      |
| *Chave Pix de destino não encontrada*                       | A chave de destino não é da sua conta.                                                              | Use uma chave Pix cadastrada na sua conta de parceiro.                            |
| *Uma transferência com o correlationID fornecido já existe* | Essa cobrança já foi feita.                                                                         | Não repita: a mensalidade do mês já está paga.                                    |
| *Essa funcionalidade não está habilitada para sua empresa*  | A transferência entre contas não está ativa.                                                        | Fale com o suporte Woovi.                                                         |
| *You are not allowed to transfer between these accounts*    | As contas de origem e destino não são da mesma instituição.                                         | Verifique se as duas são contas Woovi.                                            |

## 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](https://developers.woovi.com/en/api#tag/transfer-request-access/POST/api/v1/transfer).