Conecte o MPGS ao WooCommerce

O plugin Genius Checkout para WooCommerce conecta uma conta compatível do Mastercard Payment Gateway Services a uma loja WordPress. Comerciantes podem utilizar MPGS Direct ou Hosted Checkout quando o modo selecionado, as credenciais e a moeda correspondem ao que foi liberado pelo banco ou provedor de pagamentos.

Este guia reflete a integração revisada em 4 de setembro de 2026.

#Identifique o modo do gateway

MPGS Direct e Hosted Checkout possuem fluxos de credencial e navegação no navegador distintos. Utilize o URL do gateway e o merchant ID fornecidos para a conta. Crie ou obtenha a autenticação API seguindo as instruções do portal do comerciante do banco.

Um comerciante Sagicor pode receber acesso ao MPGS, mas apenas o nome do banco não determina todos os campos de configuração. Use “seu banco, por exemplo Sagicor” ao dar instruções e siga o pacote real de credenciamento.

#Configure o MPGS no Genius Checkout

1. Acesse o merchant Genius Checkout vinculado à loja.
2. Selecione MPGS Direct ou MPGS Hosted Checkout.
3. Escolha o modo de teste.
4. Insira o merchant ID, autenticação e URL do gateway do mesmo ambiente.
5. Selecione uma moeda habilitada para a conta MPGS.
6. Para Hosted Checkout, adicione o logo do comerciante pela biblioteca de mídia. Use uma imagem quadrada de 1000 por 1000 pixels.
7. Salve e resolva todas as mensagens de validação.

#Conecte o WooCommerce

1. Instale o Plugin Genius Checkout para WooCommerce mais recente.
2. Acesse as configurações de métodos de pagamento do Genius Checkout.
3. Insira as credenciais de API do merchant configurado.
4. Autorize o domínio da loja.
5. Confirme o nome do comerciante e o modo de teste no status da conexão.
6. Selecione os métodos de pagamento disponíveis para o comprador.

A lista de permissões de domínio da loja protege a conexão de API. Para este redirecionamento via plugin, não deve ser necessário verificar o DNS.

Um comerciante com múltiplos gateways ativos pode exibir o MPGS como opção de pagamento distinta. As opções reais dependem da configuração vigente do merchant e da moeda do pedido.

O plugin atual é compatível com WordPress 6.0 ou superior, WooCommerce 8.0 ou superior, PHP 8.0 ou superior, WooCommerce High-Performance Order Storage e tanto o checkout clássico quanto em Blocks. Confira os requisitos atuais no WordPress.org antes de alterar um site em produção.

#Entendendo a navegação no Hosted Checkout

O MPGS Hosted Checkout é executado na página do provedor. Essa página pode bloquear a exibição em iframe. O WooCommerce já inicia um redirecionamento de topo, portanto não necessita da tela intermediária do HighLevel.

O comprador precisa conseguir cancelar, usar o botão Voltar do navegador e retornar à loja sem ser forçado a voltar ao MPGS. Em caso de cancelamento, o pedido WooCommerce deve permanecer disponível para nova tentativa.

#Execute a matriz de testes

Teste cada modo e ambiente configurado separadamente:

1. Pagamento único realizado com sucesso.
2. Pagamento recusado com uma mensagem de erro útil.
3. Cancelamento pelo comprador.
4. Retorno pelo botão Voltar do navegador saindo do MPGS Hosted Checkout.
5. Entrega duplicada de callback.
6. Pagamento com cartão salvo, se habilitado.
7. Renovação de assinatura e nova tentativa após falha, quando permitido.
8. Estorno ou anulação a partir de um pedido WooCommerce.

Registre o ID do pedido, a transação Genius Checkout, número do recibo, referência MPGS, horário UTC, modo e resultado. Nunca registre dados brutos do cartão.

#Pagamentos recorrentes

Um pagamento único pelo MPGS pode ser aprovado mesmo sem tokenização na conta do comerciante. O WooCommerce Subscriptions exige um token de pagamento reutilizável e um plano Genius Checkout com capacidade para pagamentos recorrentes.

Para períodos de teste com valor zero, confira se o WooCommerce consegue associar o método de pagamento da assinatura sem tentar cobrar um valor zero (caso não seja suportado). Teste a primeira renovação paga após o teste. Uma nova tentativa manual deve gerar uma nova transação Genius Checkout.

#Estornos e status do pagamento

O WooCommerce pode solicitar um estorno a partir da tela do pedido, mas a operação depende do status da transação. O Genius Checkout deve anular uma autorização não capturada quando o MPGS permite isso, e estornar um pagamento já capturado quando o MPGS suporta estornos.

A linha do tempo da transação deve registrar o pagamento original e cada evento posterior de captura, anulação ou estorno.

#Erros comuns do MPGS

HTTP 502 ao iniciar. Verifique a resposta do servidor de origem, host do gateway, modo, moeda e credenciais. O Genius Checkout registra um log operacional mesmo quando não há transação financeira criada.

Falha de autenticação. Confirme que o merchant ID e a autenticação da API correspondem ao URL e ao ambiente do gateway.

Hosted Checkout não abre. Certifique-se de que a conta tem permissão para Hosted Checkout e que o navegador não está tentando exibir a página do provedor em um iframe.

Renovação rejeitada. Verifique a tokenização, permissões de recorrência, capacidade do plano, titularidade do token e o erro seguro retornado à WooCommerce pela API.

#Use MPGS além do WooCommerce

Uma configuração de merchant MPGS aprovada pode ser integrada via Genius Checkout ao HighLevel, Ecwid, GiveWP, links de pagamento e QR codes e integrações customizadas com API. Teste cada conexão, pois navegação, callbacks e controle dos pedidos variam conforme a plataforma de origem.

#Fontes e próximos passos

• Visão geral da integração MPGS
• Visão geral da integração WooCommerce
• Visão geral Sagicor eCommerce
• Documentação Genius Checkout WooCommerce
• Genius Checkout for WooCommerce no WordPress.org
• Documentação da API Mastercard Gateway

Crie sua conta Genius Checkout ou agende uma revisão de configuração.