Plano obrigatório no Pagar.me

O Pagar.me v5 não aceita assinatura inline. Diferente do Abacate Pay e do Asaas (onde a Allya monta a recorrência a partir dos campos do request), o Pagar.me exige que você tenha criado previamente um Plan via POST /plans na API deles. O plan.id retornado é passado em gateway.pagarme.planId ao criar a assinatura pela Allya.

Sem gateway.pagarme.planId quando o roteamento resolve para Pagar.me, POST /v1/subscriptions retorna 400 invalid_input.

Por que existe esse passo

No Pagar.me, o plano é que governa a recorrência (amount, interval, trial_period_days, ciclos máximos, etc.). A assinatura é uma instância de um plano amarrada a um cliente.

A Allya não cria planos automaticamente porque:

• Planos são reutilizáveis: 1.000 assinaturas mensais de R$ 49,90 com 7 dias de trial referenciam o mesmo plano. Criar um por assinatura virá cobrança de espaço/throttling no Pagar.me.
• Alterar um plano em uso é restrito pela API do Pagar.me: controlar quando criar/quando reusar deve ficar com você.
• Diferentes ofertas comerciais (mensal pro, anual pro com desconto, trial 14 dias) viram diferentes plan_ids: o catálogo é seu.

Passo a passo

1. Crie o plano direto na API do Pagar.me

Antes de chamar a Allya, crie o plano via POST /plans no Pagar.me. Use a Secret Key do mesmo projeto/ambiente que está cadastrada na Allya (sk_test_… para sandbox, sk_live_… para produção).

curl -X POST https://api.pagar.me/core/v5/plans \
  -u "sk_test_xxx:" \
  -H "Content-Type: application/json" \
  -H "User-Agent: pagarme-skill-generated/1.0" \
  -d '{
    "name": "Plano Mensal Pro",
    "currency": "BRL",
    "interval": "month",
    "interval_count": 1,
    "billing_type": "prepaid",
    "payment_methods": ["credit_card"],
    "trial_period_days": 0,
    "items": [
      {
        "name": "Assinatura Pro",
        "quantity": 1,
        "pricing_scheme": { "price": 4990 }
      }
    ]
  }'

Campos importantes:

• interval + interval_count definem o ciclo: month + 1 = mensal; year + 1 = anual.
• billing_type: "prepaid" cobra no início do ciclo. Existe postpaid mas a Allya não suporta esse fluxo.
• payment_methods: ["credit_card"]. A Allya só expõe crédito.
• trial_period_days: dias gratuitos antes da primeira cobrança real. Veja trial.
• items[].pricing_scheme.price em centavos: R$ 49,90 = 4990.

A resposta retorna plan.id no formato plan_xxx. Guarde: você vai usar a cada chamada de assinatura.

2. Passe o plan_id ao criar a assinatura na Allya

await fetch("https://payments-api.allyasolutions.com/v1/subscriptions", {
  method: "POST",
  headers: {
    Authorization: "Bearer sk_test_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    amount: 4990,
    currency: "BRL",
    interval: "monthly",
    externalId: "cliente-123-mensal",
    customer: {
      name: "Cliente Teste",
      email: "cliente@example.com",
      document: "12345678901",
      phone: "11999999999",
    },
    gateway: {
      pagarme: { planId: "plan_xxx" },
    },
  }),
});

A Allya cria um Payment Link (pl_…) referenciando o plano. O cliente final é redirecionado para checkoutUrl, insere o cartão na página hospedada do Pagar.me e a assinatura real (sub_…) é criada pelo gateway.

Trial no Pagar.me

O trial real é definido no campo trial_period_days do Plan criado em POST /plans. O trialDays enviado para a Allya só preserva o status trialing no domínio local: não é repassado ao gateway.

Mudar o tempo de trial significa criar um plano novo: a API do Pagar.me não permite editar trial_period_days de um plano em uso. Exemplo com trial de 7 dias:

curl -X POST https://api.pagar.me/core/v5/plans \
  -u "sk_test_xxx:" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mensal Pro com trial",
    "currency": "BRL",
    "interval": "month",
    "interval_count": 1,
    "billing_type": "prepaid",
    "payment_methods": ["credit_card"],
    "trial_period_days": 7,
    "items": [{ "name": "Pro", "quantity": 1, "pricing_scheme": { "price": 4990 } }]
  }'

Ao criar a assinatura na Allya, envie o mesmo trialDays para manter trialEndsAt e o status trialing consistentes: mas tenha em mente que o que governa a cobrança é o plano.

Boas práticas

• Um plano por combinação de (amount, interval, trial_period_days). Reuse o mesmo plan_id para todas as assinaturas equivalentes.
• Catálogo no seu sistema: mantenha uma tabela plans no seu banco mapeando nome_oferta → plan_id_sandbox → plan_id_live. Em deploy, leia o id correto conforme o ambiente.
• Sincronia entre sandbox e live: planos não migram entre ambientes: você precisa criar dois, um com sk_test_ e outro com sk_live_. Os IDs serão diferentes.
• Não exclua um plano com assinaturas ativas no painel do Pagar.me: o gateway pode rejeitar futuras renovações ou criação de novas assinaturas referenciando-o.

Quando o roteamento não é Pagar.me

gateway.pagarme.planId é ignorado quando o roteamento resolve para Asaas ou Abacate Pay. Você pode passar o campo sempre: não trava nada.

Isso permite o seu código não saber qual gateway está atendendo: passe o planId sempre, e troque o roteamento no painel sem mexer no código cliente. Se voltar para Pagar.me, o plano cadastrado entra em vigor de novo.

Limitações

• Checkout recorrente do Pagar.me não suporta Pix, split nem parcelamento. A Allya cria o link recorrente apenas com cartão de crédito e sem installments_setup.
• A resposta inicial da Allya mantém gatewayRef como pl_…. Quando o Pagar.me envia subscription.created, a Allya troca essa referência pelo sub_… canônico e passa a usar esse ID para sync/cancelamento.
• Não existe API pública na Allya para criar Plan: você sempre chama o Pagar.me direto.

Veja também

• Criar assinatura: fluxo geral, válido para os 3 gateways.
• Gateways: outras particularidades do Pagar.me.
• Cancelar assinatura: restrições de cancelamento no Pagar.me.