Este guia é para plataformas (sistemas de gestão, PDVs, cardápios digitais, ERPs, e-commerces) que querem oferecer pagamentos Pix da Woovi para os seus clientes dentro do próprio sistema.
No modelo parceiro, a sua plataforma é a empresa parceira e cada cliente seu vira uma empresa afiliada, com conta Woovi própria. A plataforma cuida do cadastro e da experiência do cliente. A Woovi fica por baixo, como infraestrutura de pagamento.
Ao final, sua plataforma vai conseguir:
- Integrar com a Woovi
- Ter o modelo parceiro habilitado
- Cadastrar os seus clientes como afiliados
- Ativar as contas das afiliadas
- Permitir o saque das afiliadas
- Operar cobranças, estornos e repasses no dia a dia
Como o modelo funciona
- Cada afiliada tem a própria conta Woovi, no CNPJ dela. O dinheiro das vendas cai na conta da afiliada, não na conta da plataforma.
- A plataforma ganha em cada transação: você define uma taxa por afiliada, que é cobrada automaticamente em cada pagamento recebido e cai na sua conta de parceiro.
- Tudo pode ser feito via API: criar a afiliada, gerar as credenciais dela, criar cobranças e fazer os saques.
1. Integrar com a Woovi
- Crie a conta da sua plataforma na Woovi. Essa será a sua empresa parceira.
- Gere uma chave de API (AppID) com os escopos de parceiro: PARTNER_COMPANY_POST, PARTNER_COMPANY_GET e PARTNER_APPLICATION_POST.
- Faça os testes no ambiente de sandbox antes de ir para produção.
Dica: o modelo parceiro também precisa ser habilitado na sua conta de sandbox. Peça ao nosso time junto com a habilitação de produção.
2. Habilitar o modelo parceiro
O modelo parceiro é liberado pelo time da Woovi após uma análise do perfil da sua plataforma. Fale com a gente para solicitar.
Com o modelo liberado, aparece no painel o menu Minhas empresas, onde você acompanha todas as afiliadas.
Defina a sua taxa. Você pode configurar uma taxa por afiliada, somada à taxa da Woovi em cada transação. Esse valor é a receita da sua plataforma.
3. Cadastrar as afiliadas
Com o AppID da sua empresa parceira, crie cada cliente como afiliada:
- Via API: POST /api/v1/partner/company, enviando os dados da empresa (nome, CNPJ, site) e do usuário responsável (nome, e-mail, telefone e CPF).
- Em lote, pelo painel: para cadastrar muitas empresas de uma vez.
- Pelo link de afiliado: o próprio cliente se cadastra por um link seu.
A resposta do POST /api/v1/partner/company traz o linkOnboarding: é o link em que o cliente completa o cadastro da conta (dados da empresa e dos sócios).
O cliente já tem conta na Woovi? Nesse caso, fale com o nosso time antes de cadastrar. Cadastrar pela API cria uma empresa nova, e o vínculo de uma conta que já existe com a sua plataforma é feito por nós.
4. Ativar as contas
- Leve o cliente ao linkOnboarding. Você pode abrir o link em uma nova aba, redirecionar ou exibir dentro do seu sistema, inclusive sem a logo da Woovi.
- Acompanhe o status da afiliada com GET /api/v1/partner/company/{taxID} ou pelo menu Minhas empresas.
- Com a conta aprovada, gere as credenciais da afiliada com POST /api/v1/partner/application. A resposta traz o clientId e o clientSecret, que formam o AppID da afiliada.
- Cadastre o webhook da afiliada com o AppID dela, para receber os avisos de pagamento.
Importante: gere o AppID da afiliada depois que a conta dela estiver aprovada. O AppID é vinculado à conta da afiliada no momento em que é criado. Se ele for gerado antes, algumas consultas (como o extrato) não vão encontrar a conta.
Escopos do AppID da afiliada
No POST /api/v1/partner/application, informe em scopes só o que a sua plataforma vai usar. Os mais comuns:
| Para quê | Escopos |
|---|---|
| Cobranças | CHARGE_POST, CHARGE_GET, CHARGE_DELETE |
| Estornos | CHARGE_REFUND_POST |
| Webhooks | WEBHOOK_POST |
| Conta, extrato e transações | ACCOUNT_GET, STATEMENT_GET, TRANSACTION_GET |
| Saque | ACCOUNT_WITHDRAW_POST |
Escopos que movimentam dinheiro, como o de saque, exigem IP permitido. Cadastre o IP do seu servidor uma única vez na sua empresa parceira e ele passa a valer para todas as afiliadas.
5. Permitir o saque
O saldo das vendas fica na conta da afiliada. Para levar esse dinheiro para a conta bancária do cliente:
- Pela sua plataforma, via API: consulte a conta com GET /api/v1/account e solicite o saque com POST /api/v1/account/{accountId}/withdraw, usando o AppID da afiliada.
- Pelo painel Woovi: o próprio cliente pode sacar, se tiver acesso.
Pontos que valem para as regras do seu sistema:
- O saque vai para a chave Pix de saque cadastrada na conta da afiliada, normalmente o CNPJ dela.
- A gratuidade do saque depende do valor e da titularidade: saque para uma conta de mesma titularidade (o CNPJ da afiliada) segue a regra de isenção do plano, e saque para uma chave de outro titular (como o CPF de um sócio) é tarifado.
- Os saques têm limites por período, definidos conforme a análise da conta.
- Você também pode cobrar uma taxa sua sobre o saque, como faz na venda.
6. Operar no dia a dia
Cobrança no checkout
- O cliente final escolhe Pix no seu cardápio, loja ou PDV.
- A plataforma cria a cobrança com POST /api/v1/charge, usando o AppID da afiliada e um correlationID com o número do pedido.
- O QR Code é exibido para o cliente final.
- Quando o pagamento é confirmado, o webhook OPENPIX:CHARGE_COMPLETED chega com o correlationID, e a plataforma libera o pedido.
Estornos
Para devolver o valor de um pedido cancelado, use o estorno da cobrança, com o AppID da afiliada.
Para acompanhar o resultado do estorno, assine os webhooks PIX_TRANSACTION_REFUND_SENT_CONFIRMED (estorno concluído) e PIX_TRANSACTION_REFUND_SENT_REJECTED (estorno não realizado).
Eventos principais
| Evento | Quando acontece |
|---|---|
| OPENPIX:CHARGE_COMPLETED | Cobrança paga |
| OPENPIX:CHARGE_EXPIRED | Cobrança expirou sem pagamento |
| PIX_TRANSACTION_REFUND_SENT_CONFIRMED | Estorno concluído |
| PIX_TRANSACTION_REFUND_SENT_REJECTED | Estorno não realizado |
| OPENPIX:MOVEMENT_CONFIRMED | Saque concluído |
| OPENPIX:MOVEMENT_FAILED | Saque não realizado |
Acompanhando as afiliadas
No menu Minhas empresas, você vê as afiliadas, as cobranças, a conta, as integrações e os logs de webhook de cada uma.
Exemplo: plataforma de gestão para restaurantes
Um dos cenários mais comuns do modelo parceiro é o de sistemas de gestão para food service, com milhares de restaurantes na base. O fluxo costuma ser assim:
- No sistema da plataforma, o restaurante clica em ativar pagamentos Pix e informa o CNPJ.
- A plataforma cria a afiliada (POST /api/v1/partner/company) e abre o linkOnboarding para o restaurante completar o cadastro.
- Com a conta aprovada, a plataforma gera o AppID do restaurante (POST /api/v1/partner/application) e cadastra o webhook dele.
- A partir daí, cada pedido do cardápio digital ou do PDV vira uma cobrança Pix, e o pedido é liberado automaticamente quando o webhook de pagamento chega.
- O restaurante saca o saldo pela própria plataforma, que chama o saque via API, ou pelo painel Woovi.
- A plataforma recebe a taxa dela em cada transação, direto na conta de parceira.
Dúvidas ou erros na integração
Veja o artigo Erros comuns na integração de parceiros ou fale com o nosso time pelo chat.