Pular para o conteúdo principal
Versão: 1.x

Modelo de Gateway

O Modelo de Gateway do WooCommerce fornece um ponto de partida para criar seus próprios gateways de pagamento personalizados para o WooCommerce POS. Este modelo inclui todo o código padrão necessário e a estrutura para construir um gateway de pagamento totalmente funcional.

Recursos​

  • Modelo Completo: Estrutura de gateway pronta para uso com todos os métodos necessários
  • Integração com POS: Pré-configurado para compatibilidade com o WooCommerce POS
  • Configuração Automatizada: Personalização do modelo baseada em script
  • Melhores Práticas: Segue os padrões de codificação do WordPress e WooCommerce
  • Extensível: Fácil de modificar e expandir para provedores de pagamento específicos

Começando​

Opção 1: Geração Automatizada do Modelo​

O modelo inclui um script que personaliza automaticamente o modelo para seu gateway específico:

  1. Clone o Repositório:

    git clone https://github.com/wcpos/woocommerce-gateway-template.git
    cd woocommerce-gateway-template

  2. Execute o Script de Configuração:

    ./create-gateway.sh

  3. Siga os Prompts:

    • Insira o nome do seu gateway (ex: "Meu Gateway de Pagamento")
    • Insira um slug para o gateway (ex: "meu-pagamento")
    • Forneça uma descrição
    • O script gerará um plugin personalizado

Opção 2: Uso Manual do Modelo​

Se você preferir a personalização manual:

  1. Baixe o Modelo:

  2. Personalize o Modelo:

    • Substitua {{GATEWAY_NAME}} pelo nome de exibição do seu gateway
    • Substitua {{GATEWAY_SLUG}} pelo identificador exclusivo do seu gateway
    • Substitua {{GATEWAY_DESCRIPTION}} pela descrição do seu gateway

  3. Renomeie os Arquivos:

    • Renomeie wcpos-{{GATEWAY_SLUG}}.php para corresponder ao slug do seu gateway
    • Atualize os cabeçalhos do arquivo e as informações do plugin

Estrutura do Modelo​

Arquivo Principal do Plugin​

O arquivo principal do plugin (wcpos-{{GATEWAY_SLUG}}.php) contém:

  • Cabeçalho do Plugin: Informações do plugin WordPress
  • Classe do Gateway: Classe principal do gateway de pagamento
  • Inicialização: Configuração do plugin e hooks
  • Integração: Compatibilidade com o WooCommerce POS

Componentes Principais​

Estrutura da Classe do Gateway:

class WCPOS_Gateway_{{GATEWAY_CLASS}} extends WC_Payment_Gateway {
    // Gateway configuration
    public function __construct() { }
    
    // Admin settings form
    public function init_form_fields() { }
    
    // Process payment (main logic goes here)
    public function process_payment( $order_id ) { }
    
    // POS-specific methods
    public function payment_fields() { }
}

Guia de Personalização​

Configuração Básica​

  1. Informações do Gateway:

    $this->id = 'your_gateway_id';
    $this->title = 'Your Gateway Name';
    $this->description = 'Gateway description for customers';
    $this->method_title = 'Admin title';
    $this->method_description = 'Admin description';

  2. Recursos Suportados:

    $this->supports = array(
        'products',
        'refunds',
        'subscriptions', // if applicable
    );

Processamento de Pagamentos​

A lógica principal do pagamento vai no método process_payment():

public function process_payment( $order_id ) {
    $order = wc_get_order( $order_id );
    
    // Your payment processing logic here
    // Example: API calls, validation, etc.
    
    if ( $payment_successful ) {
        $order->payment_complete();
        return array(
            'result' => 'success',
            'redirect' => $this->get_return_url( $order )
        );
    } else {
        wc_add_notice( 'Payment failed', 'error' );
        return array(
            'result' => 'failure'
        );
    }
}

Configurações Administrativas​

Configure as configurações administrativas em init_form_fields():

public function init_form_fields() {
    $this->form_fields = array(
        'enabled' => array(
            'title' => 'Enable/Disable',
            'type' => 'checkbox',
            'label' => 'Enable Your Gateway',
            'default' => 'yes'
        ),
        'api_key' => array(
            'title' => 'API Key',
            'type' => 'text',
            'description' => 'Enter your API key',
            'default' => '',
            'desc_tip' => true,
        ),
        // Add more settings as needed
    );
}

Integração com POS​

Para funcionalidades específicas do POS, implemente:

public function payment_fields() {
    // Custom payment form for POS
    if ( is_admin() && isset( $_GET['page'] ) && $_GET['page'] === 'wc-pos' ) {
        // POS-specific payment fields
        echo '<div class="pos-payment-fields">';
        // Your custom POS interface
        echo '</div>';
    } else {
        // Standard web checkout fields
        parent::payment_fields();
    }
}

Melhores Práticas de Desenvolvimento​

Padrões de Código​

  • Padrões de Codificação do WordPress: Siga os padrões de codificação PHP do WordPress
  • Diretrizes do WooCommerce: Adira às práticas de desenvolvimento do WooCommerce
  • Segurança: Sanitizar entradas, validar dados, usar nonces
  • Internationalização: Tornar strings traduzíveis usando __() e _e()

Tratamento de Erros​

// Proper error handling
try {
    $result = $this->process_api_call( $data );
    if ( is_wp_error( $result ) ) {
        throw new Exception( $result->get_error_message() );
    }
} catch ( Exception $e ) {
    $order->add_order_note( 'Payment failed: ' . $e->getMessage() );
    wc_add_notice( 'Payment processing error', 'error' );
    return array( 'result' => 'failure' );
}

Registro​

// Add logging for debugging
if ( $this->debug ) {
    $this->log( 'Payment processing started for order ' . $order_id );
}

private function log( $message ) {
    if ( empty( $this->logger ) ) {
        $this->logger = wc_get_logger();
    }
    $this->logger->info( $message, array( 'source' => $this->id ) );
}

Testando Seu Gateway​

Ambiente de Desenvolvimento​

  1. Modo de Teste: Sempre implemente um modo de teste/sandbox
  2. Registro de Depuração: Inclua registro abrangente para solução de problemas
  3. Cenários de Erro: Teste várias condições de falha
  4. Teste de POS: Teste especificamente no ambiente POS

Casos de Teste​

  • Pagamentos Bem-Sucedidos: Verifique se os pedidos completam corretamente
  • Pagamentos Falhados: Assegure o tratamento adequado de erros
  • Reembolsos: Teste a funcionalidade de reembolso, se suportada
  • Casos Limite: Teste com vários valores e configurações de pedidos

Implantação​

Empacotamento do Plugin​

  1. Remover Arquivos de Desenvolvimento: Limpe arquivos de teste e ferramentas de desenvolvimento
  2. Controle de Versão: Atualize números de versão no cabeçalho do plugin
  3. Documentação: Inclua README com instruções de instalação
  4. Pacote Zip: Crie um arquivo zip instalável

Distribuição​

  • Lançamentos do GitHub: Utilize lançamentos do GitHub para gerenciamento de versão
  • Diretório de Plugins do WordPress: Considere a submissão ao WordPress.org
  • Distribuição Privada: Hospede em seus próprios servidores se necessário

Recursos Avançados​

Webhooks​

Para atualizações de pagamento em tempo real:

public function handle_webhook() {
    $payload = file_get_contents( 'php://input' );
    $data = json_decode( $payload, true );
    
    // Verify webhook signature
    if ( $this->verify_webhook_signature( $payload ) ) {
        $this->process_webhook_data( $data );
    }
}

Suporte a Assinaturas​

Para pagamentos recorrentes:

// Add subscription support
$this->supports[] = 'subscriptions';
$this->supports[] = 'subscription_cancellation';
$this->supports[] = 'subscription_suspension';

Multi-moeda​

Para pagamentos internacionais:

public function get_supported_currencies() {
    return array( 'USD', 'EUR', 'GBP', 'CAD' );
}

Recursos​

Documentação​

Repositório do Modelo​

  • GitHub: woocommerce-gateway-template
  • Problemas: Relate problemas do modelo ou solicite recursos
  • Contribuições: Envie melhorias através de Pull Requests

Obtendo Ajuda​

Para suporte ao desenvolvimento:

  • Visite o repositório do GitHub para problemas específicos do modelo
  • Consulte a documentação de desenvolvedor do WooCommerce para questões da API
  • Participe da comunidade de desenvolvedores do WooCommerce para orientações gerais

Gateways de Exemplo​

Estude estes gateways personalizados existentes para exemplos de implementação: