Transacoes

Depois de criado, um pagamento precisa ser encontrado, explicado e, as vezes, desfeito. Esta pagina cobre as consultas e as operacoes que movem dinheiro de volta. Leitura exige o escopo payments:read; confirmacao, captura, cancelamento e estorno, payments:write.

Toda consulta vale para o ambiente da chave: sandbox e producao nunca se misturam, nem num indicador.

Meios de pagamento

methodType diz como o pagamento foi feito:

Pix e boleto tem pagina propria: Pix e boleto cobre a criacao, a confirmacao pelo banco, o vencimento e a simulacao no sandbox.

Status de um pagamento

requires_payment_method e o unico status que nasce antes de qualquer tentativa: ainda nao ha cartao, entao nenhum adquirente foi acionado e attempts vem vazio. A resposta da criacao traz clientSecret (<paymentId>_secret_...) e actionExpiresAt. O clientSecret e entregue a pagina do portador e nunca aparece no painel. Veja Confirmar um pagamento sem cartao.

Listar e filtrar

curl "http://localhost:3333/v1/payments?status=failed&declineReason=INSUFFICIENT_FUNDS&createdAfter=2026-10-01T03:00:00Z&limit=50" \
  -H "Authorization: Bearer $MINSTREL_API_KEY"

Valor fora do vocabulario em status ou methodType e recusado com 422 e a lista do que e aceito: um filtro digitado errado que devolvesse lista vazia pareceria "nao ha nada", e voce procuraria o problema no lugar errado.

search aceita o que o suporte costuma receber do cliente:

• id do pagamento (exato ou o comeco, a partir de pay_);
• externalId, descricao, nome ou e-mail do cliente (trecho, sem diferenciar maiusculas);
• os 4 ultimos digitos do cartao;
• CPF ou CNPJ do cliente, com ou sem pontuacao (a partir de 6 digitos);
• NSU, TID, codigo de autorizacao, id da transacao no adquirente (o txid do Pix, o id do boleto no banco) ou id da tentativa (4 caracteres ou mais, sem espaco).

A lista vem do mais recente para o mais antigo. totalCount vem so na primeira pagina (sem startingAfter): a contagem com filtros e a parte cara da consulta.

Resposta (resumida):

{
  "object": "list",
  "data": [
    {
      "object": "payment",
      "id": "pay_01HQ...",
      "status": "captured",
      "amount": 14990,
      "capturedAmount": 14990,
      "refundedAmount": 0,
      "customer": {
        "id": "cus_01HQ...",
        "name": "Maria Oliveira",
        "email": "maria.oliveira@exemplo.com.br"
      },
      "attemptSummary": {
        "count": 1,
        "fallback": false,
        "connectorAccount": {
          "accountId": "ca_01HQ...",
          "name": "Cielo principal",
          "slug": "cielo",
          "connectorName": "Cielo",
          "removed": false
        },
        "path": [
          {
            "attemptNumber": 1,
            "connector": "Cielo principal",
            "slug": "cielo",
            "outcome": "approved",
            "trigger": "initial"
          }
        ],
        "lastDecline": null,
        "latencyMs": 812
      }
    }
  ],
  "hasMore": true,
  "nextCursor": "pay_01HQ...",
  "totalCount": 1284
}

Cada item traz os campos do pagamento (os mesmos do data.object dos webhooks), o cliente e o resumo das tentativas em attemptSummary: quem decidiu, o caminho percorrido e a ultima recusa. lastDecline aparece mesmo quando o pagamento terminou aprovado - e ela que mostra o que o fallback recuperou (Pix e boleto, ou cartao com token de bandeira proprio: o cartao comum nao troca de adquirente). technical: true indica falha tecnica do conector, sem codigo do emissor.

Indicadores do periodo

curl "http://localhost:3333/v1/payments/summary?from=2026-10-01T03:00:00Z" \
  -H "Authorization: Bearer $MINSTREL_API_KEY"

Sem from, valem os ultimos 30 dias; sem to, ate agora. O periodo pode ter no maximo 400 dias. A resposta compara com o periodo anterior de mesma duracao, deslocado em dias inteiros: "hoje ate agora" compara com "ontem ate a mesma hora", e nao com as ultimas horas de ontem.

Resposta (resumida):

{
  "object": "payment_summary",
  "period": {
    "from": "2026-10-01T03:00:00.000Z",
    "to": "2026-10-15T15:00:00.000Z",
    "timezone": "America/Sao_Paulo",
    "granularity": "day"
  },
  "current": {
    "count": 1840,
    "approved": 1602,
    "declined": 221,
    "inProgress": 17,
    "approvalRate": 8788,
    "capturedVolume": 23918450,
    "capturedCount": 1577,
    "averageTicket": 15167,
    "refunds": { "count": 12, "amount": 180400 },
    "recovered": {
      "count": 96,
      "amount": 1402300,
      "fallback": { "count": 81, "amount": 1190500 },
      "retry": { "count": 15, "amount": 211800 }
    }
  },
  "previous": { "count": 1712, "approved": 1466, "declined": 230, "approvalRate": 8644 }
}

Como ler cada numero:

• Aprovado e todo pagamento que o emissor aprovou em algum momento: authorized, captured, partially_captured, partially_refunded, refunded, disputed, charged_back e voided. A taxa mede a decisao do emissor, nao o que aconteceu com a venda depois.
• approvalRate vem em basis points (8788 = 87,88%): aprovados sobre aprovados mais recusados. Pagamentos em andamento ficam fora da conta, e sem nenhuma decisao no periodo a taxa e null.
• capturedVolume soma o valor capturado, em centavos; averageTicket e a media por pagamento capturado.
• recovered e a venda salva por uma nova tentativa, em duas origens que nunca se somam duas vezes: fallback (aprovado numa tentativa depois da primeira, no mesmo pagamento) e retry (aprovado de primeira, numa fatura cuja cobranca anterior tinha sido recusada).
• refunds conta os estornos concluidos pela data do estorno, nao da venda.

A resposta traz ainda series (por hora ate 2 dias de periodo, por dia acima disso, no fuso da organizacao e com os intervalos vazios zerados), connectors (desempenho por conta de conector, contado por tentativa: aprovou, recusou, falha tecnica, recuperou e latencia media) e facets.connectorAccounts, as contas que servem de filtro na listagem.

Detalhe de um pagamento

GET /v1/payments/:id traz tudo o que explica o caminho da transacao:

O cartao vem so com dados de exibicao (bandeira, BIN, ultimos 4 digitos, validade, tipo e emissor) - nunca token, nunca numero.

Tentativas

trigger diz por que a tentativa aconteceu: initial, fallback_reversible (recusa reversivel na anterior) ou fallback_connector_failure (falha tecnica na anterior). connector continua sendo o slug; a conta completa vem em connectorAccount, com removed: true quando ela foi removida depois.

Por que o roteamento parou

E a pergunta que todo operador faz diante de uma recusa: "por que nao tentou outro adquirente?". A resposta esta em routing.stopReason:

Acoes possiveis

actions.capture, actions.void, actions.refund e actions.simulate trazem available e, quando a acao nao esta disponivel, o motivo em reason. Captura e estorno disponiveis trazem tambem maxAmount. No Pix e no boleto, void cancela a cobranca aguardando pagamento e simulate e a simulacao do banco, so no sandbox. Em requires_payment_method, void cancela o pagamento que ainda nao recebeu o cartao; capturar e estornar nao se aplicam.

Desenhe os botoes da sua interface a partir daqui: so o servidor sabe o que o conector que aprovou consegue fazer.

Linha do tempo

events lista os eventos do pagamento em ordem (ate 200), com status, previousStatus e o resumo das entregas de webhook de cada um (total, succeeded, failed, pending). Para o payload completo, use GET /v1/events/:id - veja Webhooks.

Confirmar um pagamento sem cartao

Um pagamento de cartao criado sem card e sem paymentMethodId nasce em requires_payment_method e so avanca quando recebe o token de uso unico do adquirente, gerado no navegador do portador. A confirmacao tem dois caminhos:

curl -X POST https://api.minstrel.com.br/v1/payments/pay_01HQ.../confirm   -H "Authorization: Bearer $MINSTREL_API_KEY"   -H "Idempotency-Key: confirma-pedido-1234"   -H "Content-Type: application/json"   -d '{ "card": { "token": "3f9a...", "brand": "visa", "last4": "1111" }, "saveCard": false }'

• card.token e o token de uso unico do adquirente; brand, bin e last4 sao opcionais. Nunca envie o numero do cartao: a API o recusa com 422 raw_card_data_rejected.
• saveCard: true exige customerId no pagamento e e o consentimento do portador para guardar o cartao e cobra-lo depois. Sem ele, o token e de uso unico e o cartao nunca mais pode ser cobrado.
• Aprovada a autorizacao, o pagamento segue o caminho de qualquer cartao (authorized ou captured, conforme captureMethod). Recusada, o pagamento termina failed: nesta versao nao ha nova tentativa no mesmo pagamento; crie outro.
• Um pagamento que nao esta mais em requires_payment_method (ja confirmado, cancelado ou vencido) nao pode ser confirmado de novo.

O passo a passo completo, com a pagina do portador, esta em Checkout transparente.

Capturar

Para pagamentos criados com captureMethod: "manual", que ficam authorized:

curl -X POST http://localhost:3333/v1/payments/pay_01HQ.../capture \
  -H "Authorization: Bearer $MINSTREL_API_KEY" \
  -H "Idempotency-Key: captura-pedido-1234" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 12000 }'

• Sem amount, captura o total autorizado.
• Valor menor que o autorizado e captura parcial: o pagamento fica partially_captured e o restante nao pode ser capturado depois.
• As duas emitem payment.captured; confira status e capturedAmount.
• A captura total leva as instrucoes de split gravadas; a parcial segue sem split.

Prazo da pre-autorizacao

Uma autorizacao sem captura reserva o limite do portador, e a bandeira so deixa capturar dentro de um prazo. Assim que a autorizacao e aprovada sem captura, o pagamento ganha authorizationExpiresAt, calculado pela regra do adquirente e da bandeira:

A regra da Cielo vem do changelog de julho de 2026. Onde a bandeira nao e conhecida, vale o prazo mais curto: errar para menos antecipa uma captura, errar para mais deixaria uma venda aprovada vencer.

• Captura adiada no fluxo. O no Capturar em modo delayed agenda a captura (captureScheduledAt) e o worker a executa. Se o atraso pedido passar do prazo, a captura e marcada para 1 hora antes do vencimento. Veja Fluxos.
• Aviso 24 horas antes. O worker aplica a configuracao Pre-autorizacao perto de vencer da conta do conector (Plugins, conta, Recursos): notify (padrao) so avisa, capture captura o valor autorizado e void cancela a autorizacao. Nos tres casos sai o evento payment.authorization_expiring, com o prazo em authorizationExpiresAt e a acao em expiryAction.
• Depois do prazo a captura nao e mais possivel: a API responde 409 payment_not_capturable, e actions.capture.reason mostra authorization_expired.

Cancelar uma autorizacao

O cancelamento (void) desfaz uma autorizacao que ainda nao foi capturada. O limite do portador e liberado sem lancamento na fatura dele - por isso e a operacao certa para uma pre-autorizacao que nao vai virar venda. Estornar depois de capturar custa tarifa e aparece no extrato do cliente.

curl -X POST http://localhost:3333/v1/payments/pay_01HQ.../void \
  -H "Authorization: Bearer $MINSTREL_API_KEY" \
  -H "Idempotency-Key: cancela-pedido-1234" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Pedido cancelado antes do envio" }'

O pedido vai ao mesmo conector que autorizou - so ele conhece a transacao, e nao ha fallback. O pagamento fica voided e o evento payment.voided leva o motivo em data.object.voidReason. Nao coloque dado sensivel no motivo.

No Pix e no boleto aguardando pagamento, o mesmo endpoint cancela a cobranca no banco e o pagamento fica canceled, com payment.canceled. Veja Pix e boleto.

Em requires_payment_method (o cartao ainda nao foi digitado), o mesmo endpoint cancela o pagamento: ele fica canceled e a pagina do portador nao consegue mais confirma-lo. Nada chegou ao adquirente, entao nao ha limite a liberar.

Estornar

curl -X POST http://localhost:3333/v1/payments/pay_01HQ.../refund \
  -H "Authorization: Bearer $MINSTREL_API_KEY" \
  -H "Idempotency-Key: estorno-pedido-1234-1" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 5000, "reason": "Devolucao parcial", "metadata": { "ticket": "SAC-991" } }'

• Sem amount, estorna todo o saldo estornavel: capturado menos ja estornado.
• Varios estornos parciais sao permitidos, ate o valor capturado. O pagamento passa a partially_refunded e, quando o saldo zera, a refunded, com os eventos payment.partially_refunded e payment.refunded.
• O estorno vai ao conector que aprovou a venda. Se o adquirente recusar ou falhar, ele fica registrado em refunds no detalhe, com status: failed e o motivo em failureReason. Conector sem estorno recusa antes, sem registrar nada.
• Pagamento em disputa nao e estornado. Com chargeback em andamento, o portador ja pediu o dinheiro ao emissor: estornar devolveria duas vezes. Responda a disputa.
• Pix e estornado pela devolucao do PSP que recebeu. Boleto nao tem estorno automatico: a resposta e 409 com a orientacao de devolver por Pix ou TED e registrar a devolucao.

Idempotencia nas operacoes

Captura, cancelamento, estorno e a decisao de revisao manual aceitam o header Idempotency-Key, como a criacao do pagamento. Use sempre: a repeticao de uma chamada perdida por timeout devolve a resposta original em vez de capturar ou estornar duas vezes. A mesma chave com corpo diferente responde 409 idempotency_key_reused. Resposta de erro nao fica memorizada: depois de uma falha, a mesma chave pode ser usada de novo. Veja o catalogo de erros.

Eventos

Os mesmos dados chegam por webhook, assinados.