Assinatura por link

Crie um link de adesao e envie ao cliente. Ele ve o valor, a periodicidade e as condicoes de cancelamento, aceita a recorrencia e informa o cartao no checkout do Minstrel. O numero e o codigo de seguranca sao enviados diretamente ao parceiro pelo SDK de navegador; o servidor recebe apenas o token.

Nao e uma fatura avulsa convertida em assinatura. A assinatura so nasce apos o aceite. O primeiro pagamento ja pertence a uma fatura de assinatura, como transacao iniciada pelo cliente (CIT). Os ciclos seguintes usam o cartao reutilizavel salvo, como transacoes iniciadas pela loja (MIT recorrente).

Antes de gerar o link

• Cadastre o cliente, o produto e um plano pre-pago (billingTiming: "start") sem teste (trialDays: 0). O periodo comeca na adesao, nao na criacao do link.
• Habilite uma conta que ofereca tokenizacao no navegador e devolva um token reutilizavel ao autorizar com salvamento do cartao. Consulte GET /v1/subscription-links/options para descobrir as contas compativeis no ambiente atual.
• Tenha um endereco HTTPS com os termos da contratacao e descreva como o cliente pode cancelar. O checkout apresenta essas condicoes antes do aceite.

Planos com teste gratuito ou pos-pagos nao aceitam este fluxo de primeiro pagamento imediato: exigem cadastrar e validar o cartao sem cobranca, o que depende de outra capacidade do parceiro. O Minstrel recusa a criacao do link nesses casos; nao faz uma cobranca ficticia para salvar o cartao.

Criar e compartilhar

curl https://api.minstrel.com.br/v1/subscription-links \
  -H "Authorization: Bearer $MINSTREL_API_KEY" \
  -H "Idempotency-Key: adesao-academia-aluno-1234" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "cus_01HQ...",
    "planId": "plan_01HQ...",
    "connectorAccountId": "ca_01HQ...",
    "expiresInDays": 7,
    "termsUrl": "https://academia.example/termos",
    "cancellationPolicy": "Solicite o cancelamento antes da proxima mensalidade."
  }'

A resposta traz id, url, status, terms, termsVersion e expiresAt. Envie o endereco completo de url, inclusive o fragmento depois de #. Trate esse endereco como uma credencial: nao publique em listagens abertas, logs ou ferramentas de analise. A credencial nao acompanha os eventos.

expiresInDays aceita de 1 a 30, com padrao de 7 dias. amount, opcional, define um valor negociado em centavos para a assinatura. Use a mesma chave de idempotencia ao repetir a criacao da mesma adesao depois de uma falha de rede.

No painel, clique em Assinaturas → Gerar link de assinatura. Escolha cliente, plano e parceiro e informe os termos. O link aparece imediatamente como uma linha na aba Links de assinatura, com cliente, plano, valor por ciclo, status e validade. Abra a linha para copiar o endereco, acompanhar o aceite e o primeiro pagamento e consultar a assinatura e a fatura vinculadas.

A aba oferece busca por cliente, e-mail, plano ou id do link, filtros de status e plano e paginacao. Os links concluidos permanecem no historico. Na aba Assinaturas, a identificacao Por link mostra a origem da contratacao.

Pela API, GET /v1/subscription-links aceita search, status, planId, customerId, limit (1 a 100, padrao 25) e startingAfter. A resposta inclui data, total, hasMore e nextCursor. Cada linha inclui customer, connectorAccount, subscription, firstInvoice e latestPayment, com apenas os campos necessarios para acompanhamento. GET /v1/subscription-links/:id devolve o mesmo detalhamento. Esses dados exigem autenticacao e permissao subscriptions:read; o checkout publico continua sem expor o cadastro do cliente.

O que acontece na adesao

1. A pagina mostra a empresa, o plano, a periodicidade, a primeira cobranca e as condicoes de cancelamento. Dia fixo de vencimento pode gerar um primeiro ciclo proporcional.
2. O comprador marca uma caixa de aceite, inicialmente desmarcada. O Minstrel registra a versao das condicoes, a data, o IP e o navegador do aceite.
3. A assinatura nasce incomplete, sem reutilizar um cartao padrao que o cliente ja tivesse na carteira. O primeiro pagamento aguarda o novo cartao.
4. O SDK tokeniza no parceiro e confirma o pagamento com saveCard: true. Informar saveCard: false nesta adesao e recusado pelo servidor.
5. Depois da captura, o Minstrel vincula o token reutilizavel a assinatura e quita a primeira fatura. A assinatura passa a active.

O cobrador automatico fica bloqueado enquanto a adesao nao estiver concluida. A conciliacao tambem roda no worker: fechar a pagina depois de pagar nao impede o reconhecimento do pagamento.

Se houver captura sem um token reutilizavel valido, o pagamento e registrado, a assinatura fica pausada e o link passa a requires_attention. O checkout orienta o comprador a nao pagar de novo; a empresa deve revisar o cadastro antes de retomar a assinatura.

Para concluir essa revisao, vincule um cartao reutilizavel valido a assinatura pausada e use Concluir revisao no painel, ou POST /v1/subscription-links/:id/review. A revisao nao repete o pagamento e mantem a assinatura pausada; a retomada e uma decisao explicita da empresa.

O primeiro ciclo tem uma cotacao de 15 minutos. Se ela vencer antes do aceite, a pagina atualiza as condicoes e exige nova confirmacao, preservando o valor exibido mesmo quando o primeiro periodo e proporcional.

Parceiros e portabilidade

O contrato de adesao pertence ao Minstrel. Nao e necessario implementar uma API de recorrencia diferente para cada adquirente, subadquirente ou gateway. Cada plugin declara se oferece tokenizacao e salvamento de cartao durante a autorizacao; somente contas compativeis podem ser escolhidas.

Ser independente da API do parceiro nao torna o token portavel. Um token vinculado ao cofre de uma conta continua sendo cobrado naquela conta, seguindo as regras de roteamento do sistema. Os indicadores de credencial armazenada e os identificadores da bandeira continuam sob responsabilidade dos conectores e do motor de pagamentos. Veja cartao salvo e identificadores.

Estados, eventos e recuperacao

Os eventos sao subscription_link.created, subscription_link.accepted, subscription_link.completed, subscription_link.requires_attention, subscription_link.expired e subscription_link.canceled. Acompanhe tambem invoice.payment_succeeded e subscription.activated para liberar acesso, respeitando os casos que exigem revisao.

Reabrir o link retoma a adesao existente. Repetir o aceite nao cria outra assinatura nem outro pagamento pendente. Depois de uma recusa terminal, uma nova tentativa exige acao do comprador e nova tokenizacao; nao ha retentativa automatica do primeiro pagamento.

Cancelar o link nao cancela uma assinatura ja concluida: use as operacoes de cancelamento da assinatura.