MPGS para HighLevel: guia de integração Direct e Hosted Checkout

O Genius Checkout conecta uma conta compatível do Mastercard Payment Gateway Services ao HighLevel como provedor de pagamento personalizado. O comerciante mantém seu banco e relação com o MPGS. O Genius Checkout cria a sessão de pagamento, gerencia a transferência da transação e retorna o resultado ao HighLevel.

Este guia reflete a implementação do Genius Checkout revisada em 4 de setembro de 2026. Confirme URLs do gateway, moedas, tokenização e permissões de transação com o banco ou provedor que emitiu a conta MPGS.

O comerciante controla sua marca no Genius Checkout e os métodos de pagamento ativados. O provedor determina quais operações do gateway a conta pode realizar.

#Identifique a conta MPGS antes da configuração

Bancos e provedores emitem contas MPGS com um Merchant ID, host regional do gateway e detalhes de autenticação. Um portal bancário com marca pode usar tecnologia MPGS, mas somente o nome do portal não confirma o modo correto do Genius Checkout.

Verifique no material de boas-vindas e portal do gateway:

• Merchant ID.
• URL base do gateway ou região.
• Senha de API ou credenciais de operador para Direct.
• Permissões de Hosted Checkout e configurações do comerciante para HPP.
• Separação entre teste e produção.
• Moedas habilitadas.
• Permissões de tokenização e pagamentos recorrentes.

Ao explicar quem fornece acesso ao MPGS, use "seu banco, por exemplo, Sagicor". Não afirme que um banco usa MPGS para todos os comerciantes ou países, a menos que o banco confirme essa relação para a conta.

#Direct e Hosted Checkout são integrações distintas

Os modos podem atingir a mesma conta, mas utilizam requisições e fluxos diferentes para o comprador.

O conjunto de credenciais do comerciante define qual modo pode ser ativado. Uma senha de API não substitui o provisionamento do Hosted Checkout, e a configuração de página hospedada não habilita Direct.

#Como o pagamento HighLevel percorre o processo

O HighLevel envia os campos de pedido e comprador suportados ao Genius Checkout. O Genius Checkout cria uma sessão de checkout única e seleciona a rota MPGS configurada para a moeda da transação.

No Hosted Checkout, o comprador é direcionado à página MPGS. Páginas de fornecedores podem bloquear carregamento dentro de iframes de terceiros; o Genius Checkout pode utilizar redirecionamento seguro em primeiro plano e retornar o resultado ao HighLevel.

No Direct, o Genius Checkout coordena o pagamento e a autenticação do cartão conforme o fluxo configurado. A plataforma registra a resposta do provedor, gera o histórico da transação e informa o desfecho ao HighLevel.

#Configure MPGS no Genius Checkout

1. Acesse Gateways no comerciante correto dentro do Genius Checkout.
2. Selecione MPGS Direct ou MPGS Hosted Checkout.
3. Escolha o modo de teste ou produção.
4. Informe o Merchant ID, credenciais de autenticação e URL do gateway necessários para o modo ativo.
5. Selecione apenas as moedas habilitadas pelo seu banco ou provedor.
6. Adicione o logo do Hosted Checkout pela biblioteca de mídia ao usar HPP. Uma imagem quadrada de 1000 x 1000 pixels permite redimensionamento adequado.
7. Salve e resolva todas as mensagens de validação apresentadas.

Utilize os dados emitidos para o modo e ambiente MPGS selecionados. Um gateway de teste com credenciais de produção apresentará falha.

#Conecte o local HighLevel

1. Acesse o local HighLevel responsável pelos produtos e pagamentos.
2. Instale ou abra o Genius Checkout no HighLevel App Marketplace como provedor de pagamento personalizado.
3. Autorize o comerciante Genius Checkout desejado.
4. Confirme o nome do comerciante exibido na conexão.
5. Adicione o Genius Checkout a um produto de teste controlado.
6. Execute separadamente os testes de pagamento avulso e recorrente.

Nome, e-mail, telefone, endereço, referência do pedido e outros campos suportados podem ser enviados ao Genius Checkout quando informados pelo HighLevel. A integração não deve criar dados de cliente ausentes.

#Teste todo o fluxo de retorno

Registre para cada teste: pedido do HighLevel, transação do Genius Checkout, recibo, referência MPGS, horário UTC, modo, ambiente e resultado.

Execute estes casos:

1. Pagamento aprovado.
2. Pagamento recusado.
3. Cancelamento do comprador na página MPGS.
4. Ação "Voltar" do navegador a partir do Hosted Checkout.
5. Retorno bem-sucedido para a confirmação do HighLevel.
6. Pagamento com cartão salvo, se a tokenização estiver habilitada.
7. Ativação de assinatura e renovação iniciada pelo comerciante, se pagamentos recorrentes estiverem ativos.
8. Estorno ou anulação a partir do sistema operacional de rotina.

Os controles de Voltar e Cancelar do Hosted Checkout devem permitir a saída do comprador. Um loop de retorno que direciona novamente ao MPGS precisa ser ajustado antes do lançamento.

#Diagnóstico para “Não foi possível iniciar o pagamento” ou HTTP 502

Um HTTP 502 na rota inicial do MPGS indica falha integração/upstream, não uma reprovação da transação. Verifique o log da API do Genius Checkout e o correlation ID, então confirme:

• O comerciante possui configuração MPGS ativa no modo selecionado.
• O URL do gateway pertence ao mesmo ambiente das credenciais.
• A moeda está ativada no Genius Checkout e no MPGS.
• O Merchant ID não tem espaços ocultos.
• Existem permissões requeridas para Hosted Checkout.
• O gateway upstream respondeu no tempo limite permitido.

O Genius Checkout gera um log operacional mesmo quando o MPGS falha antes que exista transação financeira. O suporte precisa desse registro para diferenciar erro do provedor e erro da plataforma.

#Pagamentos recorrentes exigem aprovação de tokenização

A aprovação de um pagamento único não garante prontidão para recorrência. A conta deve suportar tokens reutilizáveis e o comportamento transacional respectivo. O Genius Checkout também impõe as capacidades do plano.

Uma nova tentativa de renovação cria pagamento e transação separados. A transação recusada anterior permanece inalterada, garantindo trilha de auditoria em ambos os sistemas.

#Utilize a mesma conexão MPGS além do HighLevel

O comerciante configura o MPGS uma vez no Genius Checkout. O modo e capacidades habilitados definem quais dessas conexões são possíveis:

• Lojas WooCommerce.
• Lojas Ecwid.
• Formulários de doação GiveWP.
• Links de pagamento hospedados e pagamentos via QR code.
• Aplicações personalizadas compatíveis pela documentação da API Genius Checkout.

Teste cada conexão de software. URLs de retorno, sincronização de status, comportamento de cartão salvo e fluxo de reembolso variam por plataforma.

#Perguntas frequentes dos comerciantes

#Sagicor eCommerce funciona com HighLevel?

O comerciante pode usar uma conta MPGS compatível fornecida pelo seu banco, por exemplo Sagicor, nesta integração com o HighLevel. Configure o host do gateway, modo, credenciais, moedas e permissões exatos fornecidos para a conta. Leia o resumo sobre Sagicor eCommerce.

#O MPGS Hosted Checkout pode ficar dentro do iframe do HighLevel?

Cabeçalhos de segurança do provedor podem bloquear exibição embutida. O Genius Checkout utiliza transferência segura em outro nível quando necessário e retorna o resultado ao HighLevel.

#O Genius Checkout faz a liquidação do valor?

Não. O banco ou provedor processa e liquida os valores conforme o contrato do comerciante.

#Onde posso revisar cada campo MPGS?

Use a visão geral do gateway MPGS e o guia de campos do MPGS no Genius Checkout.

#Fontes

• Documentação da API Mastercard Gateway
• Documentação de pagamentos personalizados HighLevel
• Genius Checkout no HighLevel App Marketplace
• Visão geral do MPGS no Genius Checkout
• Visão geral do HighLevel no Genius Checkout

Precisa de ajuda para identificar o modo correto sem expor credenciais secretas? Agende uma verificação de conexão.