Modelo de Gateway

O Modelo de Gateway oferece um ponto de partida para construir seu próprio gateway de pagamento apenas para POS. Ele produz um plugin WordPress funcional com um único arquivo PHP que você pode instalar e personalizar de acordo com suas necessidades.

Recursos

Código Mínimo

Um único arquivo PHP com apenas o essencial — fácil de ler e modificar

Apenas POS

Desativado no checkout da web por padrão, ativado através das configurações do WCPOS

Configuração Automatizada

Um script shell cuida de todas as substituições de espaço reservado para você

Lançamentos do GitHub

Faça um aumento de versão e o GitHub Actions cria um ZIP para download

Começando

1

Clone o Repositório do Modelo

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

Ou clique no botão Usar este modelo no repositório do GitHub para criar sua própria cópia.

2

Execute o Script de Configuração

./create-gateway.sh

O script solicita alguns detalhes — o nome do seu gateway, uma breve descrição e seu nome de usuário do GitHub — e depois gera um plugin pronto para uso em um diretório de sua escolha.

3

Instale o Plugin

Você tem duas opções:

Opção A — Copie a pasta diretamente (se você tiver acesso ao servidor): Copie a pasta do gateway gerado para o diretório wp-content/plugins/ do seu site.

Opção B — Compacte e faça o upload (mais fácil para a maioria das pessoas):

1. Comprima a pasta gerada em um arquivo .zip
2. No WordPress, vá para Plugins > Adicionar Novo > Fazer Upload do Plugin
3. Escolha o arquivo zip e clique em Instalar Agora

4

Ative no WCPOS

1. Vá para WP Admin > WCPOS > Configurações > Checkout
2. Encontre seu novo gateway na lista e ative-o

nota

O gateway está desativado no checkout da web regular por padrão. O WCPOS controla quais gateways aparecem no POS através de suas próprias configurações.

Configuração Manual

Se você preferir não usar o script, pode substituir os espaços reservados você mesmo. Abra cada arquivo em um editor de texto e localize-substitua o seguinte:

Espaço Reservado	O que inserir	Exemplo
{{GATEWAY_NAME}}	O nome de exibição do seu gateway	Pagamento em Dinheiro
{{GATEWAY_SLUG}}	Um identificador seguro para URL (minúsculas, hífens)	pagamento-em-dinheiro
{{GATEWAY_DESCRIPTION}}	Breve descrição do gateway	Aceitar pagamentos em dinheiro no WCPOS
{{GATEWAY_DEFAULT_DESCRIPTION}}	Texto mostrado ao caixa no checkout	Pagar em dinheiro no ponto de venda
{{GITHUB_USERNAME}}	Seu nome de usuário do GitHub	kilbot
{{REPO_NAME}}	O nome do seu repositório	gateway-pagamento-em-dinheiro
{{AUTHOR_NAME}}	Seu nome	kilbot
{{GATEWAY_ID}}	Slug com underlines em vez de hífens	pagamento_em_dinheiro
{{GATEWAY_CLASS_NAME}}	Cada palavra capitalizada, unidas por underlines	Pagamento_Em_Dinheiro
{{GATEWAY_FUNCTION_PREFIX}}	Igual ao ID do Gateway	pagamento_em_dinheiro

Em seguida, renomeie wcpos-{{GATEWAY_SLUG}}.php para corresponder ao seu slug (por exemplo, wcpos-pagamento-em-dinheiro.php).

dica

O script de configuração deriva automaticamente GATEWAY_ID, GATEWAY_CLASS_NAME e GATEWAY_FUNCTION_PREFIX do nome e do slug, então você só precisa pensar nisso ao fazer a configuração manual.

Como Funciona

O plugin gerado registra uma classe de gateway de pagamento do WooCommerce. Aqui estão as principais coisas a saber:

• $this->enabled = 'no' — O gateway é oculto no checkout da web. O WCPOS o habilita no POS com base nas suas configurações de POS.
• process_payment() — Chama $order->payment_complete(), que marca o pedido como pago e lida automaticamente com a redução de estoque.
• init_form_fields() — Define os campos de Título e Descrição que aparecem nas configurações do WooCommerce.

Personalizando seu Gateway

Adicionando Campos de Pagamento

Se o seu gateway precisar de entrada do caixa (por exemplo, um número de referência), substitua o método payment_fields():

public function payment_fields() {
    if ( $this->description ) {
        echo wpautop( wptexturize( $this->description ) );
    }

    woocommerce_form_field( 'my_gateway_reference', array(
        'type'        => 'text',
        'label'       => __( 'Reference Number', 'your-text-domain' ),
        'required'    => true,
    ) );
}

Você pode então ler o valor enviado em process_payment() através de $_POST['my_gateway_reference']. Lembre-se de sanitizar qualquer entrada com sanitize_text_field().

Mudando o Comportamento do Pagamento

O modelo padrão marca os pedidos como pagos imediatamente. Se seu fluxo de trabalho exigir pagamento posterior (como uma fatura), substitua payment_complete() por uma atualização de status:

public function process_payment( $order_id ) {
    $order = wc_get_order( $order_id );

    // Set to pending — the customer will pay later.
    $order->update_status( 'pending', __( 'Awaiting payment', 'your-text-domain' ) );

    // Stock must be reduced manually when not using payment_complete().
    wc_reduce_stock_levels( $order_id );

    return array(
        'result'   => 'success',
        'redirect' => $this->get_return_url( $order ),
    );
}

Fazendo Alterações e Atualizando

Após instalar seu gateway, você pode continuar editando o arquivo do plugin para ajustar a lógica de pagamento. Para instalar uma versão atualizada:

1. Edite wcpos-seu-slug.php na pasta gerada
2. Atualize o número da Versão: no cabeçalho do plugin (por exemplo, 0.1.0 para 0.2.0)
3. Compacte a pasta e faça o upload novamente através de Plugins > Adicionar Novo > Fazer Upload do Plugin, ou substitua a pasta diretamente em wp-content/plugins/

dica

O WordPress perguntará se você deseja substituir o plugin existente quando você fizer upload de um zip com o mesmo nome do plugin — clique em Substituir o atual pelo carregado para atualizar.

Lançamentos Automatizados com GitHub

Se você enviar seu gateway para um repositório do GitHub, o modelo inclui um fluxo de trabalho do GitHub Actions que cria lançamentos automaticamente:

1. Atualize o número da Versão: no cabeçalho do plugin
2. Faça commit e envie para o branch main
3. O GitHub Actions detecta a mudança de versão e cria um novo lançamento com um ZIP para download

Outros usuários podem então baixar o ZIP da página Lançamentos do seu repositório e instalá-lo como qualquer plugin do WordPress.

Solução de Problemas

Gateway não aparece no POS

• Verifique se o plugin está ativado em WP Admin > Plugins
• Vá para WP Admin > WCPOS > Configurações > Checkout e certifique-se de que o gateway está ativado
• Verifique se o WooCommerce está instalado e ativo

Gateway aparece no checkout da web

• Certifique-se de que $this->enabled = 'no'; está definido no construtor do gateway
• O WCPOS substitui essa configuração para solicitações de POS, então o gateway deve aparecer apenas no POS

Pedidos permanecem em 'Processando' em vez de 'Concluído'

• O WooCommerce define o status do pedido com base nos tipos de produtos. Pedidos contendo produtos físicos permanecem em "Processando" — esse é o comportamento normal do WooCommerce. Apenas pedidos com produtos exclusivamente virtuais ou para download são marcados como "Concluído" automaticamente.

Recursos

• GitHub: woocommerce-gateway-template
• API do Gateway de Pagamento WooCommerce: Documentação do WC_Payment_Gateway

Exemplos de Gateways

Esses gateways existentes foram construídos com a mesma abordagem e são boas referências:

• Fatura por Email — Envia um email de fatura para que o cliente possa pagar depois
• Checkout Web — Redireciona para a loja web para pagamento