Fluxo de Pagamento & Statuses
Entenda cada status de pagamento público, as operações que o produzem e as transições que os comerciantes devem realizar.
Nesta página
Uso payment.data.status como fonte da verdade para um pagamento. Quando o pagamento for encerrado em uma resposta do pedido ou webhook, leia order.payment.data.status. O contêiner do pedido não altera o significado do status do pagamento.
Avalie sempre o status juntamente com os valores confirmados e o histórico da operação. Uma solicitação de API aceita ou HTTP 2xx resposta pode significar que uma operação assíncrona foi iniciada; nem sempre significa que o dinheiro foi movimentado.
Para decisões de fraude, consulte Fluxo de trabalho e status de fraude. Para entrega e verificação de notificação, consulte Webhooks da DEUNA.
Famílias de status#
Os rótulos abaixo explicam como os lojistas devem lidar com os valores; eles não são campos adicionais da API.
| Família | Status | Tratamento do comerciante |
|---|---|---|
| Aguardando ação ou confirmação | pending, pending_3ds, processing, authorizing, capturing, partial_capturing, voiding, refunding, partial_refunding, manual_review | Mantenha o pagamento sem solução. Conclua qualquer ação necessária do cliente e aguarde ou recupere um resultado oficial. |
| Confirmado e ainda operável | processed, authorized, captured, partial_captured, partial_refunded | Registre o resultado financeiro confirmado. Uma captura, reembolso ou anulação qualificada posterior ainda pode alterar o status. |
| Sem sucesso, mas recuperável | denied | Não cumpra esta tentativa. Uma nova tentativa ou decisão de encaminhamento pode mover o mesmo pagamento de volta para um estado ativo, portanto, não modele denied como terminal. |
| Cancelamento aguardando resolução financeira | cancelled | Inspecione a atividade financeira anterior. Um reembolso ou anulação ainda pode ocorrer. |
| Terminais | voided, refunded, expired | A máquina principal de estado de pagamento não tem transição de saída desses valores. |
partial_captured e partial_refunded pode ser o último estado exigido pelo processo de negócios do comerciante, mesmo que não sejam status de API de terminal. Manter a situação real e os valores acumulados; nunca substitua um status parcial localmente por captured ou refunded.
Ciclo de vida de ponta a ponta#
Esta visão geral mostra as principais famílias de ciclo de vida. Transições diretas e ramificações específicas do provedor estão listadas na referência de transição validada.
3DS e OTP
pending_3ds significa que a autenticação está incompleta. O sucesso da autenticação apenas permite que o fluxo de pagamento continue; isso não prova que a compra ou autorização foi bem-sucedida. Após o desafio, aguarde processed, authorizedou outro status de pagamento relatado.
Alguns adaptadores de processador usam pending_otp internamente. O processamento de pagamentos atual normaliza esse resultado para o público pending e fornece os metadados necessários para a próxima ação. Se um relatório ou filtro de pesquisa mais antigo contiver pending_otp, trate isso como uma espera pela ação do cliente – e não como um pagamento bem-sucedido.
Autorização, captura e anulação#
O processamento de pagamentos em duas etapas reserva os fundos primeiro e os coleta depois. authorized não é dinheiro capturado.
A máquina de estados também permite que um processador relate captured, partial_captured, ou voided diretamente, sem primeiro expor o status “-ing” correspondente. As notificações são instantâneos do estado autoritativo, não uma sequência garantida de evento por evento.
Escolha compra em uma única etapa ou autorização/captura em duas etapas no nível de conexão do processador. A elegibilidade para captura e anulação também depende do processador, do valor restante, do prazo e da configuração do comerciante. Seu DEUNA TAM pode confirmar comportamento compatível.
Para modos de captura parcial e final_capture, veja MPC — Múltiplas Capturas Parciais. O sucesso Anular API retorna HTTP 204 No Content; use o estado de pagamento posterior quando o processador for concluído de forma assíncrona.
Reembolsos e cancelamento#
Os reembolsos devolvem os fundos coletados. Os vazios liberam uma autorização. Eles não são intercambiáveis.
Um reembolso falhado pode restaurar o estado financeiro anterior (processed, captured, ou partial_captured). Guarde o pagamento bem-sucedido e a tentativa de reembolso malsucedida separadamente. Veja MPR – Reembolsos Parciais Múltiplos para modos de reembolso parcial nativos e agregados por DEUNA.
Fluxo de trabalho do APM#
Métodos de pagamento alternativos geralmente começam em pending, pode expor processing, e complete em processed, denied, cancelled, ou expired. Algumas conexões APM suportam autorização e captura, portanto, os mesmos status de autorização podem ser aplicados.
O prazo de pagamento depende do método e da configuração. Não infira expired do tempo do navegador ou de um retorno de redirecionamento; espere até que DEUNA relate isso.
Referência de status de pagamento#
Os valores são strings minúsculas com distinção entre maiúsculas e minúsculas.
| Estado | Significado | O que o comerciante deve fazer |
|---|---|---|
pending | Pagamento criado; a ação do cliente, o roteamento ou a confirmação do fornecedor ainda podem ser necessários. | Siga next_action ou instruções de método e manter o atendimento bloqueado. |
pending_3ds | A autenticação 3DS está incompleta. | Conclua o desafio e avalie o status do pagamento resultante. |
processing | Uma compra ou pagamento APM está em andamento. | Aguarde um webhook ou recupere o resultado oficial antes de tentar novamente. |
processed | Uma compra em uma única etapa concluída. | Registrar o sucesso e aplicar a política de atendimento; reembolsos podem ocorrer. |
authorizing | A solicitação de autorização está em andamento. | Não trate os fundos como capturados ou reservados ainda. |
authorized | Os fundos foram reservados com sucesso. | Capturar ou anular quando elegível. |
capturing | Uma captura completa está em andamento. | Acompanhe a operação e aguarde a confirmação. |
partial_capturing | Uma captura parcial está em andamento. | Mantenha separados os valores capturados pendentes e confirmados. |
partial_captured | Uma quantia parcial foi capturada. | Registre o valor confirmado e a elegibilidade restante de captura/reembolso. |
captured | Captura concluída. | Registrar o valor arrecadado; reembolsos podem ocorrer. |
voiding | A liberação de uma autorização está em andamento. | Aguarde voided ou um resultado restaurado/com falha. |
voided | A autorização foi liberada. | Registre a conclusão do terminal. |
refunding | Um reembolso total ou do saldo restante está em andamento. | Aguarde a confirmação; a aceitação da solicitação não é prova de fundos devolvidos. |
partial_refunding | Um reembolso parcial está em andamento. | Acompanhe os valores reembolsados pendentes e confirmados separadamente. |
partial_refunded | Um reembolso parcial concluído. | Registre o valor e o saldo reembolsável restante. |
refunded | O saldo reembolsável representado pelo ciclo de vida foi devolvido. | Registre a conclusão do terminal. |
manual_review | O pagamento é retido por uma decisão de risco. | Mantenha o cumprimento bloqueado até que o pagamento receba um novo status. |
denied | A tentativa atual foi rejeitada. | Não cumpra. Preservar a razão; uma nova tentativa configurada pode entrar novamente no fluxo ativo. |
cancelled | O método ou comerciante cancelou o pagamento. | Verifique se um reembolso ou anulação ainda deve ser concluído. |
expired | A janela de conclusão permitida foi fechada antes do término do pagamento. | Registre a conclusão do terminal; crie um novo pagamento se o cliente tentar novamente. |
not_authorized e failed são usados por adaptadores de processador ou de nível de operação, mas não são valores canônicos no núcleo payment.data.status gráfico de transição. Não mescle status de operação do provedor, status de operação de captura/reembolso ou marcadores de tempo limite local no campo de status de pagamento.
Referência de transição validada#
As transições a seguir correspondem à máquina de estado principal do Payments. A entrega repetida do mesmo estado é omitida, exceto quando for explicitamente aceita. Uma transição listada não garante que cada processador ou método de pagamento suporte a operação correspondente.
| Estado atual | Próximos status permitidos |
|---|---|
pending | pending, pending_3ds, authorizing, authorized, processing, processed, cancelled, voided, denied, manual_review, expired |
pending_3ds | pending_3ds, authorizing, authorized, processing, processed, cancelled, denied, manual_review, expired |
processing | processed, cancelled, denied, manual_review, partial_refunding, refunding, partial_refunded, refunded |
processed | refunding, refunded, partial_refunding, partial_refunded, voided |
authorizing | authorized, captured, voiding, cancelled, denied, manual_review |
authorized | capturing, captured, partial_capturing, partial_captured, voiding, voided, cancelled |
capturing | captured, denied; para fluxos de recuperação de captura pendentes suportados: authorized, partial_capturing, partial_refunding, partial_refunded, refunding, refunded |
partial_capturing | capturing, partial_captured, captured, denied |
partial_captured | captured, partial_refunding, partial_refunded, refunding, refunded |
captured | partial_refunding, partial_refunded, refunding, refunded |
voiding | voided, denied, authorized |
refunding | refunded, partial_refunded, voided, processed, captured |
partial_refunding | partial_refunded, refunding, refunded, denied, processed, captured, partial_captured |
partial_refunded | partial_refunding, refunding, refunded |
manual_review | processed, captured, denied |
denied | pending, pending_3ds, processing, processed, authorizing, authorized, manual_review, denied |
cancelled | refunded, voided |
voided | Nenhum (terminal) |
refunded | Nenhum (terminal) |
expired | Nenhum (terminal) |
A reconciliação do arquivo de liquidação pode permitir transições de recuperação adicionais enquanto a DEUNA reconcilia um resultado de processador externo. Estas transições não alteram o significado público dos estatutos.
Alguns perfis de processadores podem aceitar um reembolso enquanto uma captura assíncrona ainda está pendente. Nesse fluxo, a DEUNA pode cancelar ou reverter a captura pendente e reembolsar a autorização original, o que permite as transições adicionais listadas para capturing. Não inicie este fluxo, a menos que a DEUNA tenha confirmado o suporte para a conexão do processador.
Lide com atualizações com segurança#
- Verifique cada notificação com o método de verificação de webhook configurado.
- Identifique o pagamento e a operação relacionada antes de alterar o estado local.
- Armazene o status informado, o valor confirmado, a moeda, o identificador da operação e as referências do fornecedor.
- Processe notificações repetidas de forma idempotente. Não desduplique apenas por status.
- Mantenha o cumprimento bloqueado para estados transitórios, de revisão ou desconhecidos.
- Reconcilie resultados ausentes ou conflitantes por meio do fluxo de recuperação de pagamentos compatível.
Um tempo limite de HTTP, uma resposta perdida ou um webhook atrasado não provam denied ou expired. Siga orientação de solicitação idempotente, recupere o pagamento e diferencie uma nova tentativa da mesma solicitação de uma nova tentativa de pagamento.