Comece aqui

Qual API chamar e em qual ordem

Do cadastro à confirmação: origem dos IDs, seleção de fluxo, conta do parceiro e APIs necessárias para cobrar de verdade.

Guia de integração · 6 min de leitura

Nesta página

Uma cobrança pontual começa em POST /v1/payments. Uma recorrência começa em POST /v1/subscriptions, depois de cadastrar cliente, produto, plano e cartão reutilizável com consentimento. O Minstrel gera e cobra as faturas da assinatura; não crie outro pagamento para cobrar o mesmo ciclo.

O caminho de uma transação

Do backend à confirmação: pagamento, seleção de fluxo ou conta elegível, parceiro e confirmação por consulta e webhook.

Abrir diagrama em tamanho integral

Conta do parceiro: conecte-a em Plugins ou POST /v1/connector-accounts. Consulte GET /v1/connectors para campos e capacidades do plugin e GET /v1/connector-accounts para suas contas e capacidades efetivas.
Cliente: crie em POST /v1/customers. Para Pix e boleto, informe documento; boleto também precisa do endereço completo.
Cartão: use somente token obtido legitimamente no parceiro, na conta de origem. Para salvar, chame POST /v1/customers/{customerId}/payment-methods. No Minstrel Sandbox, .../payment-methods/test-card dispensa cartão real.
Cobrança: chame POST /v1/payments, com Idempotency-Key. Envie paymentMethodId ou card para crédito; Pix e boleto não usam esses campos.
Resultado: confira status, decline e nextAction. Consulte GET /v1/payments/{paymentId} e acompanhe os webhooks.

O caminho de navegador para coletar cartão real está suspenso, inclusive Cielo sandbox. A nova coleta deve ocorrer integralmente em página hospedada pelo parceiro. Configurar uma conta não ativa automaticamente checkout, 3DS ou link real. Veja disponibilidade da coleta.

Como selecionar um flow

Você pode manter vários fluxos publicados. No painel Fluxos, copie o flowId para a API (flw_), disponível no cartão da lista e no editor. Pela API, use o id de GET /v1/flows; confira status: published, triggerEvent e activeVersion.

Requisição	Como a rota é escolhida
`POST /v1/payments` com `flowId`	Usa esse fluxo publicado da mesma conta e ambiente, com gatilho `payment.authorization_requested`.
Sem `flowId`, com fluxo publicado	Usa o padrão daquele gatilho no ambiente.
Sem `flowId` e sem fluxo publicado	Roteamento direto, se houver uma conta elegível ou origem inequívoca do token. Várias contas elegíveis exigem configuração de fluxo.
Fatura de assinatura	O cobrador prioriza o padrão de `invoice.payment_due`; na ausência, usa `payment.authorization_requested`.

O flowId escolhe o fluxo; o motor fixa sua versão publicada na criação do pagamento. Publicar outra versão enquanto um checkout espera confirmação não troca a versão já selecionada. O flowVersionId (flv_) é a versão de auditoria, não o ID para enviar como flowId.

ID inexistente, rascunho, arquivado, de outra conta/ambiente ou com gatilho incompatível responde 422 em flowId antes de criar o pagamento. Não há fallback silencioso para outro fluxo. Se um fluxo selecionado for arquivado antes do processamento, a cobrança não é enviada por outra rota.

O exemplo usa um fluxo que continua publicado, embora outro seja o padrão:

Selecionar um fluxo publicado diferente do padrao

cURL / Bash

curl -X POST "https://api.minstrel.com.br/v1/payments" \
  -H "Authorization: Bearer $MINSTREL_API_KEY" \
  -H "Idempotency-Key: pedido-fluxo-escolhido-001" \
  -H "Content-Type: application/json" \
  --data-raw '{
  "amount": 25990,
  "customerId": "cus_01M5DA7M63VN499S6P34D6DQJZ",
  "paymentMethodId": "pm_01M5DA7M79Q7WTDWW10ZHD1V0D",
  "flowId": "flw_01M5DA7P8GHHVQAJWEYPYY0KXC",
  "externalId": "pedido-fluxo-escolhido-001"
}'

HTTP 201 · Resposta completa capturada no Minstrel Sandbox com dados fictícios

json

{
  "object": "payment",
  "security": {
    "transactionFingerprint": "1501579242f55e416f9fce08e8e0b93d5a211c2d84814ece75709bd034987076",
    "deviceFingerprint": null,
    "cardFingerprint": "d94bbdbc0b0d993e7807a75565ca70a817226c77059c7536ed8bb5d458a224bd",
    "cardIdentitySource": "token",
    "channel": "api"
  },
  "id": "pay_01M5DA7PKZB6NBTZ0TY8HBTA40",
  "status": "captured",
  "amount": 25990,
  "currency": "BRL",
  "capturedAmount": 25990,
  "refundedAmount": 0,
  "captureMethod": "automatic",
  "installments": 1,
  "methodType": "card",
  "nextAction": null,
  "actionExpiresAt": null,
  "initiator": "customer",
  "mitType": null,
  "description": null,
  "softDescriptor": null,
  "externalId": "pedido-fluxo-escolhido-001",
  "customerId": "cus_01M5DA7M63VN499S6P34D6DQJZ",
  "invoiceId": null,
  "paymentMethod": {
    "id": "pm_01M5DA7M79Q7WTDWW10ZHD1V0D",
    "type": "card",
    "brand": "visa",
    "last4": "4242",
    "expMonth": 12,
    "expYear": 2029,
    "isNetworkToken": false
  },
  "decline": null,
  "fraudReview": null,
  "attempts": [
    {
      "id": "att_01M5DA7PP8ZAK9GE4EX77FW9RP",
      "attemptNumber": 1,
      "status": "succeeded",
      "trigger": "initial",
      "connector": null,
      "authorizationCode": "6C41F6",
      "nsu": "160006",
      "tid": "17925220503098831",
      "rawResponseCode": null,
      "declineReason": null,
      "reversibility": null,
      "retryAction": null,
      "latencyMs": 63,
      "startedAt": "2026-10-20T18:47:30.252Z"
    }
  ],
  "splits": [],
  "metadata": {},
  "authorizedAt": "2026-10-20T18:47:30.350Z",
  "capturedAt": "2026-10-20T18:47:30.350Z",
  "failedAt": null,
  "createdAt": "2026-10-20T18:47:30.190Z",
  "updatedAt": "2026-10-20T18:47:30.352Z",
  "clientSecret": null
}

Na sua integração, substitua o flowId pelo ID copiado no seu painel e os outros IDs pelas respostas da sua conta. Publicar configura as regras; a transação só começa ao chamar a API de pagamento.

Quando chamar uma adquirente diretamente

O plugin é um adaptador interno. Você não chama um endpoint separado da Cielo, Rede ou outro plugin dentro da API Minstrel para autorizar. O ponto de entrada continua sendo POST /v1/payments.

Para uma rota fixa, publique um fluxo com Escolher adquirente → Autorizar pagamento e passe seu flowId. Nesse caminho, configure Zero Auth, 3DS e split somente depois de escolher uma conta que suporte os recursos.

Campo	Finalidade
`flowId` no pagamento	Selecionar regras e rota de um fluxo publicado.
`card.connectorAccountId`	Identificar onde o token foi emitido. Não ignora o fluxo nem torna o token portável.
`tokenizationAccountId`	Selecionar a conta no checkout sem token, atualmente exclusivo da simulação Minstrel Sandbox. Não serve para roteamento de cartão salvo.
`connectorAccountId` na assinatura	Escolher onde cobrar os ciclos daquela assinatura. O cartão precisa ser compatível; as etapas de risco do fluxo continuam valendo.

connectorAccountId não existe na raiz de POST /v1/payments. Não envie campos que não fazem parte do contrato esperando que alterem a rota.

De onde vem cada ID

Todos pertencem à organização e ao ambiente da chave. Nomes, documentos e IDs do seu ERP não substituem os IDs retornados pelo Minstrel.

Campo usado	Criar ou localizar	Valor que deve ser guardado
`customerId`	`POST /v1/customers` ou `GET /v1/customers`	`id` com prefixo `cus_`
`connectorAccountId`	Plugins no painel ou `GET /v1/connector-accounts`	`id` com prefixo `ca_`, não `connectorSlug`
`paymentMethodId`	`POST/GET /v1/customers/{customerId}/payment-methods`	`id` com prefixo `pm_`, não o token do cofre
`flowId`	Fluxos no painel ou `GET /v1/flows`	`id` com prefixo `flw_`, não `activeVersion.id`
`productId`	`POST/GET /v1/products`	`id` com prefixo `prod_`
`planId`	`POST/GET /v1/plans`	`id` com prefixo `plan_`
`subscriptionId`	`POST/GET /v1/subscriptions`	`id` com prefixo `sub_`
`invoiceId`	`latestInvoice.id` da assinatura ou `GET /v1/invoices`	`id` com prefixo `inv_`, não o número da fatura
`paymentId`	`POST /v1/payments` ou `firstCharge.paymentId`	`id` com prefixo `pay_`
`recipientId`	`POST/GET /v1/recipients`	`id` com prefixo `rcp_`; verifique cadastro no parceiro

APIs necessárias por cenário

Cenário	Chamadas principais	O que confirma o recebimento
Crédito com token salvo	Cliente → salvar token → `POST /payments`	`status: captured`, consulta e webhook
Pré-autorização	Mesmo caminho, `captureMethod: manual` → `POST /payments/{id}/capture`	`authorized` apenas reserva; entrega depende da captura
Pix	Cliente com documento → `POST /payments` com `methodType: pix`	QR emitido não é pago; aguarde `captured`
Boleto	Cliente com documento/endereço → `POST /payments` com `methodType: boleto`	Boleto emitido não é pago; aguarde liquidação
Recorrência	Cliente/token → produto → plano → `POST /subscriptions`	Fatura paga e eventos de ativação/pagamento
Zero Auth	`verify: true` ao salvar token, ou nó no fluxo	Valida cartão, não recebe dinheiro
3DS	Nó no fluxo antes da autorização	Autenticar não captura; o caminho público atual é só simulado

Cadastre webhooks uma vez por ambiente; não a cada transação. Operações de configuração exigem os escopos de escrita dos respectivos recursos; cobranças usam payments:write, consultas payments:read, assinaturas e planos subscriptions:write/read, faturas invoices:write/read.

Ler a resposta sem confundir HTTP com pagamento

Uma requisição pode retornar HTTP 201 e status: failed: o recurso foi criado, mas o emissor recusou. Este é um exemplo completo de recusa 51:

Recusa do emissor com HTTP 201