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 a fonte de verdade para um pagamento. Quando o pagamento é incluído na resposta do pedido, 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 atualizações assíncronas do provedor, 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.
Escolha o fluxo de pagamento#
Pagamentos com cartão e métodos de pagamento alternativos não seguem as mesmas ações ou estados de processamento do cliente. Comece com o fluxo que corresponde ao método de pagamento, e retorne aqui para referências de status e transições canônicas.
Os diagramas nessas páginas mostram o caminho normal para o comerciante. Transições diretas, tentativas, caminhos de reconciliação e ramificações específicas do provedor permanecem autoritativos no referência de transição validada.
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. | Recupere o resultado oficial após o processamento da atualização pelo provedor; não tente novamente prematuramente. |
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#
- Recupere o pagamento oficial antes de alterar o estado local.
- Identifique o pagamento e a operação relacionada antes de aplicar a atualização.
- Armazene o status informado, o valor confirmado, a moeda, o identificador da operação e as referências do fornecedor.
- Processar a recuperação repetida e as tentativas do cliente de forma idempotente. Não dedupe apenas com base no 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 timeout HTTP, perda de resposta ou atualização atrasada do provedor não comprovam 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.