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.

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 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. Hoje e o Minstrel Sandbox; Mercado Pago, PagBank, Asaas, iugu e Pagar.me estao em desenvolvimento. A Cielo processa o cartao salvo das assinaturas, mas ainda nao gera link. No painel, quem ainda nao gera aparece como EM BREVE na escolha do plugin.

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.