MevvPos Documentation

Instalação

O MevvPos precisa de WordPress 6.0+, PHP 8.1+ e WooCommerce 9.0 ou mais recente. O WooCommerce é uma dependência obrigatória, declarada no cabeçalho do plugin: sem ele, o WordPress recusa a ativação, e em versões antigas do WordPress o plugin simplesmente não faz nada.

Envie o plugin em Plugins → Adicionar novo → Enviar plugin e ative-o.
Abra o MevvPos no menu lateral do admin. Também há um atalho dentro do WooCommerce, onde os lojistas costumam procurar as configurações de pagamento.
Na aba Geral, ligue a forma de pagamento e defina o título que o cliente verá na finalização da compra.
Em API do banco, escolha o seu banco e informe as credenciais que ele lhe deu.
Em Parcelamento e comissão, informe as suas taxas de parcelamento.
Teste com as credenciais de teste do seu banco antes de entrar no ar.

A edição gratuita não cria tabelas no banco de dados nem registra nenhuma tarefa agendada. Tudo vive nas opções do WordPress e nos metadados do pedido.

O Pro é um plugin separado, instalado ao lado do gratuito — não é um substituto dele. O plugin gratuito é publicado no WordPress.org, onde tudo o que é publicado pode ser redistribuído sob a GPL; manter o código pago no mesmo pacote o tornaria legalmente redistribuível por qualquer pessoa que apagasse as verificações de licença. A chave de licença é informada na aba Licença.

Abrir WooCommerce → Configurações → Pagamentos → MevvPos redireciona você para a tela do MevvPos. Isso é deliberado: há um único lugar para essas configurações, não dois que possam se contradizer.

Como funciona

Você define um ou mais registros de POS. Um registro de POS é o POS virtual de um banco: suas credenciais, o endereço do gateway, suas taxas de parcelamento.
No checkout, o cliente digita o cartão. Os seis primeiros dígitos — o BIN — identificam o banco que o emitiu.
O MevvPos consulta o BIN e envia o pagamento ao seu POS naquele banco, se você tiver um. Caso contrário, ele recai no seu POS padrão.
O parcelamento só é oferecido quando o cartão pertence ao próprio banco daquele POS, porque bancos não concedem parcelamento em cartões de outro banco.
O cliente passa pelo 3-D Secure no banco, e o banco retorna a um único endereço de callback no seu site.
A assinatura do retorno é verificada com a chave do POS que o pedido realmente usou, o pedido é concluído e o resultado é registrado.

O número do cartão, a validade e o CVV nunca são gravados no seu banco de dados nem na sessão do WooCommerce. Os únicos dados de cartão guardados são os seis primeiros dígitos e o nome do banco reconhecido.

Registros de POS

A barra de POS fica acima das abas e aparece em todas elas. Cada cartão mostra o banco, o número do estabelecimento e um selo quando algo exige sua atenção.

Padrão: O POS que recebe o pagamento quando nenhuma correspondência melhor é encontrada. Sempre existe exatamente um.
Inativo: Mantido, mas sem cobrar. Use isso em vez de apagar quando um POS está configurado mas ainda não está ativo no banco — do contrário, um cliente com o cartão daquele banco ficaria sem conseguir pagar.
Aguardando uma licença: O registro existe, mas está dormente porque a licença não está ativa. Nada foi apagado; ele retoma de onde parou quando a licença é renovada.
Os dados da API não foram informados: O registro ainda não tem número de estabelecimento.

Os bancos aparecem por uma faixa de cor em vez de um logotipo. Logotipos de banco são marcas registradas, e quinze deles são ao mesmo tempo exposição jurídica e manutenção permanente — você já sabe qual é o seu banco.

O último POS não pode ser excluído e o último habilitado não pode ser desligado. Para parar de aceitar pagamentos com cartão por completo, desligue a forma de pagamento na aba Geral.

A edição gratuita permite um POS. Registros extras são um recurso do Pro — e, por consequência, o roteamento por BIN também: com um único POS não há entre o que rotear.

API do banco — credenciais e o endereço do gateway

Banco: Escolha o banco em que seu POS está. Tanto o endereço do gateway quanto a lista de BINs usada para o parcelamento seguem essa escolha. Instituições ainda sem implementação aparecem com “— yakında” (em breve) e não podem ser selecionadas.
Número do estabelecimento (Client ID): O número de estabelecimento que o banco lhe deu.
Chave do estabelecimento (Store key): A chave de segurança do estabelecimento. Guardada como campo de senha; depois de salva, é exibida mascarada.
Gate URL: O endereço para o qual o formulário de pagamento envia os dados.
Ativar o modo de teste: Interrompe o redirecionamento automático para você inspecionar a requisição antes de ela ser enviada.

Deixar a Store Key em branco ao salvar significa “não altere”. Gravar o valor em branco apagaria a chave e sua loja pararia de aceitar pagamentos sem uma única mensagem de erro. A mesma regra vale para os outros campos secretos.

Algumas famílias precisam de credenciais extras, e o formulário só as mostra para o banco que você escolheu:

Garanti BBVA — Merchant ID, usuário de autorização, senha de autorização.
VakıfBank — Terminal No, e um endereço MPI (deixe vazio para usar o endereço de teste).
PayTR — Merchant Salt.
iyzico, Craftgate, Sipay — sem campos extras: a chave da API vai no Número do estabelecimento e o segredo na Chave do estabelecimento.

Essas credenciais extras entram na assinatura. Se uma faltar, a assinatura é calculada com um valor vazio e o banco recusa o pagamento em silêncio — sem erro, sem mensagem, apenas uma recusa.

Para os sete bancos NestPay, o endereço do gateway é preenchido a partir da sua escolha de banco, então você pode deixar o Gate URL vazio. Para os demais o campo não vem preenchido: informe o endereço que seu banco ou provedor forneceu, caso contrário o formulário de pagamento não tem para onde enviar.

As treze instituições suportadas

NestPay / Asseco (Payten): İş Bankası, Akbank, Halkbank, QNB, Şekerbank, TEB, Ziraat Bankası
Garanti GT3D: Garanti BBVA
PayFlex V4: VakıfBank
Instituições de pagamento: iyzico, PayTR, Craftgate, Sipay

Instituições sem implementação continuam na lista de bancos de propósito, marcadas com “— yakında”. Removê-las esconderia quais famílias de protocolo ainda faltam. Se a sua for uma delas, a aba Solicitação de banco é onde dizer isso.

Só a assinatura NestPay tem um teste de vetor de referência contra o exemplo publicado pelo próprio banco. Todos os outros provedores estão marcados como beta no próprio código: o fluxo está implementado conforme a documentação, mas ainda não foi verificado de ponta a ponta com uma conta de estabelecimento real naquela instituição. Esse rótulo permanece até que isso aconteça.

Instituições de pagamento não emitem cartões, então não têm lista de BINs. Você as seleciona como seu POS em vez de rotear para elas.

Roteamento baseado em BIN

Os seis primeiros dígitos de um cartão identificam o banco que o emitiu. O MevvPos compara exatamente esses seis dígitos.

Um instantâneo da tabela de BINs vem dentro do plugin — 1.449 BINs de 36 bancos na versão atual — de modo que o roteamento funciona offline, na edição gratuita, desde o momento da instalação.
O Pro a atualiza semanalmente a partir dos nossos servidores. A atualização é mesclada sobre a tabela empacotada em vez de substituí-la: uma resposta parcial ou vazia nunca deve deixar uma loja sem dados de BIN.
Uma resposta com menos de cem BINs é rejeitada como implausível e não é gravada.
Os conflitos — o mesmo BIN reivindicado por dois bancos — são resolvidos do nosso lado antes de a lista ser enviada. Uma loja que os resolvesse localmente poderia contar um cartão como “nosso” e roteá-lo para outro lugar ao mesmo tempo.

Um BIN não reconhecido nunca é recusado. Ele cai no seu POS padrão. Recusar um cartão que simplesmente não temos cadastrado seria perder uma venda para proteger uma tabela de consulta.

A mesma tabela responde a uma segunda pergunta, diferente, no checkout: este cartão é do próprio banco deste POS? É isso que decide se o parcelamento é oferecido — veja abaixo.

A exatidão dos BINs não é um recurso pago. O que o Pro paga é a atualidade, não a correção: a lista empacotada é a mesma lista, apenas congelada no momento do build.

Parcelamento e comissão

As taxas são definidas por POS, do pagamento à vista até doze parcelas, na aba Parcelamento e comissão. São porcentagens: escreva 5.50 para 5,5%.

0: A opção é exibida e nenhuma comissão é adicionada.
Vazio: A opção não é exibida de jeito nenhum. Vazio e zero não são a mesma coisa.

A comissão aparece no carrinho como uma taxa tributável chamada “N Taksit Komisyonu” (comissão de N parcelas), calculada sobre o total do carrinho incluindo frete e impostos.

O parcelamento só é oferecido em cartões emitidos pelo próprio banco daquele POS, e isso é imposto no servidor — não apenas escondido na interface. Um cartão de outro banco é forçado de volta ao pagamento à vista e a taxa é removida.

A edição gratuita mostra ao cliente no máximo três parcelas; o Pro eleva o teto a doze. O teto é aplicado em três pontos: a lista que o cliente vê, o valor que chega com o formulário e o valor enviado ao banco. Este último importa porque um valor escolhido enquanto a licença ainda era válida pode sobreviver na sessão.

O formulário de configurações sempre mostra os doze campos, qualquer que seja a sua licença. Se eles sumissem quando uma licença expirasse, salvar a página apagaria silenciosamente taxas que você já tinha informado. Os campos acima do seu limite são marcados como “Liberado no Pro” e os seus números são mantidos.

Não existe tabela de parcelamento fornecida pelo banco. As taxas são as que você informa, e a comissão de um pedido passado é calculada pela taxa que valia no dia da venda — mudar uma taxa hoje não reescreve o relatório de ontem.

O fluxo de pagamento e o tratamento do cartão

Todas as famílias passam pelo 3-D Secure. Não existe modo sem 3D nem configuração para desligá-lo.

Fluxo por formulário: NestPay, Garanti, PayTR e Sipay: o navegador envia um formulário assinado ao banco, o cliente se autentica, e o banco retorna ao seu site.
Fluxo por servidor: VakıfBank, iyzico e Craftgate: seu servidor conversa com o provedor, obtém a página 3-D, exibe-a e conclui a venda de servidor para servidor após a autenticação.

O banco sempre retorna a um único endereço no seu site: ?wc-api=mevvpos_callback. A assinatura desse retorno é verificada com a chave do POS que o pedido realmente usou, registrada no próprio pedido — com mais de um POS, verificar com a chave errada produz um erro de hash em cada pagamento.

O cartão nunca chega ao seu banco de dados. Ele fica no navegador pelo tempo do redirecionamento e é removido depois. Se não estiver lá quando a página de pagamento carregar — uma nova aba, um recarregamento, armazenamento desativado, uma volta a partir do banco — um formulário de cartão visível é exibido em vez de enviar campos vazios ao banco. O formulário de cartão é visível por padrão, de propósito: um fluxo de pagamento não pode depender de o JavaScript ter rodado.

Quando o banco aprova o pagamento, o pedido é concluído mesmo se o código de status 3-D for inesperado — uma nota no pedido registra a anomalia e pede que você a confirme na própria tela do banco. Se o banco diz aprovado, o cliente já foi cobrado; recusar isso significaria “seu cartão foi cobrado mas seu pedido falhou”.

Cada tentativa registra o POS usado, o banco e o BIN do cartão, a quantidade de parcelas e a taxa, o resultado, o código e a mensagem de resposta do banco, e as referências de autorização e de transação.

Relatórios

A aba Relatórios mostra a receita, as transações bem-sucedidas, a taxa de sucesso e a divisão entre pagamento à vista e parcelado, com um gráfico diário. As transações que ainda aguardam o retorno do banco são contadas à parte e ficam de fora da taxa de sucesso.

A edição gratuita relata uma janela fixa de 30 dias. O Pro acrescenta faixas de 7 / 30 / 90 dias e três detalhamentos:

Carga de parcelamento e comissão — quantidade, receita e encargo de comissão por faixa de parcelamento.
Detalhamento por POS e banco — receita, sucessos, falhas e taxa de sucesso para cada POS e para cada banco emissor.
Distribuição dos códigos de recusa — com exportação CSV. Um código de recusa que se repete aponta para algo que você pode consertar: saldo insuficiente é problema do cliente, mas erros de verificação 3-D e de configuração do POS são seus.

Os dados por trás dos relatórios são coletados pelo plugin gratuito, então o histórico continua se acumulando tenha você o Pro ou não. Tem de ser assim: dados passados não podem ser gerados retroativamente quando você faz o upgrade.

Uma loja recém-instalada não tem gráfico. O registro começa com o plugin, e a tela se preenche após a primeira tentativa de pagamento.

Solicitações de banco e suporte

Solicitação de banco: Lista todas as instituições que ainda não foram implementadas, com o motivo: ou a família de protocolo não foi determinada, ou a família é conhecida e estamos aguardando a documentação. Você pode abrir uma solicitação para uma delas, ou indicar uma instituição que não esteja na lista.
Suporte: Um assunto, o POS ou banco envolvido, o que acontece quando você faz o quê, e a mensagem de erro que o banco exibiu.

O formulário de suporte pede que você não inclua número de cartão nem código de segurança. Eles nunca são necessários para diagnosticar um problema de pagamento, e nenhum dado de pagamento ou de cartão é enviado com qualquer um dos formulários.

O plugin gratuito entra em contato com os nossos servidores apenas quando você aperta um desses botões. Nada é enviado em um cronograma e não há nenhuma chamada de licença na edição gratuita.

Free e Pro

A divisão está na quantidade, não na capacidade. As treze instituições, o 3-D Secure, o modo de teste, volume ilimitado de transações e o relatório básico de receita estão na edição gratuita.

Free: Um POS. Até três parcelas mostradas ao cliente. Um resumo de receita fixo de 30 dias. A tabela de BINs empacotada com o plugin.
Pro: Registros de POS ilimitados — e portanto roteamento por BIN. Até doze parcelas. Faixas de relatório e detalhamentos por POS, banco, parcelamento e código de recusa, com exportação CSV. Atualização semanal ao vivo dos BINs. Atualizações automáticas para o próprio plugin Pro.

Quando uma licença expira ou está ausente:

Sua loja continua recebendo pagamentos. Não há nenhuma verificação de licença no caminho do pagamento. Cortar a receita de uma loja não é uma forma aceitável de enviar um lembrete de renovação.
O POS padrão continua funcionando, incluindo o 3-D Secure e o modo de teste.
Os registros de POS extras ficam dormentes, mas nunca são apagados, credenciais incluídas. Eles voltam com a renovação.
O teto de parcelas volta a três. As taxas que você informou acima dele são mantidas, não apagadas.
Os relatórios voltam ao resumo de 30 dias. O histórico coletado não é apagado.
A atualização ao vivo dos BINs para; a tabela empacotada continua funcionando.

Se os nossos servidores estiverem inacessíveis, uma licença ativa continua funcionando por sete dias com base na última verificação bem-sucedida. Mas uma licença cuja própria data de validade já passou é lida como expirada de qualquer forma — do contrário, bloquear o nosso endereço seria uma maneira de estender uma licença por uma semana.

Quando algo não funciona

O banco recusa todos os pagamentos sem nenhuma mensagem útil: Quase sempre é a assinatura. Uma assinatura errada não gera erro em lugar nenhum — o banco simplesmente recusa. Verifique o número de estabelecimento, a chave da loja e quaisquer credenciais extras daquela família: todas entram na assinatura. Um teste útil é que os bancos respondem de forma diferente a um erro de assinatura e a um cartão inválido; receber uma mensagem de “cartão inválido” significa que sua assinatura está certa.
“Erro de hash” no retorno, com mais de um POS: O retorno é uma requisição separada, sem sessão. O MevvPos registra qual POS um pedido usou e verifica com aquela chave. Se você apagou o registro de POS pelo qual um pedido foi pago, a verificação recai no POS padrão e pode falhar.
O cliente chega a uma página de pagamento em branco, ou o botão Öde (Pagar) não faz nada: Um plugin de cache ou de otimização está adiando scripts. No LiteSpeed, exclua mevvpos, jquery e os scripts de front-end do WooCommerce da lista de atraso. O formulário de cartão é exibido por padrão para que o fluxo continue funcionando, mas o redirecionamento automático não.
O pedido fica “pendente” depois de um pagamento bem-sucedido: O banco ou o provedor não alcançou o endereço de callback. Verifique se ?wc-api=mevvpos_callback é acessível de fora — um modo de manutenção, uma restrição de IP ou uma barreira de login na frente do site vão bloqueá-lo.
O formulário de pagamento é enviado para a mesma página: O campo Gate URL está vazio para um banco cujo endereço não vem preenchido. Informe o endereço que seu banco ou provedor forneceu.
O modo de teste está ligado, mas o pagamento continua indo para o banco real: O modo de teste interrompe o redirecionamento automático e mostra a requisição; ele não reescreve o endereço do gateway para os bancos NestPay. Coloque o endereço de teste do seu banco em Gate URL enquanto estiver testando.
O parcelamento não aparece: Ou a taxa daquela quantidade está vazia em vez de zero, ou o cartão é de outro banco, ou você está acima do teto de três da edição gratuita.
Os cartões vão para o POS errado depois de uma atualização: Versões antigas traziam faixas de BIN escritas à mão que estavam parcialmente erradas. Verifique se cada POS está arquivado sob o banco em que ele realmente está.
A tela de administração parece sem estilo, ou uma correção não aparece: Um cache de navegador desatualizado. Recarregue a página contornando o cache.

Limites

A lista abaixo é deliberada. Nada disso é um bug.

Sem reembolsos ou cancelamentos pelo WordPress. O plugin não implementa a API de reembolso do WooCommerce e nenhum provedor traz uma chamada de reembolso. Faça o reembolso pela tela do seu próprio banco.
Somente lira turca. O código da moeda é fixo em todos os provedores; não existe configuração multimoeda.
Sem cartões salvos, sem tokenização, sem assinaturas nem pagamentos recorrentes.
Sem pré-autorização. Toda transação é uma venda direta.
Sem roteamento baseado em regras. O roteamento é só por banco emissor — não por valor, bandeira do cartão ou país.
O formulário de pagamento é escrito para o checkout clássico do WooCommerce. Nenhum componente separado para o Checkout em blocos vem no pacote.
O 3D Pay Hosting foi rejeitado de propósito. A página hospedada remove o escopo PCI, mas também remove o BIN e a tabela de parcelamento — e todo o valor deste plugin está no roteamento que eles tornam possível.
Sem editor de BIN. A tabela é gerenciada por nós e mesclada com a atualização ao vivo; não há tela para editá-la à mão.
Vinte e seis instituições estão listadas mas não implementadas. Elas continuam visíveis para que a lacuna fique visível.
Todos os provedores exceto o NestPay são autodeclarados beta até serem verificados de ponta a ponta com uma conta de estabelecimento real.
As abas ficam dentro da página. Os itens da barra lateral abrem a tela do MevvPos; troque de aba na própria página.

O que nunca é armazenado, de forma alguma: o número do cartão, a data de validade e o código de segurança. Os únicos dados de cartão guardados são os seis primeiros dígitos e o banco que eles identificam. Armazenar o código de segurança é proibido em qualquer circunstância, e mesmo mascarado ele revela seu comprimento.

De um único POS virtual a um cartão roteado para o banco que o emitiu.