Modelo de gateway

O modelo de gateway oferece um ponto de partida para criar seu próprio gateway de pagamento exclusivo para o WCPOS. Ele gera um plugin funcional do WordPress com um único arquivo PHP, que você pode instalar e personalizar conforme suas necessidades.

Recursos

Código mínimo

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

Exclusivo para o WCPOS

Desativado por padrão no checkout da Web e ativado nas configurações do WCPOS

Configuração automatizada

Um script de shell substitui todos os marcadores de posição para você

Lançamentos do GitHub

Envie uma atualização de versão, e o GitHub Actions cria um ZIP para download

Primeiros passos

1

Clonar 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

Executar o script de configuração

./create-gateway.sh

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

3

Instalar o plugin

Você tem duas opções:

Opção A — Copiar 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 — Compactar e enviar (mais fácil para a maioria das pessoas):

1. Compacte a pasta gerada em um arquivo .zip
2. No WordPress, acesse Plugins > Adicionar novo > Enviar plugin
3. Escolha o arquivo ZIP e clique em Instalar agora

4

Ativar no WCPOS

1. Acesse WP Admin > Ponto de venda > Configurações > Caixa
2. Encontre o novo gateway na lista e ative-o

nota

O gateway fica desativado por padrão no checkout normal da Web. O WCPOS controla quais gateways aparecem no ponto de venda por meio de suas próprias configurações.

Configuração manual

Se preferir não usar o script, você pode substituir os marcadores de posição manualmente. Abra cada arquivo em um editor de texto e faça as seguintes substituições:

Marcador de posição	O que inserir	Exemplo
{{GATEWAY_NAME}}	Nome de exibição do gateway	Pagamento em dinheiro
{{GATEWAY_SLUG}}	Identificador seguro para URL (minúsculas, hífens)	cash-payment
{{GATEWAY_DESCRIPTION}}	Descrição breve do gateway	Aceitar pagamentos em dinheiro no WCPOS
{{GATEWAY_DEFAULT_DESCRIPTION}}	Texto exibido ao caixa no checkout	Pague em dinheiro no ponto de venda
{{GITHUB_USERNAME}}	Seu nome de usuário no GitHub	kilbot
{{REPO_NAME}}	Nome do seu repositório	cash-payment-gateway
{{AUTHOR_NAME}}	Seu nome	kilbot
{{GATEWAY_ID}}	Slug com sublinhados em vez de hífens	cash_payment
{{GATEWAY_CLASS_NAME}}	Cada palavra com inicial maiúscula, unidas por sublinhados	Cash_Payment
{{GATEWAY_FUNCTION_PREFIX}}	Igual ao ID do gateway	cash_payment

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

dica

O script de configuração deriva automaticamente GATEWAY_ID, GATEWAY_CLASS_NAME e GATEWAY_FUNCTION_PREFIX do nome e do slug; portanto, você só precisa se preocupar com esses valores ao fazer a configuração manual.

Como funciona

O plugin gerado registra uma classe de gateway de pagamento do WooCommerce. Veja os principais pontos:

• $this->enabled = 'no' — O gateway fica oculto no checkout da Web. O WCPOS o ativa no ponto de venda com base nas configurações do WCPOS.
• process_payment() — Chama $order->payment_complete(), que marca o pedido como pago e processa automaticamente a redução do estoque.
• init_form_fields() — Define os campos Título e Descrição exibidos nas configurações do WooCommerce.

Personalizar seu gateway

Adicionar campos de pagamento

Se o gateway precisar de uma informação 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,
    ) );
}

Em seguida, você pode ler o valor enviado em process_payment() por meio de $_POST['my_gateway_reference']. Lembre-se de sanitizar qualquer entrada com sanitize_text_field().

Alterar o comportamento do pagamento

O modelo padrão marca os pedidos como pagos imediatamente. Se seu fluxo de trabalho exigir pagamento posterior (como no caso de 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 ),
    );
}

Fazer alterações e atualizar

Depois de instalar o 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-your-slug.php na pasta gerada
2. Atualize o número Version: no cabeçalho do plugin (por exemplo, de 0.1.0 para 0.2.0)
3. Compacte a pasta e envie-a novamente por Plugins > Adicionar novo > Enviar plugin ou substitua a pasta diretamente em wp-content/plugins/

dica

O WordPress perguntará se você quer substituir o plugin existente ao enviar um arquivo ZIP com o mesmo nome — clique em Substituir o atual pelo enviado 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 Version: no cabeçalho do plugin
2. Faça commit e envie as alterações para o branch main
3. O GitHub Actions detecta a alteração da versão e cria um novo lançamento com um arquivo ZIP para download

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

Solução de problemas

O gateway não aparece no WCPOS

• Verifique se o plugin está ativado em WP Admin > Plugins
• Acesse WP Admin > Ponto de venda > Configurações > Caixa e confirme que o gateway está ativado
• Verifique se o WooCommerce está instalado e ativo

O gateway aparece no checkout da Web

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

Os pedidos permanecem como 'Processando' em vez de 'Concluído'

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

Requisitos

WCPOS: É necessária a versão Pro para o checkout no ponto de venda

WordPress: WordPress com WooCommerce instalado

PHP: Conhecimentos básicos de PHP para personalizar o gateway

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