Pix e boleto

Pix e boleto nao sao aprovados na hora, como o cartao. O Minstrel emite a cobranca no banco ou PSP e devolve o que o pagador precisa - o QR Code do Pix ou a linha digitavel do boleto. O pagamento so vira venda quando o banco confirma.

Tudo acontece por API, com o webservice do banco: registro on-line da cobranca e confirmacao por webhook ou consulta. Nao ha arquivo CNAB de remessa e retorno, nem VAN.

Criar um Pix

curl https://api.minstrel.com.br/v1/payments \
  -H "Authorization: Bearer $MINSTREL_API_KEY" \
  -H "Idempotency-Key: pedido-1234" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 14990,
    "methodType": "pix",
    "customerId": "cus_01M5...",
    "pix": { "expiresInSeconds": 3600 },
    "description": "Pedido 1234",
    "externalId": "pedido-1234"
  }'

Resposta (resumida):

{
  "object": "payment",
  "id": "pay_01M5...",
  "status": "requires_action",
  "amount": 14990,
  "methodType": "pix",
  "nextAction": {
    "type": "pix_qr_code",
    "qrCode": "00020126580014br.gov.bcb.pix0136...6304E732",
    "txid": "sbx0tmz39wkWmjeD6YCfSppIl",
    "expiresAt": "2026-10-15T23:44:20.127Z"
  },
  "actionExpiresAt": "2026-10-15T23:44:20.127Z"
}

nextAction.qrCode e o Pix copia e cola (BR Code). Mostre o texto com um botao de copiar e desenhe o QR Code a partir dele - qualquer biblioteca de QR serve. Quando o PSP devolve a imagem pronta, ela vem em qrCodeImage (data URL).

Criar um boleto

curl https://api.minstrel.com.br/v1/payments \
  -H "Authorization: Bearer $MINSTREL_API_KEY" \
  -H "Idempotency-Key: pedido-1235" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 25000,
    "methodType": "boleto",
    "customerId": "cus_01M5...",
    "boleto": {
      "dueDate": "2026-10-20",
      "daysAfterDue": 2,
      "fineBps": 200,
      "interestMonthlyBps": 100,
      "instructions": "Nao receber apos a data limite."
    }
  }'

{
  "object": "payment",
  "id": "pay_01M5...",
  "status": "requires_action",
  "methodType": "boleto",
  "nextAction": {
    "type": "boleto",
    "barcode": "00092160500000250007460529040900396486633853",
    "digitableLine": "00097460582904090039064866338532216050000025000",
    "dueDate": "2026-10-20",
    "expiresAt": "2026-10-23T02:59:59.999Z",
    "nossoNumero": "74605290409"
  },
  "actionExpiresAt": "2026-10-23T02:59:59.999Z"
}

digitableLine (47 digitos) e o que o pagador digita no app do banco; barcode (44 digitos) e o codigo de barras, no padrao intercalado 2 de 5. Os dois vem so com digitos: formate a linha digitavel para exibir (00097.46058 29040.900390 ...). pdfUrl vem quando o banco gera o PDF, e pixQrCode quando o banco emite o Pix junto (bolepix).

actionExpiresAt e o ultimo instante de pagamento: o fim do dia (horario de Brasilia) do vencimento mais a tolerancia, levado ao proximo dia util quando cai em fim de semana ou feriado nacional - a regra da FEBRABAN.

O que a criacao exige

Pix e boleto sao recusados com 422, antes de gravar qualquer coisa, quando:

• falta customerId, ou o cliente nao tem nome e CPF/CNPJ valido;
• e boleto e o cliente nao tem o endereco completo (rua, streetNumber, bairro, cidade, UF com 2 letras e CEP com 8 digitos). O erro lista o que falta em meta.missing;
• vem paymentMethodId ou card - Pix e boleto nao usam cartao;
• currency nao e BRL, installments nao e 1 ou captureMethod nao e automatic: Pix e boleto sao a vista e liquidam no pagamento;
• initiator nao e customer ou vem mitType: quem paga e sempre o cliente;
• nenhuma conta de plugin habilitada no ambiente emite o meio.

Ciclo de vida

O modelo e o da Stripe: o pagamento espera o pagador em requires_action, com o que ele precisa em nextAction.

• payment.requires_action leva o nextAction: da para enviar o QR Code ou a linha digitavel ao cliente direto do webhook.
• nextAction so existe enquanto o pagamento espera. Pago ou vencido, volta null; actionExpiresAt continua, como registro. O detalhe (GET /v1/payments/:id) guarda a cobranca em methodDetails, inclusive o endToEndId do Pix pago.
• payment.canceled traz data.object.cancellation, com reason (expired, canceled ou partner_canceled) e source (worker, webhook, simulation ou manual).
• Na tentativa, o Pix vencido aparece com outcome: "expired" e o cancelado, "canceled" - nao como recusa: ninguem negou nada.

Com fluxo publicado

O no Rotear para adquirente so manda Pix ou boleto para contas cujo plugin emite o meio. As outras sao puladas, com o motivo no rastro do no ("Puladas por nao aceitarem Pix: Cielo loja"). Sem nenhuma conta que sirva, o no falha com uma mensagem que diz o que mudar no fluxo.

Emitida a cobranca, a execucao do fluxo pausa no no de rota. Quando o banco confirma, ela segue pela saida Aprovado - como faria a autorizacao de um cartao. O no Capturar vira passagem: Pix e boleto liquidam no pagamento. Vencida ou cancelada, a execucao e encerrada onde estava, sem seguir por saida nenhuma.

Para separar os meios, use uma condicao em payment.method_type.

Sem fluxo publicado, o roteamento e direto: vale a unica conta habilitada que emite o meio. Com mais de uma, publique um fluxo.

Confirmacao: consultamos antes de acreditar

O banco avisa o pagamento por webhook, e o Minstrel tambem consulta as cobrancas pendentes. As duas vias chegam ao mesmo lugar, e so a primeira confirmacao vale: um webhook e a consulta chegando juntos geram um payment.captured so.

Consultamos antes de acreditar. O corpo do webhook nunca e usado para mudar um pagamento: ele so aponta quais cobrancas mudaram, e cada uma e consultada no banco antes de qualquer alteracao. Um aviso forjado - mesmo com o endereco certo - nao paga nada. Cada aviso conferido fica registrado em operations do detalhe, com a origem e o que o banco respondeu.

Endereco do webhook

Cada conta de plugin que emite Pix ou boleto expoe webhookUrl em GET /v1/connector-accounts, e a pagina do plugin no painel mostra o endereco com um botao de copiar:

https://api.minstrel.com.br/v1/connector-webhooks/ca_01M4.../exemplo_de_token_da_conta_000001

Cadastre esse endereco no portal do banco. O ultimo trecho e o token da conta: trate-o como segredo. Token errado ou conta inexistente respondem 404. O webhook responde 200 assim que le o aviso e faz a consulta em seguida - o banco nao fica esperando.

Sem webhook cadastrado, nada se perde: a consulta periodica confirma do mesmo jeito, so que mais devagar.

Vencimento

• Pix: passada a validade, o Minstrel consulta o banco uma ultima vez. Pago no ultimo segundo, confirma; senao, tira o Pix do banco e cancela o pagamento (payment.canceled, reason: "expired").
• Boleto: o pagamento feito no ultimo dia so compensa no dia util seguinte. Por isso, passada a data limite, o Minstrel continua consultando por dois dias uteis antes de dar baixa. Se o banco ja informa o boleto vencido, a baixa e imediata.

Cancelar a cobranca

curl -X POST https://api.minstrel.com.br/v1/payments/pay_01M5.../void \
  -H "Authorization: Bearer $MINSTREL_API_KEY" \
  -H "Idempotency-Key: cancela-pedido-1234" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Cliente desistiu" }'

O mesmo endpoint do cancelamento de autorizacao. Para Pix e boleto aguardando pagamento, tira a cobranca do banco (remove o Pix, da baixa no boleto) e emite payment.canceled. Antes, consulta o banco: se o pagador acabou de pagar, o pagamento e confirmado e a resposta e 409 - nunca se cancela um Pix pago.

Estorno do Pix

POST /v1/payments/:id/refund, como no cartao: total ou parcial, ate o valor pago. A devolucao e pedida ao PSP que recebeu, pelo endToEndId gravado na confirmacao, e normalmente cai na conta do pagador em segundos.

Boleto nao tem estorno

O banco nao devolve dinheiro de boleto ao pagador: nao existe operacao para chamar. O estorno de boleto responde 409 payment_not_refundable com a orientacao, e actions.refund vem com reason: "method_unsupported".

Para devolver, faca um Pix ou TED para a conta do pagador e registre a devolucao no seu controle.

Simular no sandbox

O plugin Minstrel Sandbox emite cobrancas bem formadas e impagaveis de verdade:

• o Pix e um BR Code no padrao do Banco Central, com CRC correto, txid, o nome MINSTREL SANDBOX e uma chave aleatoria gerada a cada cobranca. O app do banco le o QR, procura a chave no DICT e nao encontra ninguem;
• o boleto tem linha digitavel e codigo de barras com os digitos verificadores da FEBRABAN, mas o codigo de banco e 000, que nao existe na compensacao.

O banco simulado responde pending ate a validade e expired depois. Para pagar, use a simulacao:

curl -X POST https://api.minstrel.com.br/v1/payments/pay_01M5.../simulate \
  -H "Authorization: Bearer $MINSTREL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "outcome": "paid" }'

outcome aceita paid e expired. A simulacao exige o escopo payments:write, so existe no ambiente sandbox e so vale para cobrancas do Minstrel Sandbox. O resultado segue o mesmo caminho da consulta e do webhook: fluxo retomado, eventos e webhooks iguais aos de producao. No painel, os botoes Simular pagamento e Simular vencimento ficam no detalhe da transacao.

Bancos no catalogo

O catalogo de plugins tem o grupo Bancos, com Pix e boleto registrado por API: Inter, Itau, Bradesco, Santander, Banco do Brasil, Sicredi, Sicoob e Caixa, alem dos PSPs de Pix Efi e Celcoin. Eles aparecem como Em breve ate a integracao ficar pronta; o Minstrel Sandbox ja emite Pix e boleto para voce construir e testar a integracao inteira hoje.

Nenhum deles usa VAN nem arquivo CNAB: o registro e a confirmacao sao on-line, pelo webservice do banco.