Links de pagamento

Fatura avulsa nao tem acordo de recorrencia com o portador. Cobrar o cartao salvo dela por iniciativa da loja - uma transacao MIT - e exatamente o tipo de cobranca que o emissor recusa, ou que vira contestacao depois. Por isso o Minstrel nunca cobra uma fatura avulsa sozinho.

O caminho certo e o link de pagamento: voce gera o link no plugin escolhido, envia ao cliente, e ele paga na pagina do parceiro, com cartao, Pix ou boleto. A transacao e iniciada pelo cliente (CIT) e o Minstrel nunca ve o numero do cartao: recebe so o resultado.

O link inicia uma recorrencia?

O link atual do Minstrel paga uma fatura; ele nao cria uma assinatura nem autoriza mensalidades futuras. Nao existe conversao automatica de "fatura avulsa paga" para recorrencia.

No pagamento por link, o Minstrel nao cadastra o cartao utilizado como meio de pagamento reutilizavel. Receber a confirmacao de pagamento ou um identificador da transacao nao fornece, por si so, token reutilizavel e consentimento para cobrancas automaticas.

Se o link pertence a uma fatura de assinatura, ele quita aquele ciclo e pode regularizar a assinatura existente. O cartao utilizado no link nao substitui o cartao salvo da assinatura para as proximas cobrancas. Essa alteracao deve seguir o fluxo de troca de cartao da assinatura.

Para adesao com primeiro pagamento e cadastro de cartao, use Assinatura por link, um checkout proprio de recorrencia. Para integrar seu checkout, use assinaturas desde o inicio, com plano, aceite e cartao salvo. Nao gere faturas avulsas em sequencia para simular recorrencia, nem marque uma cobranca automatica como cliente presente para contornar esse fluxo.

Esta e uma limitacao do fluxo de links de fatura do Minstrel. Existem produtos de adquirentes com adesao recorrente por link, como a recorrencia no Link de Pagamento Cielo, que exigem configuracao propria desde a criacao. Essa funcionalidade nao esta disponivel nos links de fatura do Minstrel.

Quando usar

Gerar o link

curl https://api.minstrel.com.br/v1/invoices/inv_01M4.../payment-links \
  -H "Authorization: Bearer $MINSTREL_API_KEY" \
  -H "Idempotency-Key: link-2026-000123" \
  -H "Content-Type: application/json" \
  -d '{
    "connectorAccountId": "ca_01M4...",
    "methods": ["card", "pix", "boleto"],
    "maxInstallments": 3,
    "expiresInDays": 7
  }'

A fatura precisa estar devendo - open, scheduled, past_due, uncollectible ou partially_paid, com amountDue maior que zero - e o link cobra o amountDue daquele momento. Cliente bloqueado nao recebe link.

{
  "object": "payment_link",
  "id": "plk_01M5...",
  "invoiceId": "inv_01M4...",
  "status": "active",
  "url": "https://...",
  "amount": 35000,
  "methods": ["card", "pix", "boleto"],
  "maxInstallments": 3,
  "expiresAt": "2026-10-22T18:00:00.000Z",
  "connector": {
    "slug": "minstrel_sandbox",
    "name": "Minstrel Sandbox",
    "accountName": "Sandbox principal"
  },
  "paymentId": null
}

O endereco tambem vai para o hostedInvoiceUrl da fatura, que alimenta a variavel {{fatura.link}} da regua de cobranca: os avisos ja saem com o link. Quando o link deixa de estar ativo, o campo volta a null.

Um link ativo por fatura

Gerar outro link cancela o anterior, no parceiro e aqui, com o evento payment_link.canceled (cancelReason: "replaced"). Antes de substituir, o Minstrel confirma com o parceiro que o link antigo nao foi pago: se foi, o pagamento e registrado, a fatura e quitada e a API responde 409.

Quando o cliente paga

Numa transacao so:

1. o link vira paid - so a primeira confirmacao vale, e duas chegando juntas criam um pagamento so;
2. nasce um pagamento captured com initiator: "customer" (CIT), o meio usado (card, pix ou boleto), a fatura e o cliente, e metadata com paymentLinkId e o transactionId do parceiro;
3. a tentativa aprovada fica registrada na conta do plugin: e ela que permite estornar depois, por POST /v1/payments/:id/refund;
4. a fatura e quitada como numa cobranca aprovada - a assinatura dela, se houver, volta a ficar em dia;
5. saem os eventos payment.captured, invoice.payment_succeeded e payment_link.paid.

Do cartao usado, o Minstrel guarda so bandeira, BIN (primeiros digitos) e final. Nunca o numero.

Situacao do link

O worker consulta o parceiro dos links ativos - cada link no maximo a cada 5 minutos -, vence os que passaram da validade e cancela os de faturas que deixaram de aceitar pagamento. Para nao esperar:

curl -X POST https://api.minstrel.com.br/v1/payment-links/plk_01M5.../refresh \
  -H "Authorization: Bearer $MINSTREL_API_KEY"

Uma baixa manual ou uma cobranca aprovada no cartao cancelam o link ativo na hora: o cliente nao consegue pagar duas vezes a mesma fatura.

Endpoints

Eventos

Plugins

So plugin com a capacidade payment_link gera link, e a conta precisa ter o recurso ligado. Hoje sao o Minstrel Sandbox e a Cielo (checkout hospedado, logo abaixo); Mercado Pago, PagBank, Asaas, iugu e Pagar.me estao em desenvolvimento. No painel, quem ainda nao gera aparece como EM BREVE na escolha do plugin, e a conta Cielo que ainda nao ligou o link aparece com o atalho para a configuracao da conta.

Link de pagamento da Cielo

O cliente paga numa pagina da Cielo (cielolink.com.br), com cartao de credito: o numero do cartao nunca passa pelo Minstrel, que so le o resultado. Detalhes de configuracao em Conectores.

• Contrato: o Link de Pagamento e um produto da Cielo contratado a parte da API E-commerce, com credenciais proprias (ClientId e ClientSecret do Link, geradas no site da Cielo em E-commerce > Link de Pagamento > Configuracoes > Credenciais de API). A conta liga o recurso em Plugins; sem isso a API responde 422 ao gerar o link.
• Teste: nao existe sandbox. Ligue o Modo Teste da loja no site da Cielo (cartao final 0 a 4 aprova, 5 a 9 nega, ninguem e cobrado) e desligue-o antes de vender de verdade.
• Confirmacao por consulta: o Minstrel nao usa as notificacoes da Cielo (nao sao assinadas). O worker consulta os links ativos a cada 5 minutos, e voce pode chamar refresh. Pedido autorizado e capturado pelo Minstrel, salvo quando o antifraude da loja o segurou para revisao.
• Estorno: pelo mesmo POST /v1/payments/:id/refund de qualquer pagamento. O estorno parcial pode se repetir ate o total. Split nao existe nesta venda.
• Meios: cartao de credito, ate 18 parcelas na Cielo (o Minstrel oferece ate 12). Pix e boleto ainda nao sao oferecidos no link da Cielo.
• Nao serve para assinatura. O checkout hospedado da Cielo so oferece recorrencia agendada e cobrada por ela e nao devolve o token do cartao nem os identificadores da bandeira; o Minstrel nao conseguiria cobrar os ciclos seguintes sem criar uma segunda agenda de recorrencia. O link de assinatura nao lista a Cielo.

Testar no sandbox

O plugin Minstrel Sandbox aponta o link para a pagina de checkout simulado do painel (/checkout/sandbox/...), que o cliente abre sem login. Ela avisa que e ambiente de teste, nao tem campo de numero de cartao e oferece cenarios:

O botao faz as vezes do webhook do parceiro: o pagamento segue exatamente o caminho de uma confirmacao real. O link do Sandbox so existe no ambiente sandbox - o checkout simulado aprova sem dinheiro, e em producao isso seria uma forma de "pagar" fatura de verdade.

Cobrar com o cliente presente

Se o cliente esta no seu checkout agora e o cartao dele ja esta salvo no Minstrel, a cobranca pode ser imediata, marcada como CIT:

curl https://api.minstrel.com.br/v1/invoices/inv_01M4.../charge \
  -H "Authorization: Bearer $MINSTREL_API_KEY" \
  -H "Idempotency-Key: cobranca-2026-000123" \
  -H "Content-Type: application/json" \
  -d '{ "customerPresent": true }'

Sem customerPresent: true, a fatura avulsa responde 409 (invoice_not_payable) com o caminho do link em meta.paymentLinks. A recusa de uma cobranca avulsa nao agenda retentativa (noRetryReason: "standalone_invoice"): quem tenta de novo e o cliente, e a fatura segue em aberto para o link.