P
Payment
AQpay Pagamentos para Medusa v2: página de pagamento AQpay (Pix, boleto e cartão com 3D Secure) ou checkout próprio na vitrine.
AQpay Pagamentos para Medusa v2
Provedor de pagamento AQpay para lojas Medusa v2: Pix, boleto e cartão de crédito (3D Secure obrigatório, na página segura AQpay — os dados do cartão nunca passam pela loja). Moeda obrigatória: BRL. Uma chave AQpay por loja.
Versão 1.1.0 — homologação em loja ainda pendente. Faça os primeiros testes com valores baixos: a chave de produção gera cobranças reais.
Por que existem duas partes
Uma loja Medusa tem duas partes separadas:
| Parte | O que é | O que a AQpay instala |
|---|---|---|
| Servidor (backend) | Pedidos, carrinho, pagamentos | Este módulo (sempre obrigatório) |
| Vitrine (storefront) | O site que o comprador vê — pode ser feito em qualquer tecnologia | Depende da opção escolhida abaixo |
O Medusa não permite que um módulo do servidor altere as telas da vitrine. Por isso você escolhe como o comprador vai pagar:
| Opção A — Página de pagamento AQpay | Opção B — Checkout dentro da loja | |
|---|---|---|
| Onde o comprador paga | Na página segura da AQpay () | Na própria página da loja |
| O que muda na vitrine | Só um botão "Pagar com AQpay" | Um componente React com Pix, boleto e cartão |
| Funciona com | Qualquer vitrine (React, Vue, Next, app de celular…) | Vitrines React (ex.: starters oficiais Medusa) |
| Precisa de programador | Pouco (um botão) | Sim, para encaixar o componente |
| Recomendado para | A maioria das lojas | Quem quer o comprador sem sair do site |
As duas opções usam o mesmo módulo do servidor e as mesmas regras de segurança: o pedido só é criado depois que o servidor da loja reconsulta a AQpay e confirma o pagamento com o mesmo valor e a mesma referência. Nenhuma cobrança é repetida automaticamente.
Passo 1 — Instalar o módulo no servidor (obrigatório nas duas opções)
No :
Passo 2 — Criar a chave AQpay
- No painel AQpay: Desenvolvedor → Módulos de loja → Medusa.
- Informe a URL HTTPS da loja. Para a Opção A, o endereço de retorno () precisa ser esse mesmo domínio ou um subdomínio dele — ex.: chave com aceita .
- Copie a chave (). Ela aparece uma única vez. Nunca coloque no código nem no Git.
Passo 3 — Variáveis de ambiente do servidor
| Variável | Obrigatória | Exemplo / padrão |
|---|---|---|
| Sim | ||
| Não | ||
| Não | (1 a 21) | |
| Não | (juros do parcelamento para o comprador) | |
| Não | (1 a 30) | |
| Não | (3 a 60) | |
| Opção A | (URL pública deste servidor) | |
| Opção A | ||
| Opção A |
No Medusa Cloud: projeto → Environment Variables, marque Build e Runtime e faça um Redeploy.
Passo 4 — Ativar na região
Admin da loja → Configurações → Regiões → Brasil (BRL) → Provedores de pagamento → adicione AQpay ().
Opção A — Página de pagamento AQpay (tutorial)
Como funciona para o comprador
1. Configure , e (Passo 3). Os campos , e são preenchidos automaticamente.
2. Na vitrine, adicione o botão. Quando o comprador escolher AQpay, a vitrine cria a sessão de pagamento normalmente () e chama:
Resposta: — envie o comprador para esse endereço.
Em React, use o pacote pronto ():
Em qualquer outra tecnologia, basta o acima e .
3. Retorno. A página AQpay devolve o comprador para . Esse endereço do módulo:
- reconsulta a AQpay; se o pagamento estiver confirmado, finaliza o carrinho e redireciona para ;
- se ainda não estiver pago (ex.: boleto aguardando compensação), redireciona para , sem criar pedido.
Na página AQpay o comprador pode trocar de forma de pagamento só se a anterior falhar; com um pagamento em andamento, não é possível gerar outro.
Opção B — Checkout dentro da loja (tutorial)
Como funciona para o comprador
1. Instale o pacote da vitrine
2. Use o componente no passo de pagamento
O componente valida o CPF/CNPJ, cria uma única cobrança por sessão, mostra o Pix copia e cola, o boleto (linha digitável e PDF) ou abre a página segura do cartão com 3D Secure, e chama quando o servidor confirmar o pagamento.
Rotas do servidor usadas (para quem não usa React)
- com → , ou .
- até , depois .
O telefone, nome, e-mail e endereço vêm do endereço de cobrança do carrinho.
Regras importantes (as duas opções)
- Não altere o carrinho depois de gerar o pagamento: o valor fica congelado e a sessão não pode ser apagada.
- Se aparecer a mensagem para não refazer o pagamento, não crie outra cobrança — contate o suporte AQpay.
- Primeiros testes em produção: Pix de R$ 1,00 pago por você; boleto só para conferir a emissão; cartão com valor baixo. Estorno nesta versão é feito pelo suporte AQpay.
Limitações desta versão
Sem recorrência, Apple Pay, captura manual, estorno ou cancelamento automáticos e sem webhook. Pagamento confirmado com carrinho não finalizado exige conciliação pelo suporte.
Publicação no npm
O pacote segue o layout oficial de plugins do Medusa ( → , ). (escopo @aqpay; roda o build). As palavras-chave e fazem o plugin aparecer na documentação do Medusa.