Atualizado em: 23 de agosto de 2025

Documentação: PRMP

Pagamento Recorrente para Mercado Pago (WooTatitas) — Guia de Integração para Desenvolvedores

Guia rápido para programadores que desejam usar este plugin como base em seus projetos.

Aviso importante

Este plugin pode mudar funcionalidades sem aviso prévio para acompanhar atualizações do Mercado Pago e do WooCommerce.

Toda customização é de responsabilidade do desenvolvedor. Não edite os arquivos originais do plugin. Faça suas alterações em código externo:

um plugin próprio (preferencialmente must‑use),
um plugin adicional do seu projeto, ou
o functions.php de um tema filho.
Utilize hooks (actions/filters) documentados. Alterações diretas no plugin serão sobrescritas em atualizações.

1) Status utilizados (pedidos WooCommerce)

O PRMP registra os seguintes status de pedido para gerenciar assinaturas. Slugs e parâmetros principais:

wc-prmp-awaiting-sub: Aguardando assinatura

Após criar a assinatura (preapproval) e antes da autorização do cliente

wc-prmp-sub-active: Assinatura ativa

Assim que o Mercado Pago confirma a autorização / primeiro authorized payment

wc-prmp-sub-paused: Assinatura pausada

Quando a assinatura é pausada no MP

wc-prmp-sub-cancel: Assinatura cancelada

Quando a assinatura é cancelada no MP ou pelo admin

Downloads: o PRMP libera downloads de produtos quando o pedido está prmp-sub-active.

Em outros status PRMP, downloads não são exibidos na “Minha conta”.

2) E-mails do plugin (IDs, parâmetros e momento do envio)

Cada e-mail é uma classe WC_Email. Não informe chaves de API em templates. IDs, parâmetros e gatilhos:

prmp_subscription_created: Assinatura criada

prmp_payment_pending: Pagamento pendente

prmp_payment_overdue: Pagamento atrasado

prmp_payment_failed: Falha no pagamento

prmp_subscription_cancelled_customer: Assinatura cancelada

prmp_subscription_cancelled_admin: Assinatura cancelada

Quando disparamos?

Em geral, após eventos do MP: ativação, pendência/atraso, falha, pausa e cancelamento.

O plugin dispara actions internas que, por sua vez, acionam os e-mails acima.

Para desativar ou substituir templates, use os filtros/ações do WooCommerce e sobreponha os templates de e-mail em seu tema filho se necessário.

3) Comportamento no checkout

3.1 Carrinho e gateways

Se houver qualquer item recorrente no carrinho, o plugin limita os gateways disponíveis ao gateway do PRMP (prmp_recurring).
Exibe no checkout um resumo de recorrência (valor e periodicidade).
Valida quantidades/itens quando necessário para evitar combinações inválidas.

3.2 Tipos de produto

Simples: marcado como recorrente via metadados de produto; a periodicidade define frequency e frequency_type enviados ao MP.

Variável: o controle é por variação (cada variação pode ser recorrente ou não). O resumo no produto e no checkout considera a variação selecionada.

Virtual: não soma frete ao valor recorrente.

Baixável: downloads ficam disponíveis apenas com prmp-sub-active.

3.3 Frete e cupons

Frete: se o produto não é virtual, o valor do frete do pedido inicial (total + imposto) é adicionado ao valor recorrente.

Cupons: por padrão, cupons/descontos aplicam-se apenas ao pedido inicial. O valor recorrente é calculado a partir do preço do produto (considera sale price quando houver). Caso precise aplicar descontos recorrentes, use o filtro wootatitas_prmp_recurring_amount.

4) O que enviamos ao Mercado Pago (criação de assinatura)

O PRMP cria um preapproval no MP com um payload mínimo (sem expor chaves):

back_url
reason
external_reference
notification_url
payer_email
auto_recurring
frequency
frequency_type
transaction_amount
currency_id
status

Notas importantes:

reason usa a descrição configurada para o produto/vencimento e aparece no MP.

external_reference é ORDER- para rastreabilidade.

auto_recurring.transaction_amount é baseado no preço do produto (considera sale price). Se o item não for virtual, soma frete do pedido inicial. Você pode ajustar via wootatitas_prmp_recurring_amount.

Após a autorização, o plugin consulta o authorized_payments mais recente para consolidar a ativação.

5) Endpoints criados pelo plugin

5.1 Webhook do Mercado Pago

URL base: /?wootatitas_prmp_webhook=mercadopago (preferencialmente HTTPS).
Assinatura de segurança: é adicionada via query string (padrão sig). Nome do parâmetro e algoritmo podem ser alterados via filtros.
Principais type recebidos: subscription_authorized_payment, subscription_preapproval, subscription_updated.
O webhook agenda sincronizações, atualiza status do pedido e dispara actions internas (ver Hooks).

5.2 Endpoints “Minha Conta” (WooCommerce)

Slugs adicionados: assinaturas e assinatura-detalhes.
Podem ser renomeados via filtro wootatitas_prmp_subscription_endpoints.

6) UI/Admin: ações e e-mails

Você pode substituir templates em seu tema, pastas em woocommerce/ conforme o padrão, ou usar os filtros/ganhos para customizar mensagens.

7) Boas práticas & dicas de debug

Nunca edite os arquivos do plugin. Centralize tudo em um plugin MU ou tema filho.
Logs: o PRMP grava logs internos em pasta própria do plugin (com proteção). Trate-os como dados sensíveis.
Teste o webhook localmente com ngrok/tunelamento e envie POST para /?wootatitas_prmp_webhook=mercadopago&sig= com corpo JSON. Use os type suportados (subscription_preapproval, subscription_authorized_payment, subscription_updated).
Cron: existe um agendamento prmp_5minutes usado para sincronizações/verificações. Em ambientes de staging, garanta que o WP-Cron esteja executando.
Recriação de preapproval: o plugin pode recriar a assinatura se detectar preapproval pendente muito antigo sem authorized payment. Não dependa do ID ser imutável.
Compatibilidade com cupons/frete: lembre que cupons não afetam o valor recorrente por padrão; frete entra apenas se o item não for virtual.
Extensibilidade primeiro: prefira actions/filters acima, evitando overrides diretos de classes/templates do plugin.

Como instalar

Veja nosso guia de como instalar nosso plugin:

Compre nosso plugin

Gostou do que viu? Compre o nosso plugin: