Integração WHMCS

O módulo de gateway do Vmix Pay para WHMCS deixa seus clientes pagarem as faturas do WHMCS por PIX (QR/copia-e-cola na própria fatura) e boleto. A partir da v1.1.0 ele emite um boleto híbrido: uma única cobrança que já traz o QR Code PIX impresso no boleto — o cliente paga pelo PIX ou pela linha digitável, e a fatura é baixada automaticamente.

Baixar o módulo

⬇ Baixar o módulo — vmixpay-whmcs-1.1.0.zip · código aberto (licença MIT), compatível com WHMCS 8.x e PHP 8.1+.

Atualize para a v1.1.0

Versões anteriores à 1.1.0 usam a cobrança dupla (POST /v1/charges/dual), que deixa de funcionar quando a plataforma suspende a emissão de PIX avulso (passa a responder 403 PIX_AVULSO_SUSPENDED). A v1.1.0 migra para o boleto híbrido e não é afetada. Faturas antigas já emitidas continuam sendo reconhecidas normalmente após a atualização.

O que você vai precisar

Uma conta no Vmix Pay (com KYC aprovado para sacar; receber já funciona antes), acesso de administrador ao seu WHMCS (8.x, PHP 8.1+) e o pacote do módulo (vmixpay-whmcs-x.y.z.zip).

A configuração tem dois lados: primeiro você cria as credenciais e o webhook no painel do Vmix Pay, depois preenche a configuração do módulo no WHMCS.

1. Configurar no painel do Vmix Pay

1. Crie uma credencial de API. No painel, vá em Tokens (/painel/tokens) e crie uma credencial com os escopos charges:create, charges:read e payments:read. Anote o Client ID e o Client Secret (o secret é exibido uma única vez).

   Para homologar antes de ir ao ar

   Crie também uma credencial na seção “Ambiente Teste” — ela opera no sandbox (banco simulado), para você testar o fluxo inteiro sem dinheiro real. Veja Ambiente de Testes.

2. Crie o webhook. Vá em Webhooks (/painel/webhooks) e crie um endpoint da conta apontando para a URL do callback do seu WHMCS:

   https://SEU-WHMCS/modules/gateways/callback/vmixpay.php

   Assine o evento payment.received e copie o segredo whsec_... (também exibido uma única vez). É com ele que o módulo valida a assinatura HMAC de cada notificação.

2. Instalar e configurar o módulo no WHMCS

1. Instale o módulo. Baixe o vmixpay-whmcs-1.1.0.zip e descompacte na raiz do seu WHMCS (ele cria modules/gateways/vmixpay.php e modules/gateways/callback/vmixpay.php).

2. Ative o gateway. Em Configuração → Gateways de Pagamento → Todos os Gateways de Pagamento, ative Vmix Pay (PIX/Boleto).

3. Preencha a configuração, campo a campo:

   Campo	O que é / onde pegar
   Client ID	da credencial de API (passo 1.1)
   Client Secret	da credencial de API (senha, criptografada pelo WHMCS)
   Webhook Secret	o whsec_... do webhook (passo 1.2)
   Account ID	opcional — a conta já vem do token; preencha só para forçar uma conta específica
   API Base URL	deixe o padrão https://api.vmixpay.com.br
   App Base URL	deixe o padrão https://app.vmixpay.com.br
   Métodos	PIX + Boleto (boleto híbrido) (padrão) ou Só Boleto
   Vencimento do boleto (dias)	prazo do boleto a partir de hoje (padrão 3)
   Campo do CPF/CNPJ	nome do custom field do cliente onde fica o CPF/CNPJ (necessário para boleto)
   Modo teste	marque enquanto homologa com credenciais de teste

   Boleto exige CPF/CNPJ + endereço

   O boleto — e o PIX impresso nele — precisa do documento (CPF/CNPJ) e do endereço do cliente. Se o cadastro estiver incompleto não há cobrança a gerar: o módulo mostra um aviso pedindo para completar o cadastro (CPF/CNPJ e endereço).

3. Homologar no sandbox

Antes de ir ao ar, valide o fluxo inteiro sem dinheiro real:

1. Configure o módulo com as credenciais de teste e marque Modo teste.

2. Gere uma fatura de teste no WHMCS e abra a tela de pagamento — o QR do PIX aparece e (se o cadastro estiver completo) o link do boleto.

3. Simule o pagamento chamando o endpoint de simulação com o token de teste:

   curl -X POST \
     https://api.vmixpay.com.br/v1/charges/{charge_id}/simulate-payment \
     -H "Authorization: Bearer SEU_ACCESS_TOKEN_DE_TESTE"

4. O Vmix Pay envia o webhook test:true e o módulo credita a fatura de teste.

5. Deu certo? Troque as credenciais para produção e desmarque Modo teste.

4. Como funciona / Solução de problemas

• PIX + Boleto (boleto híbrido): a fatura emite uma única cobrança — um boleto que já traz o QR Code PIX impresso nele. O cliente paga pelo PIX (copia-e-cola/QR) ou pela linha digitável do boleto; nos dois casos a mesma cobrança é baixada e a fatura é dada como paga uma vez.
• Confirmação: o pagamento é confirmado por webhook (payment.received, validado por HMAC). O módulo re-consulta a cobrança na API antes de creditar (verificar-não-confiar).

Sintoma	Causa provável
Callback retorna 401/403	Webhook Secret errado, ou o relógio do servidor fora de ±5 min
Cobrança não aparece (aviso “complete o cadastro”)	cliente sem CPF/CNPJ ou endereço completo (veja o Campo do CPF/CNPJ)
“Pagamento indisponível nesta moeda”	a fatura não está em BRL
Fatura de teste não credita	credenciais/segredo de teste, e Modo teste deve estar marcado

Segurança

O módulo é código aberto e auditável (licença MIT). As credenciais (Client Secret, Webhook Secret) ficam apenas na configuração do WHMCS, criptografadas — nunca no código — e o segredo do webhook garante, por assinatura HMAC, que só o Vmix Pay dá baixa nas suas faturas.