Transações

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.

Novas cobranças estão sujeitas à proteção de transações. O guia explica 429, Retry-After, fingerprints e relatórios de padrões suspeitos.

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 (volta preenchido se o pagamento reabriu depois de uma recusa reversivel). 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). No checkout transparente, cada cartao que o portador tenta no mesmo pagamento gera as suas tentativas, em sequencia (attemptNumber continua de onde parou) e todas ficam no detalhe, com o motivo da recusa de cada uma. connector continua sendo o slug; a conta completa vem em connectorAccount, com removed: true quando ela foi removida depois.

Autenticacao 3DS

Quando o fluxo tem o no Autenticacao 3DS e o pagamento e confirmado no navegador pelo SDK, a transacao passa por duas etapas visiveis na API:

1. A pausa. No no, o pagamento fica requires_action e nextAction traz type: "three_ds", com o provedor (cielo_mpi ou, no sandbox, minstrel_sandbox), o ambiente, o modo (challenge, frictionless ou data_only) e o prazo (expiresAt). Quem o consome e o SDK; o seu servidor nao precisa fazer nada.
2. O resultado. O SDK roda o script de 3DS da Cielo na pagina do portador e envia o resultado a POST /v1/public/payments/:id/three-ds (rota publica, com o header Minstrel-Client-Secret, como as demais rotas do checkout transparente). O fluxo continua do no e a autorizacao segue com a autenticacao.

Depois disso, threeDs no detalhe do pagamento registra o que aconteceu. O CAVV e o XID nunca sao gravados.

{
  "id": "pay_01M5...",
  "methodType": "debit_card",
  "threeDs": { "status": "authenticated", "eci": "05", "version": "2.2.0" }
}

eci e o indicador que a bandeira devolveu; ele diz quem responde pela fraude. Mastercard 01 ou 02, e Visa, Elo e Amex 05 ou 06, transferem a responsabilidade ao emissor. O Data Only (Mastercard 04, Visa 07) nao transfere. version e a versao do protocolo 3DS (2.2.0 na Visa e Mastercard, 2.1.0 na Elo e Amex). threeDs e null quando o pagamento nao passou pelo no de 3DS: fluxo sem o no, Pix e boleto.

No painel, o detalhe da transacao mostra o cartao Autenticacao 3DS com a situacao (Pendente, Autenticado, Data Only, Nao autenticado ou Indisponivel), o ECI com o que ele significa para a responsabilidade, e a versao.

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). Quando o evento tem explicacao, ela vem junto: error (code, message e a conta envolvida, por exemplo no payment.checkout_not_configured), decline (motivo e reversibilidade da recusa) e checkout (tentativas de cartao usadas e, se o pagamento acabou, endedBy). Para o payload completo, use GET /v1/events/:id - veja Webhooks.

Split no pagamento

Um pagamento criado com splits (ou que passa por um no Split do fluxo) traz uma parcela por recebedor em splits. A divisao e executada no adquirente, e a parcela acompanha o que ele faz:

• So ha autorizacao numa conta que executa o split, com todos os recebedores registrados nela. Se nenhuma candidata serve, o pagamento nao e autorizado e a resposta e split_not_supported, explicando o que falta. Veja Quando o pagamento nao e autorizado e o catalogo de erros.
• Captura e estorno dividem o valor entre as parcelas: veja Capturar e Estornar.
• Os eventos payment.captured, payment.voided, payment.refunded e payment.partially_refunded levam as parcelas no data.object.

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 por motivo reversivel, o pagamento volta para requires_payment_method (evento payment.attempt_declined) e aceita outro cartao no mesmo pagamento: gere outro token e confirme de novo, com outra Idempotency-Key. Recusa irreversivel, o fim das tentativas (padrao: 3 cartoes) ou o prazo vencido terminam failed (payment.failed); ai, crie outro pagamento. Veja Recusa e nova tentativa.
• Um pagamento que nao esta mais em requires_payment_method (ja confirmado, encerrado, cancelado ou vencido) nao pode ser confirmado de novo.
• A confirmacao pelo servidor nao autentica o portador. Nao ha ninguem na pagina para o desafio, entao o no de 3DS nao roda nela. Por isso o cartao de debito, que exige 3DS, so existe pelo SDK.

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.
• Num pagamento com split, a captura divide o valor entre os recebedores: a total leva as parcelas gravadas na autorizacao, e a parcial divide o valor capturado na mesma proporcao do autorizado (a parte da conta principal entra como mais um peso, e a soma fecha ao centavo). Cada parcela guarda o que foi capturado em capturedAmount, e o adquirente informa de novo o liquido. Se um recebedor foi movido para outra conta depois da autorizacao, a captura nao e enviada e responde split_not_supported.
• Com o pagamento em revisao de fraude (fraudReview.status = "pending") a captura vale, mas passa a frente do provedor: a revisao fecha como merchant_decided.

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. Com o pagamento em revisao de fraude, capture vira notify: nunca se captura sozinho o que o antifraude ainda analisa.
• Depois do prazo a captura nao e mais possivel: a API responde 409 payment_not_capturable, e actions.capture.reason mostra authorization_expired.

Analise de fraude da adquirente

Quando a conta usa o antifraude embutido da Cielo, a analise de fraude vai dentro da autorizacao e o pagamento ganha o que esta nesta secao. Ela so roda em cartao de credito, com o portador presente (initiator: "customer"), numa conta com o recurso ligado e numa rota que nao a dispensou (Fluxos). Fora disso, nada muda no pagamento.

Dados para a analise

Dois campos opcionais na criacao do pagamento (POST /v1/payments) alimentam a analise. Sem eles ela roda com o que o Minstrel ja sabe (o cliente do customerId, o valor, as parcelas e o cartao), mas com menos sinais.

items descreve o pedido (ate 100):

fraudAnalysis leva o resto:

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,
    "customerId": "cus_01M5...",
    "externalId": "pedido-1234",
    "items": [{ "sku": "CAM-001", "name": "Camiseta preta", "quantity": 1, "amount": 14990 }],
    "fraudAnalysis": { "shipping": { "method": "two_day" } }
  }'

Nada aqui e dado de cartao: a barreira da API inspeciona estes campos como qualquer outro do corpo, e um numero de cartao num valor de merchantDefinedFields responde 422 raw_card_data_rejected. Os itens e o que voce enviou ficam no pagamento e aparecem no detalhe (orderItems e fraudAnalysis), o que ajuda a explicar uma analise skipped.

O nome, e-mail, documento e telefone do cliente tambem sao obrigatorios para a analise (e o nascimento, na ClearSale). Eles vem do cadastro do cliente: veja a tabela de dados do cliente. Faltando algum, a analise nao e enviada e a autorizacao segue (skipped).

O resultado da analise

Cada analise vira um item de antifraud no detalhe do pagamento, com origin: "acquirer" (as do no Antifraude do fluxo vem com origin: "flow_node") e o evento antifraud.assessment_completed. providerStatus diz o que o provedor respondeu:

Alem disso o item traz score (de 0 a 100, quando o provedor o devolve), triggeredRules (os codigos de fator da Cybersource, como B, D, R), providerReference e rawResponse. O rawResponse guarda so o que explica a decisao (status, provider, skippedReason, missingFields, factorCodes, score): o corpo inteiro da Cielo ecoa dados do comprador e nao e guardado.

Recusa pelo antifraude

Quando o provedor recusa, a venda nao e cobrada: o pagamento termina failed, com o codigo proprio ANTIFRAUD_REJECT.

{
  "status": "failed",
  "decline": {
    "reason": "SUSPECTED_FRAUD",
    "reversibility": "IRREVERSIBLE",
    "retryAction": "DO_NOT_RETRY"
  },
  "attempts": [{ "connector": "cielo", "rawResponseCode": "ANTIFRAUD_REJECT" }]
}

• E um codigo do Minstrel, fora da tabela ABECS e da tabela da Cielo (ela aparece em Codigos de recusa, entre os codigos proprios da Cielo). O emissor pode nem ter sido consultado.
• E irreversivel e nao ha configuracao que mude isso. O pagamento nao e retentado nem tentado em outra conta: contornar a analise e o que ela existe para impedir. Peca outro meio de pagamento ou revise o pedido (e as regras no painel do provedor). Veja Retentativa.
• Chega por tres caminhos, todos com o mesmo resultado: a Cielo aborta a venda antes do emissor (AnalyseFirst), cancela a autorizacao depois dele (AuthorizeFirst) ou aborta por fraude sem devolver o bloco da analise. O Merchant Advice Code do emissor nao e repassado, para nao sugerir retentativa.
• Se o antifraude esta fora do ar, nao e recusa: a Cielo aborta a venda, o Minstrel trata como falha tecnica do conector (connector_unavailable, retentavel) e o cartao nao e punido por um problema do parceiro.
• Recusa com a venda ainda autorizada. Se o veredito e reject mas a Cielo manteve a autorizacao (a conta analisa qualquer que seja o veredito, ou o cancelamento automatico dela falhou), o pagamento nao vira failed: fica authorized em revisao, e o Minstrel o cancela com o motivo de risco alto (Reason: "HighRisk", que a Cielo exige desde 17/04/2026). Termina voided, com a revisao rejected.
• Capturada apesar da recusa. Se a Cielo ja capturou, o pagamento segue captured, a analise fica registrada como reject e o Minstrel nao estorna sozinho: a decisao de devolver e sua.

Revisao de fraude

O provedor pode nao decidir na hora (review): um analista decide depois, no painel do provedor (na Cybersource, o Enterprise Business Center, Aceitar ou Rejeitar). Enquanto isso o pagamento fica authorized, sem captura, mesmo com captureMethod: "automatic", e ganha fraudReview:

{ "id": "pay_01HQ...", "status": "authorized", "fraudReview": { "status": "pending" } }

fraudReview e null quando nao houve revisao.

pending tambem aparece quando o provedor aceitou mas a captura que voce pediu ainda nao foi confirmada pela Cielo, e quando a analise terminou sem decisao (unfinished, unknown): em ambos a venda fica segura ate o Minstrel confirmar o desfecho.

Ciclo da revisao

A Cielo avisa que o antifraude mudou de status, mas nao diz para qual. Por isso um worker do Minstrel pergunta a Cielo, venda por venda, a cada FRAUD_REVIEW_POLL_INTERVAL_MINUTES (padrao 10, minimo 1) ate o provedor decidir. A decisao leva ate esse intervalo para aparecer; o aviso da Cielo ainda nao e usado para acelerar. O worker age conforme o que a Cielo informa:

Toda mudanca e condicionada a venda ainda estar authorized e pending. Se voce decidiu no meio, a sua decisao vale e o worker nao desfaz nem duplica nada.

• Voce pode decidir antes. capture e void valem com a revisao pendente e a fecham como merchant_decided: voce passou a frente do provedor, e capturar pode cobrar uma venda que ele ainda recusaria.
• O no Capturar espera. O no Capturar do fluxo, imediato ou adiado, nao captura enquanto a venda esta pending: a captura roda depois do aceite e nunca na recusa.
• O vencimento nunca captura sozinho. A acao Pre-autorizacao perto de vencer capture vira notify enquanto a revisao esta pendente, porque capturar anularia a analise. void segue como configurado. A janela e a do prazo da pre-autorizacao (7 dias na Mastercard, 15 nas demais): peca ao analista que decida antes dela.
• Captura manual. Na Cielo, a captura manual nao captura no aceite. O Minstrel so o enxerga se a consulta da venda devolver a analise atualizada, ponto que esta sendo validado com a Cielo (veja Antifraude da Cielo). A recusa aparece de qualquer forma, porque a Cielo cancela a venda.
• Ao fim, o evento payment.fraud_review_resolved avisa o resultado.

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.

Com o pagamento em revisao de fraude, o cancelamento vale e fecha a revisao como merchant_decided; a decisao do provedor, se vier depois, nao muda nada.

Num pagamento com split, cancelar a autorizacao desfaz a venda inteira: o adquirente devolve a parte de cada recebedor sozinho, e o Minstrel nao manda divisao nenhuma. O restante de cada parcela fica registrado em refundedAmount, e o evento payment.voided leva as parcelas.

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.
• Pagamento com split. O estorno total (nada devolvido antes e valor igual ao capturado) vai sem divisao: o adquirente desfaz tudo. O parcial divide o valor pelo que ainda resta em cada parcela, com a parte da conta principal como mais um peso, e o adquirente recebe so a parte dos recebedores - o resto sai da parte do lojista principal. A soma fecha ao centavo, e refundedAmount de cada parcela acumula os estornos. Na Cielo, so cabe um estorno parcial por transacao a cada 24 horas: o segundo dentro do prazo e recusado e fica failed.
• 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.