osCommerce

Integre a Cost+ como método de pagamento na sua loja osCommerce 4. O módulo oficial NoPayn Payments utiliza o fluxo de Página de Pagamento Alojada, para que nenhum dado de cartão passe pelo seu servidor — totalmente compatível com PCI DSS.

Pré-requisitos

• Conta de comerciante Cost+ ativa
• osCommerce 4.x
• PHP 8.1 ou superior
• Extensão cURL ativada
• Certificado SSL (HTTPS obrigatório)
• Acesso de administrador ao painel de administração osCommerce

Métodos de Pagamento Suportados

Cada método pode ser individualmente ativado ou desativado a partir do painel de administração.

1. Instalar o Módulo

Transfira ou clone o módulo a partir do GitHub.

Copie o diretório lib/ para a raiz do seu osCommerce 4:

cp -r lib/ /path/to/oscommerce/

Isto coloca os ficheiros do módulo em:

lib/common/modules/orderPayment/nopayn.php
lib/common/modules/orderPayment/nopayn/NoPaynApiClient.php
lib/common/modules/orderPayment/nopayn/NoPaynLogger.php
lib/common/modules/orderPayment/nopayn/NoPaynWebhookHandler.php

No painel de administração osCommerce:

1. Navegue até Modules → Payment → Online
2. Ative os filtros "Show inactive" e "Show not installed" se necessário
3. Encontre NoPayn Payments e clique em Install

2. Configurar o Módulo

Inicie sessão no Portal do Comerciante e navegue até Websites, depois clique no website que pretende conectar. Clique em Integração onde encontrará a sua chave API.

Introduza a sua chave API e configure as seguintes definições:

3. Atualizar Etiquetas do Checkout (Recomendado)

As etiquetas predefinidas do botão de checkout do osCommerce assumem um fluxo de passo único. Para uma melhor experiência com o redirecionamento de pagamento externo, atualize estas traduções em Admin → Localisation → Languages → English → Define:

4. Fluxo de Pagamento

Depois de configurado, o fluxo de pagamento funciona da seguinte forma:

1. O cliente seleciona um método de pagamento Cost+ no checkout
2. O cliente confirma a encomenda
3. O módulo cria uma encomenda pendente e chama a API Cost+
4. O cliente é redirecionado para a Página de Pagamento Alojada Cost+ (HPP)
5. O cliente completa o pagamento na HPP segura
6. O cliente é redirecionado de volta para a loja
7. O módulo verifica o estado do pagamento via a API Cost+
8. O estado da encomenda é atualizado em conformidade

5. Webhooks

O módulo regista um URL de webhook com a Cost+ para atualizações de estado servidor-a-servidor. Quando o estado de um pagamento muda, a Cost+ envia uma notificação e o módulo:

1. Recebe o POST do webhook
2. Verifica o estado do pagamento via API (nunca confia apenas no payload do webhook)
3. Atualiza o estado da encomenda no osCommerce

Captura Manual

Quando ativada para pagamentos com cartão de crédito:

• O pagamento é autorizado mas não capturado no checkout
• Os fundos são capturados quando a encomenda transita para o estado completed
• Se a encomenda for cancelada, a autorização é automaticamente anulada

Registo de Depuração

Quando o Debug Logging está ativado, o módulo escreve em nopayn_debug.log no diretório de logs do osCommerce. As entradas do log incluem:

• Todos os pedidos e respostas da API
• Eventos de webhook e resultados de processamento
• Operações de captura e anulação
• Erros (sempre registados, independentemente da opção de depuração)

Todas as entradas são prefixadas com NoPayn_ para filtragem fácil.

Desinstalação

1. Vá a Modules → Payment → Online no painel de administração
2. Selecione NoPayn Payments
3. Clique em Remove

Testar e Lançar

Faça algumas transações de teste para garantir que tudo funciona corretamente. Recomendamos testar tanto pagamentos bem-sucedidos como falhados para confirmar que todos os cenários são tratados corretamente.

Suporte

Precisa de ajuda? Contacte a nossa equipa de suporte em support@costplus.io.