# 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[​](#features "Link direto para 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[​](#getting-started "Link direto para 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](https://github.com/wcpos/woocommerce-gateway-template) 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[​](#manual-setup "Link direto para 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[​](#how-it-works "Link direto para 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[​](#customising-your-gateway "Link direto para Personalizando seu Gateway")

### Adicionando Campos de Pagamento[​](#adding-payment-fields "Link direto para 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[​](#changing-payment-behaviour "Link direto para 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[​](#making-changes-and-updating "Link direto para 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[​](#automated-releases-with-github "Link direto para 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[​](#troubleshooting "Link direto para 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[​](#resources "Link direto para Recursos")

* **GitHub**: [woocommerce-gateway-template](https://github.com/wcpos/woocommerce-gateway-template)
* **API do Gateway de Pagamento WooCommerce**: [Documentação do WC\_Payment\_Gateway](https://woocommerce.github.io/code-reference/classes/WC-Payment-Gateway.html)

### Exemplos de Gateways[​](#example-gateways "Link direto para Exemplos de Gateways")

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

* **[Fatura por Email](/pt-BR/payment/gateways/email-invoice.md)** — Envia um email de fatura para que o cliente possa pagar depois
* **[Checkout Web](/pt-BR/payment/gateways/web-checkout.md)** — Redireciona para a loja web para pagamento