# WooCommerce

> Uma forma de pagamento para o WooCommerce: bitcoin e USDC/USDT direto na sua carteira, e um webhook assinado marca o pedido como pago.

O plugin do Perly Pay adiciona cripto ao checkout clássico e ao bloco Checkout. Cada pedido vira uma fatura do Perly Pay; o comprador paga sobre a sua loja ou numa página separada; um webhook assinado marca o pedido como pago. WordPress 6.5+, WooCommerce 8.6+, PHP 8.1+. Não é preciso instalar nada no servidor: o [SDK de PHP](https://pay.perly.io/docs/sdks.md) já vem dentro.

> **Nota:** As faturas são em USD ou EUR. Numa loja com outra moeda, a forma de pagamento fica oculta e as configurações dela explicam por quê.

## Instalação

1. **Pegue o zip** — O plugin está a caminho do WordPress.org. Enquanto não chega, [escreva para nós](https://pay.perly.io/pt/contact) para pedir o `perly-pay-woocommerce.zip`.
2. **Instale** — No WordPress: Plugins → Adicionar novo → Enviar plugin, escolha o zip e ative. O WooCommerce precisa estar ativo.
3. **Abra as configurações** — WooCommerce → Configurações → Pagamentos → **Perly Pay**.

## Configuração

| Campo | O que colocar |
| --- | --- |
| Chave secreta | Dashboard → Developers → API keys. `sk_test_…` para o [modo de teste](https://pay.perly.io/docs/test-mode.md), `sk_live_…` para dinheiro real. As configurações mostram em que modo você está. |
| Segredo de assinatura do webhook | `whsec_…`. **Configurar webhook** preenche sozinho. |
| Checkout | **Janela** abre o checkout sobre a sua loja (pay.js). **Redirecionamento** leva o comprador para a página dele. No celular, a página sempre abre. |
| Status após o pagamento | O que o WooCommerce decidir (Processando; Concluído para downloads), sempre Processando ou sempre Concluído. |
| Título, Descrição | O que os compradores veem no checkout. |
| Log de depuração | Eventos e erros em WooCommerce → Status → Logs. Nunca chaves, segredos nem dados de compradores. |

1. **Cole a chave** — E clique em **Testar conexão**: você vê se a chave funciona, o modo dela e se o Perly Pay tem o webhook desta loja.
2. **Configure o webhook** — Clique em **Configurar webhook**. Ele adiciona o endereço da sua loja (fica acima dos botões, `…/wp-json/perly-pay/v1/webhook`) ao Perly Pay e salva o segredo. Ou adicione você mesmo em Developers → Webhooks e cole o segredo.
3. **Permita a janela** — Em Dashboard → Settings, adicione o endereço da sua loja em **Sites that may embed the checkout**. Sem isso, a janela oferece abrir o checkout numa aba nova.
4. **Ative** — Marque **Aceitar cripto com o Perly Pay** e salve.

## Teste

Com uma chave `sk_test_…`, faça um pedido na sua loja e escolha Perly Pay. O pedido fica em **Pagamento pendente**. Pague a fatura com moedas de teste ou pela API; o id dela está nas notas do pedido:

```bash
curl -X POST https://pay.perly.io/api/v1/invoices/inv_…/simulate \
  -H "Authorization: Bearer $PERLY_PAY_SECRET_KEY" -H "Content-Type: application/json" -d '{}'
```

Em alguns segundos, o pedido passa a **Processando**, com uma nota: a rede, o valor e um link para a transação. `{"outcome":"short"}` e `{"outcome":"over"}` testam os outros casos depois de escolher a moeda na página da fatura.

## Como os pedidos acompanham os pagamentos

| No Perly Pay | O pedido |
| --- | --- |
| Paga, remetente verificado (`invoice.fulfilled`) | Pago: o status escolhido, estoque reduzido, e-mail ao comprador. Uma nota com cada transferência e a transação dela. |
| Vista, paga em parte, paga e ainda em revisão | Uma nota. Continua pendente. |
| Retida para [revisão](https://pay.perly.io/docs/screening.md) | Aguardando, com o motivo. Decida no Perly Pay. |
| Expirada ou cancelada, sem nada pago | Cancelado. |
| Expirada, paga em parte | Aguardando: reembolse ou aceite no Perly Pay. |
| Reembolsada | Reembolsado por inteiro, ou uma nota para a parte. |

Cada evento é aplicado uma vez, ao pedido para o qual foi criado, e um “expirado” atrasado nunca cancela um pagamento. Se o comprador voltar à página de obrigado antes do webhook, o plugin consulta a API e atualiza o pedido na hora.

## Reembolsos

Reembolse como sempre, na página do pedido: o plugin abre um [reembolso](https://pay.perly.io/docs/refunds.md) no Perly Pay na moeda em que foi pago (uma parte, se for parcial). O Perly Pay pede ao comprador um endereço por e-mail e o verifica; as notas do pedido dizem o que enviar e para onde. Você envia da sua carteira e cola o id da transação no Perly Pay: o Perly Pay nunca guarda o dinheiro.

## Ir para produção

- Ative a produção no Perly Pay e conecte as chaves públicas da sua carteira.
- Cole uma chave `sk_live_…`. As chaves e os webhooks de produção são separados dos de teste: clique em **Configurar webhook** de novo.
- Adicione o endereço https da sua loja real em **Sites that may embed the checkout** em produção.
- Faça um pedido real pequeno e reembolse.